COMMANDS

DCICreatePrimarySurface

A DCI client makes the GDI Escape call with these parameters to a DCI Provider to request access to the primary display surface. The DCI Provider returns access to the entire surface area; it is the DCI Client's responsibility to position the image at the appropriate coordinate location.

uint Escape (hdc, DCICOMMAND, sizeof(DCICREATEINPUT),
(LPDCICREATEINPUT)lpInput, LPDCIPRIMARY *lpSurface);

hdc	Device context being queried for DCI support.
lpInput	DCI Client provided DCICREATEINPUT structure with input parameters.
lpSurface	DCI Client provided DWORD for the DCI Provider to put a far pointer to the DCIPRIMARY structure to be returned. This structure must be allocated by the DCI Provider.

INPUT PARAMETERS

A DCI Client issuing this DCI Command will set the following fields of the DCICREATEINPUT structure:

dwCommand	Set to the constant DCICREATEPRIMARYSURFACE.
dwVersion	Set to 0x0100 for DCI 1.0.

RETURNS

A DCI Provider responding to this DCI Command must set the following fields of the DCIPRIMARY structure it returns:

dwSize	DCI Provider must provide the size of the structure created. This size must be no smaller than sizeof(DCIPRIMARY). It can be larger, should the DCI Provider need to maintain instance data.
dwDCICaps	At a minimum, DCI_PRIMARY \| DCI_VISIBLE must be set. DCI_1632_ACCESS must be set if the surface uses bank-switched memory and will be accessed via a VFlatD linear-access mechanism.
dwCompression	Access is being requested to the default display driver mode. The DCI provider must provide the FOURCC of the current display format. This field must be set to BI_BITFIELDS, if the current display mode is a nonstandard RGB mode If the format of the frame buffer is different from the current default display driver mode (i.e., GDI is passing 24-bit RGB data, but the display driver is converting this to 16-bit RGB data before writing the data to the frame buffer), then the provider should return the format of the frame buffer.
dwMask	If the current display mode is a nonstandard RGB mode, the DCI provider must set the dwMask fields appropriately. The masks define bit packing -- dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask. If the format of the frame buffer is different from the current default display driver mode (i.e., GDI is passing 24-bit RGB data, but the display driver is converting this to 16-bit RGB data before writing the data to the frame buffer), then the provider should return the appropriate masks of the frame buffer.
dwWidth	DCI Provider specifies the width of the screen in pixels.
dwHeight	DCI Provider specifies the height of the screen in pixels.
lStride	Specifies the width in bytes of the surface. The width provided will be used as a stride in performing columnar accesses. A bottom to top device must set the origin to point to the lowest scan line and provide a negative stride.
dwBitCount	Access is being requested to the default display driver mode. DCI Provider must set the bit depth of the current display format. If the format of the frame buffer is different from the current default display driver mode (i.e., GDI is passing 24-bit RGB data, but the display driver is converting this to 16-bit RGB data before writing the data to the frame buffer), then the provider should return the bit depth of the frame buffer.
dwOffSurface
wSelSurface	wSelSurface:dwOffSurface is the pointer to the surface. This pointer must be generated at the time CreateSurface. Note that this is a 48-bit (16:32) pointer is called. The DCI Client will access it in this manner. Huge-pointer arithmetic will not be applied here. If the surface to be accessed is on a bank-switched memory device, the Surface Provider must install a suitable bank-switch handling routine, so that the DCI Client is "tricked" into viewing the entire memory range as a linear memory range.
BeginAccess	Called by DCI Client before accessing the surface. This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure. Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to a BeginAccess call.
EndAccess	Called by DCI Client at the end of access to display surface. Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to an EndAccess call.
DestroySurface	Called by DCI Client when the Client will no longer be using the surface. The DCI Provider must free all resources allocated when this surface was created.

COMMENTS

BeginAccess and EndAccess are called as a framework around every set of accesses to the display buffer. The DCI Client must not access surface memory before a BeginAccess or after an EndAccess. At BeginAccess, the DCI Provider must ensure that valid access is available to the memory range specified by the wSelSurface:dwOffSurface pointer.

The DCI Provider may change any and all fields in the DCIPRIMARY structure at BeginAccess. If any changes are made to the DCIPRIMARY structure the DCI Provider must return a suitable status code. No notification need be returned when callback addresses are changed; the DCI Client cannot assume that these addresses will remain unchanged.

