DEVESC_EXTPUT

GreEscape DEVESC_EXTPUT is called by EnDIVE users to copy an image to the screen.

Simulation support: None.

Syntax

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

Parameters

hdc (HDC) - input: Device context handle.

ICODE (LONG) - input: DEVESC_EXTPUT escape code.

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

pbInData (PBYTE) - input: Pointer to IMAGEPACK data structure.

plOutCount (PLONG) - input: NULL.

pbOutData (PULONG) - input: NULL.

Returns

rc (LONG) - returns

Return Codes.

The handling routine returns:

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

Remarks

The source image must be scaled to the dimensions specified in the IMAGEPACK input data structure. The source data of this operation can be either linear system memory or single aperture off-screen VRAM that was previously allocated by the display driver's GreEscape DEVESC_VRAMALLOC function.

Stretch Blt Acceleration Processing: Since Stretch Blt accelerators support a wide variety of input formats that are typically different from the graphics adapter's VRAM, a COLORINFO data structure is included in the IMAGEBUF data structure to describe the source data. COLORINFO is one of the structures returned by the driver's call to GreEscape DEVESC_EXTQUERY. As long as the source color space is one of the driver's accelerated color spaces, the driver is expected to accelerate the Blt by using the Stretch Blt assist. Only COLORINFO data structures returned by GreEscape DEVESC_EXTQUERY can be specified for source and target color spaces.

CODEC Processing: Fields in the IMAGEPACK data structure specify compression and decompression services from within the driver. When the corresponding capabilities are specified in the IMAGECAPS flags of the GreEscape DEVESC_EXTQUERY function, the IMAGEPACK CODEC fields must be supported. To support CODEC processing of video data, the driver must examine the flags in the CODECINFO structure to determine whether compression or decompression is required.

Roundtrip Processing: Through the use of bits in the command mask parameter, data can be passed to the driver for decompression and the output returned to the caller. Another bit controls whether the output is displayed. Conversely, uncompressed data can be passed in GreEscape DEVESC_EXTGET, be compressed, and returned to the caller.

Users of this function are responsible for bracketing access to video memory and this function with GreEscape DEVESC_HWREQUEST.

The GreEscape DEVESC_EXTQUERY and GreEscape DEVESC_EXTGET functions are related to GreEscape DEVESC_EXTPUT.

Source Code Sample

Declaration:

#define INCL_GRE_DEVICE
#include <os2.h>

HDC      hdc;         /* Device context handle. */
LONG     ICODE;       /* DEVESC_EXTPUT escape code. */
LONG     lInCount;    /* Number of bytes pointed to by pInData. */
PBYTE    pbInData;    /* Pointer to IMAGEPACK data structure. */
PLONG    plOutCount;  /* NULL. */
PULONG   pbOutData;   /* NULL. */
LONG     rc;          /* Return Codes. */

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