SetDestination

Called by DCI Client to describe the extent of the destination surface.

DCIRVAL CALLBACK _loadds SetDestination(lpSurface, lprDst, lprSrc)

LPVOID	*lpSurface;*
LPRECT	*lprDst;*
LPRECT	*lprSrc;*

INPUT PARAMETERS

lpSurface	Specifies a far pointer to a DCISURFACEINFO structure that was previously obtained via a DCIDCREATEPRIMARYSURFACE, DCICREATEOFFSCREENSURFACE, or DCICREATEOVERLAYSURFACE escape.
lprDst	Specifies a far pointer to a RECT structure in screen coordinates. This rectangle represents the area on the primary surface which the source rectangle is to be mapped to.
lprSrc	Specifies a far pointer to a RECT structure. This rectangle represents the area of the offscreen surface which is to be mapped to the primary surface, and is a sub-rectangle of the rectangle which encompasses the offscreen surface. The upper left corner of the "surface" rectangle is represented by the point (0, 0), and corresponds to the pointer specified by wSelSurface:dwOffSurface of the offscreen surface.

RETURNS

Returns DCI_OK on success, or an error code on failure. DCI error codes are listed in Chapter 2 of the DCI Specification.

COMMENTS

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 rectangle provided cannot be supported.

Before a call to SetDestination, the DCI Provider has no idea 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.

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 destination screen rectangle given. It is invalid for a client to make a SetDestination call with the destination rectangle pointer set to NULL.