The DCI Client is encouraged to minimize processing time between BeginAccess/EndAccess. Similarly the DCI Provider is encouraged to optimize the speed of these calls so that the DCI Client does not incur a stiff penalty on each direct access of a surface. It is valid to return NULL pointers if no action need be taken by the DCI Provider.

The DCI Provider must manage the mouse cursor during surface accesses. The DCI Client will provide the bounding rectangle of the area that will be accessed. The DCI Provider must exclude the cursor at BeginAccess, if the mouse cursor is within this area. At EndAccess, the DCI Provider must turn the mouse back on, if it was previously excluded.

DCIEnumSurface

A DCI client makes a DCIEnumSurface call to a DCI provider to determine what enhanced support, if any, the DCI provider provides.

uint Escape (hdc, DCICOMMAND, sizeof(DCIENUMINPUT),
(LPDCIENUMINPUT)lpInput, (LPVOID)NULL);

hdc	Device context being queried for DCI support.
lpInput	DCI Client provided DCIENUMINPUT structure with input parameters.

INPUT PARAMETERS

A DCI Client issuing this DCI Command will set the following fields of the DCIENUMINPUT structure:

dwCommand	DCIENUMSURFACE.
rDest, rSrc	Rectangular size of destination and source. The combination of these parameters defines any stretching requirements. Note: It is legal for the rectangles to be set to NULL, meaning the client is asking for an enumeration of the largest available surface. The provider should respond by enumerating the largest surface available in each offscreen or overlay format.
EnumCallback	Callback function provided by caller. The DCI provider uses this function to inform the caller of the list of color formats supported for the given input parameters.
lpContext	Pointer that identifies the DCI Client's context. This parameter must be passed back to the DCI Client as a parameter to EnumCallback.

EnumCallback

DCI Providers indicate support for each surface they support by returning a SurfaceInfo structure that describes the surface. The DCI Client is being provided the parameters for READ purposes only, and therefore there is no guarantee that the structure will be valid after the callback. The surface itself need not be created, but fields corresponding to an actual creation must be filled and returned.

void EnumCallback(LPDCISURFACEINFO lpSurface, LPVOID lpContext);

The following fields of the DCISURFACEINFO passed back to the DCI Client in the lpSurface parameter are must be filled by the DCI Provider:

dwSize	Set to size of structure. This size must be no smaller than sizeof(DCISURFACEINFO).
dwDCICaps	Flags that indicate the kind of support available for the surface being promised. Capability flags are defined in Chapter 2.
dwCompression	The DCI Provider provides the FOURCC of the surface that it can create. This field must be set to BI_BITFIELDS, if the current display mode is a nonstandard RGB mode.
dwMask	If promised support mode is a nonstandard RGB mode, the DCI provider must set dwMask fields appropriately. The masks define the bit packing. dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask.
dwWidth	DCI Provider specifies the width of the surface in pixels.
dwHeight	DCI Provider specifies the height of the surface in pixels.
lStride	Specifies the width in bytes of the surface. The width provided will be used as a stride in performing columnar accesses. A bottom-to-top device must set the origin to point to the lowest scanline and provide a negative stride. For subsampled planar formats, the stride of the subsampled planes will be proportional to the subsampling ratio.
dwBitCount	Access is being requested to the default display driver mode. DCI Provider must set the bit depth of the current display format.

COMMENTS

The DCI Provider calls EnumCallback to indicate offscreen and/or overlay surface support. While calling the callback, the DCI Provider passes to the DCI Client the lpContext parameter that was passed down previously.

A surface described through a call to EnumCallback is determined by the resources available at the time it is called. At a later time, even with the same input parameters, the DCI Provider could return a different level of support based upon different resource availability. In a multitasking environment, resources could get absorbed by a different task between a given tasks call to EnumSurface and the subsequent call to CreateOffscreenSurface. Hence, enumeration is only a conditional promise of support; it is legal for a subsequent CreateOffscreenSurface to fail.

If more than one color format is supported, the DCI Provider must call EnumCallback repeatedly to describe each color format. The DCI Provider must only return from DCIENUMSURFACE after all available surfaces are described.

The DCI provider must examine the stretching factor requested via the rDest and the rSrc parameters. Given the stretch factor, the DCI provider must call EnumCallback and provide the color format that the DCI provider will accept. If a color format is not supported for the given stretch factor, EnumCallback must not be called for that color format.

