View source for DEVESC EXTPUT

{{DISPLAYTITLE: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:
<pre>
#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);
</pre>

[[Category:DEVESC]]