DEVESC_ACQUIREFB

GreEscape DEVESC_ACQUIREFB reserves a video adapter by acquiring the necessary internal Presentation Manager driver resources so that the calling routine has sole access to the video frame buffer and bank-switching registers. No use of the adapter by the Presentation Manager or any other process is allowed while the adapter is reserved.

Simulation support: This function is mandatory for display drivers supporting software motion video. For other drivers, it is simulated by a handling routine in the graphics engine.

Syntax

GreEscape(hdc, ICODE, lInCount, pbInData, plOutCount, pbOutData);

Parameters

hdc (HDC) - input: Device context handle.

ICODE (LONG) - input: DEVESC_ACQUIREFB escape code.

lInCount (LONG) - input: Number of bytes pointed to by pbInData.

pbInData (PBYTE) - input

Pointer to ACQUIREFB structure containing:

fAFBFlags: Only one flag is currently defined. AFB_SWITCH is set if the ulBankNumber field contains the value of a bank switch, which is to be active when the call returns. AFB_SWITCH should not be set for apertures that are not bank-switched.
ulBankNumber: This is an integer value specifying the initial video memory bank index; 0 (zero) for the first bank, 1 (one) for the second bank, and so on.
rctlRegion: This field gives the rectangle, in device coordinates, that will be used for BLTing. The device driver will perform Exclude processing to hide the mouse cursor if it is in this area. If it is hidden when DEVESC_DEACQUIREFB is called, it will be restored.

plOutCount (PLONG) - input: The handling routine ignores this parameter.

pbOutData (PLONG) - input: The handling routine ignores this parameter.

Returns

rc (LONG) - returns

Return Code.

The handling routine returns:

DEV_OK: Successful
DEVESC_NOTIMPLEMENTED: Escape is not implemented for the specified code
DEVESC_ERROR: Error

Remarks

The escape is intended to allow the calling routine to access memory directly (causing bank switches as needed), without concern for another process changing the bank registers. The device drivers are alerted that the software motion video component is using the bank address switch DevEscape.

This escape is used in conjunction with DEVESC_SWITCHBANK and DEVESC_DEACQUIREFB. When used, the handling routine saves the necessary state to allow the calling routine to access video memory directly and use DEV_SWITCHBANK. After the calling routine completes its access of video memory it must use DEVESC_DEACQUIREFB to restore the adapter state, and allow other processes to access the adapter.

If the adapter cannot be acquired, the handling routine immediately responds with DEVESC_ERROR.

Source Code Sample

Declaration:

#define INCL_GRE_DEVICE
#include <os2.h>

HDC      hdc;         /* Device context handle. */
LONG     ICODE;       /* DEVESC_ACQUIREFB escape code. */
LONG     lInCount;    /* Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /* Pointer to ACQUIREFB structure. */
PLONG    plOutCount;  /* The handling routine ignores this parameter. */
PLONG    pbOutData;   /* The handling routine ignores this parameter. */
LONG     rc;          /* Return Code. */

rc = GreEscape(hdc, ICODE, lInCount, pbInData,
       plOutCount, pbOutData);