A call of EnumCallback does not create or grant access to the surface described. Therefore, the callback fields of the DCISURFACEINFO, and the parameters of BeginAccess, EndAccess, and DestroySurface, should be NULL.

DCICreateOffScreenSurface

A DCI client makes the GDI Escape call with these parameters to a DCI Provider to request access to access an offscreen surface. The DCI Client will tell the DCI Provider about the format of the requested Surface based upon the capabilities returned by a previous DCIEnumSurface call. DCI providers who indicated support for offscreen surfaces must support this call and return the corresponding DCISURFACEINFO.

uint Escape (hdc, DCICOMMAND, sizeof(DCICREATEINPUT),
(LPDCICREATEINPUT)lpInput, LPDCIOFFSCREEN *lpSurface);

hdc	Device context being queried for DCI support.
lpInput	DCI Client provided DCICREATEINPUT structure with input parameters.
lpSurface	DCI Client provided DWORD for the DCI Provider to put a far pointer to the DCIOFFSCREEN structure to be returned. This structure must be allocated by the DCI Provider.

INPUT PARAMETERS

A DCI Client issuing this DCI Command will set the following fields of the DCICREATEINPUT structure:

dwCommand	DCICREATEOFFSCREENSURFACE.
dwVersion	0x0100 for DCI 1.0.
dwCompression	FOURCC format of surface to be created. The definition of each of these formats are provided in the attached format documentation. This field will be set to BI_BITFIELDS, if the surface to be created is a non-standard RGB.
dwMask	If dwCompression is BI_BITFIELDS, these masks define the bit packing. dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask.
dwWidth	Width of the surface to be created in pixels.
dwHeight	Height of the surface to be created in pixels.
dwDCICaps	Describes the capabilities the DCI Client is requesting for this surface. This flag should describe exactly a surface described by the DCI Provider in a call to an EnumCallback.

RETURNS

A DCI Provider responding to this DCI Command must set the following fields of the DCIOFFSCREEN structure it returns:

dwSize	DCI Provider must provide the size of the structure created. This size must be no smaller than sizeof(DCIOFFSCREEN). It can be larger, should the DCI Provider need to maintain additional private information pertinent to the object created.
dwDCICaps	At a minimum, DCI_OFFSCREEN must be set.
	DCI_1632_ACCESS must be set if the surface uses bank-switched memory and will be accessed via a VFlatd linear-access mechanism.
	The DCI Provider must set stretching flags to match the stretching that is active on the surface.
	The DCI Provider must set DCI_VISIBLE if data drawn to this offscreen surface will become instantaneously visible without invoking the Draw callback function.
	The DCI Provider may also set other capability flags. These flags only promise support; they do not indicate that the support has been activated.
dwCompression	DCI Provider must set the FOURCC format of the surface being created.
dwMask	If the dwCompression field is set to BI_BITFIELDS, specifying a nonstandard bit packing for RGB16, 24 or 32, this field must be set properly. The masks define the bit packing. dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask.
dwWidth	DCI Provider specifies the width of the surface in pixels.
dwHeight	DCI Provider specifies the height of the surface in pixels.
lStride	Specifies the pitch of the surface in bytes . The value provided will be used as a stride in performing columnar accesses. A bottom-to-top device must set the origin to point to the lowest scanline and provide a negative stride. For subsampled planar formats, the stride of the subsampled planes will be proportional to the subsampling ratio.
dwBitCount	DCI Provider must set the bit depth of surface being created.
dwOffSurface
wSelSurface	wSelSurface:dwOffSurface is the pointer to the surface. This pointer must be generated at the time of CreateSurface. Note that this is a 48-bit (16:32) pointer. The DCI Client must access it in this manner. Huge pointer arithmetic cannot be applied here.
	If the surface to be accessed is on a bank-switched memory device, then the surface provider must install a suitable bank-switch handling routine, so that the DCI Client is "tricked" into viewing the entire memory range as a linear memory range.
	These fields may be invalid until the DCI Client calls the SetDestination callback.
BeginAccess	Called by DCI Client at the beginning of a draw operation. This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to BeginAccess.
EndAccess	Called by DCI Client at the end of access to display surface.
	Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to EndAccess.
DestroySurface	Called by DCI Client when the Client will no longer be using the surface. The DCI Provider must free all resources allocated when this surface was created.
Draw	Called by DCI Client when data from an offscreen surface must be copied to the screen. Parameters specifying the transfer are those in effect from the last SetDestination and SetCliplist calls.
	This function is called following a BeginAccess and an EndAccess call.
	This function must return a status code when invoked. It is legal for the DCI Provider to fail the call. at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
SetDestination	Called by DCI Client to describe the extent of the destination surface. This function will be called to reflect window moves or size changes. The source rectangle is also provided in this call to define any clipping or stretching necessary. This call can be rejected if the parameters provided cannot be supported.
	Before a call to SetDestination, the DCI Provider does not know where this surface should appear when mapped to the screen. Therefore, the DCI Client must make this call before calling SetClipList, BeginAccess, or Draw. If a change is needed, the DCI Provider can update the wSelSurface and dwOffSurface fields of the DCIOFFSCREEEN structure on the next call to BeginAccess and return the DCI_STATUS_POINTERCHANGED status code. Then the surface is considered initialized.
	This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	Note: The client may call SetDestination with the source rectangle pointer set to NULL. This indicates that the entire offscreen surface is to be mapped to the given destination screen rectangle.
SetCliplist	The DCI Client calls this function to tell the DCI Provider about changes to the overlap status of the window in which drawing is occurring. Support of this function is required for all offscreen surfaces.
	The DCI Provider will be passed a RGNDATA structure describing the visible area. The lpBuffer field of the RGNDATA structure is in an array of rectangles. Fields within the header preceding the array define the length of the array. The walk order of the rectangles is left-to-right, top-to-bottom.
	This function must return a status code when invoked. It is legal for the DCI Provider to fail the call. at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	It is the DCI Client's responsibility to ensure the bounding rectangle returned in the rcBound field of the RGNDATAHEADER structure intersects the destination rectangle in a prior SetDestination call. The very first SetClipList call must be preceded by a SetDestination call.

COMMENTS

The DCI Provider may change any and all fields in the DCIOFFSCREEN structure at BeginAccess. If any changes are made to the DCISURFACEINFO portion of DCIOFFSCREEN structure, the DCI Provider must return a suitable notification status code. No notification need be returned when callback addresses are changed; the DCI Client cannot assume that these addresses will remain unchanged.

Offscreen surfaces need not reside on the graphics memory itself. It is conceivable for the DCI provider to provide access to a system memory buffer as an offscreen surface. This is particularly attractive for devices with special blitters and limited graphics board memory.

DCICreateOverlaySurface

Called by the DCI Client when the DCI Client wants access to overlay control buffers. Overlay buffers control merging of an offscreen surface with the primary display surface. Hence, the DCI Client will already have created an offscreen surface prior to calling this function. The DCI Client invokes this function only if DCI_CANOVERLAY has been set on the offscreen surface.

uint Escape (hdc, DCICOMMAND, sizeof(DCICREATEINPUT),
(LPDCICREATEINPUT)lpInput, LPDCIOVERLAY *lpSurface);

hdc	Device context being queried for DCI support.
lpInput	DCI Client provided DCICREATEINPUT structure with input parameters.
lpSurface	DCI Client provided DWORD for the DCI Provider to put a far pointer to the DCIOVERLAY structure to be returned. This structure must be allocated by the DCI Provider.

INPUT PARAMETERS

A DCI Client issuing this DCI Command will set the following fields of the DCICREATEINPUT structure:

dwCommand	DCICREATEOVERLAYSURFACE.
dwVersion	0x0100 for DCI 1.0.
lpOffScreenSurface	The DCI Client provides the handle of the previously created DCI surface on which the overlay functionality is to be exercised.

RETURNS

A DCI Provider responding to this DCI Command must set the following fields of the DCIOVERLAY structure it returns:

dwSize	DCI Provider must provide the size of the structure created. This size must be no smaller than sizeof(DCIOVERLAY). It can be larger, should the DCI Provider need to maintain additional private information pertinent to the object created.
dwDCICaps	At a minimum, DCI_OVERLAY must be set.
	DCI_1632_ACCESS must be set if the surface uses bank-switched memory and will be accessed via a VFlatd linear access mechanism.
	If overlay is being provided through chromakeying, DCI_CHROMAKEY must be set and the value used for chromakeying must be set in dwChromakeyValue.
dwMask	If the dwCompression field is set to BI_BITFIELDS, specifying a nonstandard bit packing for RGB16, 24 or 32, this field must be set properly. The masks define the bit packing. dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask.
dwCompression	FOURCC of overlay buffer. The definition of each of these image formats are provided in the attached format documentation. If the overlay is to be performed via the default display mode, dwCompression field must be set to 0. If the surface is a nonstandard RGB mode, dwCompression must be set to BI_BITFIELDS.
dwMask	If dwCompression is BI_BITFIELDS, these masks define the bit packing. dwMask[0] is the red mask; dwMask[1] is the green mask; dwMask[2] is the blue mask.
dwWidth	DCI Provider specifies the width of the surface in pixels.
dwHeight	DCI Provider specifies the height of the surface in pixels.
lStride	Specifies the width in bytes of the surface. The width provided will be used as a stride in performing columnar accesses. A bottom-to-top device must set the origin to point to the lowest scanline and provide a negative stride. For subsampled planar formats, the stride of the subsampled planes will be proportional to the subsampling ratio.
dwBitCount	DCI Provider must set the bit depth of surface being created.
dwOffSurface
wSelSurface	For access to an overlay/chromakey buffer, wSelSurface:dwOffSurface is the pointer to the surface. This pointer must be generated at the time of CreateSurface. If the overlay/chromakey buffer is to be accessed via the default display mode, wSelSurface:dwOffSurface must not be specified.
	If the surface to be accessed is on a bank-switched memory device, the surface provider must install a suitable bank-switch handling routine, so that the DCI Client is "tricked" into viewing the entire memory range as a linear memory range.
BeginAccess	Called by DCI Client at the beginning of a draw operation. This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to BeginAccess.
EndAccess	Called by DCI Client at the end of access to display surface.
	Note: This pointer may be NULL, if the DCI Provider does not need to take any action corresponding to EndAccess.
DestroySurface	Will not be called for an overlay buffer. Only the primary offscreen buffer with which this overlay buffer is associated will be destroyed.
SetDestination	Called by DCI Client to describe the extent of the destination surface. This function will be called to reflect window moves or size changes. The source rectangle is also provided in this call to define any stretching necessary. This call can be rejected if the destination parameters provided cannot be supported.
	Before a call to SetDestination, the DCI Provider does not know where this surface should appear when mapped to the screen. Therefore, the DCI Client must make this call before calling SetClipList, BeginAccess or Draw. If a change is needed, the DCI Provider can update the wSelSurface and dwOffSurface fields of the DCIOFFSCREEEN structure on the next call to BeginAccess and return the DCI_STATUS_POINTERCHANGED status code. Then, the surface is considered initialized.
	This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	Note: The client may call SetDestination with the source rectangle pointer set to NULL. This indicates that the entire offscreen surface is to be mapped to the given destination screen rectangle.

SetCliplist	The DCI Client calls this function to tell the DCI Provider about changes to the overlap status of the window in which drawing is occurring. Support of this function is required for all offscreen surfaces.
	The DCI Provider will be passed a RGNDATA structure describing the visible area. The lpBuffer field of the RGNDATA structure is in an array of rectangles. Fields within the header preceding the array define the length of the array. The walk order of the rectangles is top-to-bottom, left-to-right.
	This function must return a status code when invoked. It is legal for the DCI Provider to fail the call at the time of invocation. A suitable error code must be returned to indicate the cause of failure.
	It is the DCI Client's responsibility to ensure the bounding rectangle returned in the rcBound field of the RGNDATAHEADER structure intersects the destination rectangle in a prior SetDestination call. The very first SetClipList call must be preceded by a SetDestination call.
dwChromakeyValue	If overlay is to be controlled via chromakey, DCI Provider must return the value which will enable data from the offscreen surface to be placed on the primary display surface.
dwChromakeyMask	These masks inform the user that the dwChromakeyValue must be XORed into place. It represents that not all bits of locations in the overlay buffer are for chromakey purposes.

COMMENTS

If overlay control is to be performed via the primary display control buffer, all returns (specifically the lpSurface, BitmapInfo, dwCompression and wSelSurface:dwOffSurface fields) must be zeroed. The only valid data when overlay control is to be provided via the primary display surface is dwChromakeyValue and dwChromakeyMask.

The DCI Provider may change any and all fields in the DCIOVERLAY structure at BeginAccess. If any changes are made to the DCISURFACEINFO portion or to the dwChromakey fields of DCIOVERLAY structure the DCI Provider must return a suitable notification status code. No notification need be returned when callback addresses are changed; the DCI Client cannot assume that these addresses will remain unchanged.