PDRREF:Presentation Manager Function Categories

This chapter categorizes the Presentation Manager functions as mandatory for all drivers, mandatory for display drivers or hardcopy drivers, or functions simulated by a handling routine in the graphics engine. Each type of function is described by category as well.

Mandatory Functions for All Drivers
This section describes those functions that must be supported for all devices. These functions are called through the dispatch table by handling routines in the presentation driver. The dispatch table contains the address of each function that the presentation driver can hook. Initially, when the presentation driver is first loaded, a copy of the default dispatch table is passed to the driver. The presentation driver's Enable routine modifies this copy so that the entries for functions supported in the driver point to the handling routines in the driver. Entries to the table that are to be modified can first be saved by the presentation driver in case they are subsequently needed. The original saved table entries, and those that are not modified, point to the engine-simulation routines for the functions concerned.

Functions listed in the dispatch table fall into two categories: Descriptions of the mandatory functions are provided. Each description shows what the handling routine is expected to do, the parameters passed to the routine, and the values that the routine returns. The functions are grouped according to the conditional include sections of the header file: Additional functions that must be supported by presentation drivers for display devices are described in Mandatory Functions for Display Drivers. Hardcopy drivers must also provide some support for these display device functions. This support can be a common routine that returns Successful and posts the warning, PMERR_DEV_FUNC_NOT_INSTALLED.
 * Functions that the presentation driver must support (mandatory functions)
 * Functions that are supported by the graphics engine but can be optionally hooked by the presentation driver
 * Attribute functions (INCL_GRE_DEVMISC1)
 * Bit-map functions (INCL_GRE_BITMAPS)
 * Color table functions (INCL_GRE_COLORTABLE)
 * Device functions 2 (INCL_GRE_DEVMISC2)
 * Device functions 3 (INCL_GRE_DEVMISC3)
 * GreEscape functions (INCL_GRE_DEVICE)
 * Line functions (INCL_GRE_LINES, INCL_GRE_SCANS)
 * Marker functions (INCL_GRE_MARKERS)
 * Query functions (INCL_GRE_DEVICE)
 * Text (String) functions (INCL_GRE_STRINGS)

The level of support provided in the handling routine for a particular function depends on the type of device and the level of support provided for that device. At the minimum, the handling routine must indicate a successful completion.

Attribute and Bundle Definitions
A general description of colors, mixes, patterns, and the attribute definitions for each attribute bundle type are provided. For area definitions, the area must be filled by using the pattern that is current when GreBeginArea is called.

Colors
All colors are passed as 32-bit signed values. These are either indexes into the Logical Color table, logical palette indexes, or representations of 24-bit Red-Green-Blue (RGB) values. Some special attribute values can be passed to the graphics engine and returned by GreGetAttributes: CLR_FALSE and CLR_TRUE provide useful operands for BitBlt logical operations. CLR_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.
 * CLR_FALSE:All color planes or bits, or both, are 0.
 * CLR_TRUE:All color planes or bits, or both, are 1.
 * CLR_WHITE:This index is never loaded explicitly. It always produces White when the default color table is in force or when the index is set to RGB. With a realized color table and an index that is not RGB, the value CLR_WHITE produces the background color CLR_BACKGROUND.
 * CLR_BLACK:This index is never loaded explicitly. It always produces Black when the default color table is in force or when the index is set to RGB. With a realized color table and an index that is not RGB, CLR_BLACK produces the neutral color CLR_NEUTRAL. See Color Functions.

Mix Modes
All values are passed to the graphics engine which passes them unchanged to the presentation driver.
 * Foreground Mix Mode:Valid values are:
 * FM_OR: OR
 * FM_OVERPAINT: Overpaint
 * FM_XOR: Exclusive-OR
 * FM_LEAVEALONE: Leave alone (invisible)
 * FM_AND: AND
 * FM_SUBTRACT: (Inverse source) AND destination
 * FM_MASKSRCNOT: Source AND (inverse destination)
 * FM_ZERO: All zeros
 * FM_NOTMERGESRC: Inverse (source OR destination)
 * FM_NOTXORSRC: Inverse (source Exclusive-OR destination)
 * FM_INVERT: Inverse of destination
 * FM_MERGESRCNOT: Source OR (inverse destination)
 * FM_NOTCOPYSRC: Inverse of source
 * FM_MERGENOTSRC: (Inverse source) OR destination
 * FM_NOTMASKSRC: Inverse of (source AND destination)
 * FM_ONE: All ones
 * Note: FM_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.

The presentation driver must support FM_OR, FM_OVERPAINT, FM_XOR, and FM_LEAVEALONE. Other foreground mixes can be handled as FM_OVERPAINT. Mixing, other than for FM_LEAVEALONE or FM_OVERPAINT, is performed on the physical color index or logical palette index. When an indexed color table or palette has been realized, this corresponds to the logical color index. In other cases, the color resulting from a mix cannot be predicted.


 * Note: An exception to this rule occurs when the same object is drawn twice with FM_XOR and BM_LEAVEALONE, and no intermediate drawing is performed in other mixes. The implementation must guarantee that this always results in the object being erased cleanly.

Other valid mixes can also be supported for some primitive types. When a valid mix is not supported, the default is FM_OVERPAINT. An error is raised only when the specified mix value is not one of those listed above.


 * Background Mix Mode:Valid values are:
 * BM_ERROR: Error
 * BM_DEFAULT: Default
 * BM_OR: OR
 * BM_OVERPAINT: Overpaint
 * BM_XOR: Exclusive-OR
 * BM_LEAVEALONE: Leave alone (invisible)
 * BM_SRCTRANSPARENT: Provides a transparent overlay function by not copying (to the output bit map) the pels from the source bit map that match the presentation space background color.
 * BM_DESTTRANSPARENT: Provides a transparent underlay function by copying the pels from the source bit map only to the destination pels that match the presentation space background color.
 * The presentation driver must support BM_OVERPAINT and BM_LEAVEALONE. Other background mixes can be handled as BM_LEAVEALONE.

GreQueryDeviceCaps allows the application to determine the mixes supported by the device.

Line Attributes
The device line attributes are bundled in a DLINEBUNDLE structure:

LINEBUNDLE Mask
This mask is used in calls to GreDeviceSetAttributes to identify fields in the LINEBUNDLE structure. Valid flags and the fields that they identify are:
 * lbnd:The fields of a LINEBUNDLE structure are:
 * lColor:Line foreground color.
 * lBackColor:Line background color.
 * usMixMode:Line foreground mix mode.
 * usBackMixMode:Line background mix mode.
 * fxWidth:Line-width multiplier. This value is expressed in fixed-point notation with a notational binary point between the second and third bytes. Therefore, 1.0 is represented by 10000h (or 65536). This multiplier is applied to the normal line width. Valid values are:
 * LINEWIDTH_DEFAULT:Default line width. This is the same as LINEWIDTH_NORMAL.
 * LINEWIDTH_NORMAL:Normal line width.
 * LINEWIDTH_THICK:Thick line width. This is double the normal width.
 * Typically, values equal or less than 1.0 are treated as LINEWIDTH_NORMAL and values greater than 1.0 as LINEWIDTH_THICK.


 * lGeomWidth:Geometric line thickness in world-coordinate space specified as an integer value. This is used only by GreStrokePath or when MPATH_STROKE is specified for GreModifyPath. A value of 0 (zero) results in the thinnest line possible regardless of the transform in force. Thick geometric lines are treated as polygons and are transformed accordingly.
 * usType:Specifies the cosmetic line type. Valid values are:
 * LINETYPE_DOT:Dotted
 * LINETYPE_SHORTDASH:Short-dashed
 * LINETYPE_DASHDOT:Dash, dot
 * LINETYPE_DOUBLEDOT:Double-dotted
 * LINETYPE_LONGDASH:Long-dashed
 * LINETYPE_DASHDOUBLEDOT:Dash, double-dot
 * LINETYPE_SOLID:Solid
 * LINETYPE_INVISIBLE:Invisible
 * LINETYPE_ALTERNATE:Every alternate pel on
 * Note:LINETYPE_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.


 * usEnd:Valid values are:
 * LINEEND_FLAT:Flat
 * LINEEND_SQUARE:Square
 * LINEEND_ROUND:Round
 * Note:LINEEND_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.


 * usJoin:Valid values are:
 * LINEJOIN_BEVEL:Bevel
 * LINEJOIN_ROUND:Round
 * LINEJOIN_MITRE:Miter
 * Note:LINEJOIN_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.
 * When lines join at a very acute angle, and a mitered joint has been specified, the length of the miter line could extend to infinity. To prevent this, when the ratio of miter length to geometric line width exceeds 10:1, a bevel joint is drawn. The miter length is the distance between the inner and outer intersection points.
 * When a wide line is explicitly closed by a call to GreCloseFigure from within a path, the style at the closure point is JOIN style not END style. If enough points are given to implicitly close the figure, the END style is used at the closure points. Notice that the LINEJOIN attribute is only to be used at wide line ends when the figure has been closed by a call to GreCloseFigure.

Area (Pattern) Attributes
The device area (pattern) attributes are bundled in a DAREABUNDLE structure:

AREABUNDLE Mask
This mask is used in calls to GreDeviceSetAttributes to identify fields in the AREABUNDLE structure. Valid flags and the fields that they identify are:
 * abnd:The fields of an AREABUNDLE structure are:
 * lColor:Area foreground color.
 * lBackColor:Area background color.
 * usMixMode:Area foreground mix mode.
 * usBackMixMode:Area background mix mode.
 * usSet:Local identifier (lcid) for a logical font or a bit map. Valid values are:
 * 0:Base pattern set.
 * Nonzero:Local identifier for the logical font or bit map defined by the cdef.def Set field in the area attributes bundle.
 * usSymbol:Identity of the required pattern in the current pattern set or logical font. This attribute is ignored when the pattern set is a bit map. If the value is outside the range of the logical font, the standard default pattern is used.
 * Values in the range 1-255 are valid. The defined values are:
 * PATSYM_ERROR:Error.
 * PATSYM_DEFAULT:Default.
 * PATSYM_DENSE1:Solid shading with decreasing intensity.
 * PATSYM_DENSE2:Solid shading with decreasing intensity.
 * PATSYM_DENSE3:Solid shading with decreasing intensity.
 * PATSYM_DENSE4:Solid shading with decreasing intensity.
 * PATSYM_DENSE5:Solid shading with decreasing intensity.
 * PATSYM_DENSE6:Solid shading with decreasing intensity.
 * PATSYM_DENSE7:Solid shading with decreasing intensity.
 * PATSYM_DENSE8:Solid shading with decreasing intensity.
 * PATSYM_VERT:Vertical lines.
 * PATSYM_HORIZ:Horizontal lines.
 * PATSYM_DIAG1:Diagonal lines 1, bottom-left to top-right.
 * PATSYM_DIAG2:Diagonal lines 2, bottom-left to top-right.
 * PATSYM_DIAG3:Diagonal lines 1, top-left to bottom-right.
 * PATSYM_DIAG4:Diagonal lines 2, top-left to bottom-right.
 * PATSYM_NOSHADE:No shading.
 * PATSYM_SOLID:Solid shading.
 * PATSYM_BLANK:Blank (same as PATSYM_NOSHADE).
 * PATSYM_HALFTONE:Every alternate pel on. PATSYM_HALFTONE can be similar to PATSYM_DENSE4 and PATSYM_DENSE5 (solid patterns) but has a more stringent definition. It is useful for generating gray text.
 * See the Presentation Manager Programming Reference for definitions of these shading patterns.


 * ptlRefPoint:Specifies the pattern origin for areas and thick lines. The pattern is mapped into the area to be filled by conceptually replicating the pattern definition in both the horizontal and vertical directions.
 * The pattern reference point is subject to all of the transforms. When an area is moved by changing a transform and redrawing, the fill pattern also appears to move so as to retain its position relative to the area boundaries. This positioning capability allows part of a picture to be moved with a BitBlt operation and the remainder to be drawn by changing the appropriate transform with no discontinuity at the join.
 * The pattern reference point, which is specified in world coordinates, need not be inside the actual area to be filled and is not subject to clipping. However, the area to be filled is subject to clipping.


 * adef:The fields of an AREADEFS structure are:
 * defSet:Area definition. This can be a text pattern, predefined pattern, bit map, pointer to an engine font, device font handle, or bit map handle.
 * fFlags:The only valid flag is CDEF_GENERIC.
 * CodePage:Code Page ID.

Character Attributes
The device character attributes are bundled in a DCHARBUNDLE structure:

CHARBUNDLE Mask
This mask is used in calls to GreDeviceSetAttributes to identify fields in the CHARBUNDLE structure. Valid flags and the fields that they identify are:
 * cbnd:The fields of a CHARBUNDLE structure are:
 * lColor:Character foreground color.
 * lBackColor:Character background color.
 * usMixMode:Character foreground mix mode.
 * usBackMixMode:Character background mix mode.
 * usSet:Specifies a local identifier (lcid) for a logical font. If usSet is 0, the current code page and character precision are used to resolve the selection of the base font. The code page (set by the function GreSetCodePage) identifies two base fonts: an outline font and an image font. The value of usPrecision determines which of these is selected. Valid values for usSet are:
 * 0:Base font.
 * Nonzero:Local identifier for the logical font defined by the cdef.defSet field in the character attributes bundle.
 * usPrecision:Specifies the character mode. The value of usPrecision is used to select output quality from Precision 1 (the lowest) to Precision 3. Presentation drivers normally use Precision 3 except when performance is improved by using the specified precision. For example, the EGA and VGA drivers always use Precision 3 when the current font is an outline font, but switch to the specified precision for an image font.
 * Valid values for usPrecision are:
 * CM_MODE1:Precision 1. The selected font can be either an image or an outline font. When an image font is used, the first character is positioned with its reference point at the current position. Subsequent characters are positioned by using FONTMETRICS.
 * CM_MODE2:Precision 2. The selected font can be either an image or outline font. When an image font is used, the first character is positioned with its reference point at the current position. Subsequent characters are positioned by using the FONTMETRICS, CBB_BOX, CBB_ANGLE, and CBB_SHEAR attributes. This is done by constructing a transformation matrix that transforms the FONTMETRICS values sXDeviceRes and sYDeviceRes to the rotated, scaled, and sheared character box attributes, and translates the reference point of the first character to the current position. The actual character positions are then determined by applying this transform to the character positions found by using the FONTMETRICS.
 * Notice that the character box attribute is subjected to the rotation, scaling, and shear defined by the current transformations and the other character attributes.
 * Note:Shear attributes affect only the horizontal position of CM_MODE2 characters when the character direction is CHRDIRN_TOPBOTTOM or CHRDIRN_BOTTOMTOP.
 * CM_MODE3:Precision 3. The selected font must be an outline font.
 * Note:CM_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.
 * For outline fonts, regardless of mode, all character attributes together with the FONTMETRICS are used for positioning, scaling, rotating, and shearing the characters. This is done by constructing a transformation matrix as described previously for CM_MODE2. The actual character vector stroke coordinates are then determined by applying this transform to the character-definition coordinates suitably modified (for character positioning) by the FONTMETRICS.
 * As with CM_MODE2, the character box attribute is subjected to the rotation, scaling, and shear defined by the current transformations and the other character attributes.
 * The character reference point is defined as the intersection of the base line and the left edge of the character. The baseline is defined as an offset, pCellOffset, from the top of the character cell.


 * sizfxCell:Specifies fixed-point numbers for the width and height of a character cell in world-coordinate space. This defines the background area for a character. Each dimension is represented as a signed four-byte integer with a notational binary point between bit 16 and bit 15. Therefore, +2.5 is represented by 00028000h and -2.5 is represented by FFFD8000h.
 * For CM_MODE1, the cell has no effect when characters are drawn from an image font. For CM_MODE2, the width determines the spacing of consecutive characters along the baseline. Both width and height can be positive, negative, or 0. When either parameter is negative, the spacing occurs in the direction opposite to normal and each character is drawn reflected in CM_MODE3. For example, a negative height in the standard direction in Mode 3 indicates that the characters are drawn upside down, and that the string is drawn below the baseline (assuming no other transformations cause inversion). A zero character width or height is also valid. The string of characters collapses into a line. If both are 0, the string is drawn as a single point in CM_MODE3.


 * ptlAngle:Specifies integer values X and Y for the coordinates of the end of a line starting at the origin (0, 0). The baseline for subsequent character strings is parallel to this line.
 * For CM_MODE1, the angle has no effect when characters are drawn.
 * For CM_MODE2, the angle is used to determine the position of each image character. However, the orientation of characters within the character box is inherent in their definitions. The characters are positioned so that the lower-left corners of the character definitions are placed at the lower-left corners of the character boxes.
 * For CM_MODE3, the angle is observed accurately and the character boxes are rotated to be normal to the character baseline. If the coordinate system is such that one X-axis unit is not physically equal to one Y-axis unit, a rotated character appears to be sheared.


 * ptlShear:Specifies integer values, which identify the end coordinates of a line originating at 0, 0. The vertical strokes in subsequent outline character strings are drawn parallel to the defined line. For CM_MODE1, the shear has no effect when image characters are drawn. For CM_MODE2, the shear affects the height of the character cell. Therefore, the position of characters drawn with CDIRN_TOPBOTTOM or CDIRN_BOTTOMTOP. The top of the character box remains parallel to the character baseline.
 * If hx=0 and hy=1 (the standard default), upright characters result. If hx and hy are both positive or negative nonzero, the characters slope from bottom left to top right. If hx and hy are of opposite signs, the characters slope from top left to bottom right.
 * Note:The value for hy cannot be 0 (zero) because this implies an infinite shear.
 * No character inversion takes place as a result of shear alone. (Inversion can be done with the charCell attribute.)


 * usDirection:Valid values are:
 * CHDIRN_LEFTRIGHT:Left-to-right
 * CHDIRN_TOPBOTTOM:Top-to-bottom
 * CHDIRN_RIGHTLEFT:Right-to-left
 * CHDIRN_BOTTOMTOP:Bottom-to-top


 * Note: CHDIRN_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.
 * If the specified direction is not valid, the presentation driver uses CHDIRN_LEFTRIGHT as the default.


 * usTextAlign:Specifies the horizontal and vertical alignment of character strings. This alignment defines a reference point within the string, which is positioned on the starting point specified for the string.

The horizontal alignment values are as follows:
 * TA_NORMAL_HORIZ:Normal alignment. This is the initial default. The alignment assumed depends on the current character direction:
 * CHDIRN_LEFTRIGHT:Same as TA_LEFT
 * CHDIRN_TOPBOTTOM:Same as TA_CENTER
 * CHDIRN_RIGHTLEFT:Same as TA_RIGHT
 * CHDIRN_BOTTOMTOP:Same as TA_CENTER
 * TA_LEFT:Left alignment. The string is aligned on the left edge of its leftmost character.
 * TA_CENTER:Center alignment. The string is aligned on the arithmetic mean of Left and Right.
 * TA_RIGHT:Right alignment. The string is aligned on the right edge of its rightmost character.
 * TA_STANDARD_HORIZ:Standard alignment. The alignment assumed depends on the current character direction:
 * CHDIRN_LEFTRIGHT:Same as TA_LEFT
 * CHDIRN_TOPBOTTOM:Same as TA_LEFT
 * CHDIRN_RIGHTLEFT:Same as TA_RIGHT
 * CHDIRN_BOTTOMTOP:Same as TA_LEFT
 * The vertical alignment values are as follows:
 * TA_NORMAL_VERT:Normal alignment. This is the initial default. The alignment assumed depends on the current character direction:
 * CHDIRN_LEFTRIGHT:Same as TA_BASE
 * CHDIRN_TOPBOTTOM:Same as TA_TOP
 * CHDIRN_RIGHTLEFT:Same as TA_BASE
 * CHDIRN_BOTTOMTOP:Same as TA_BOTTOM
 * TA_TOP:Top alignment. The string is aligned on the top edge of its topmost character.
 * TA_HALF:Half alignment. The string is aligned on the arithmetic mean of Bottom and Top.
 * TA_BASE:Base alignment. The string is aligned on the base of its bottom character.
 * TA_BOTTOM:Bottom alignment. The string is aligned on the bottom edge of its bottom character.
 * TA_STANDARD:Standard alignment. The alignment assumed depends on the current character direction:
 * CHDIRN_LEFTRIGHT:Same as TA_BOTTOM
 * CHDIRN_TOPBOTTOM:Same as TA_TOP
 * CHDIRN_RIGHTLEFT:Same as TA_BOTTOM
 * CHDIRN_BOTTOMTOP:Same as TA_BOTTOM
 * The current position will also be modified relative to the current character direction as shown:


 * Horizontal:For horizontal character directions:
 * Horizontal Alignment:New X Current Position
 * TA_LEFT:Right
 * TA_CENTER:Center
 * TA_RIGHT:Left
 * Vertical Alignment New X Current Position
 * TA_TOP:Top
 * TA_HALF:Half
 * TA_BASE:Base
 * TA_BOTTOM:Bottom


 * Vertical For vertical character directions:
 * Horizontal Alignment:New X Current Position
 * TA_LEFT:Left
 * TA_CENTER:Center
 * TA_RIGHT:Right


 * Vertical Alignment:New X Current Position
 * TA_TOP:Bottom
 * TA_HALF:Half
 * TA_BASE:Base
 * TA_BOTTOM:Top


 * fxExtra
 * A fixed point world-coordinate distance, which is added between every character as it is being placed.


 * fxBreakExtra
 * A fixed point world-coordinate distance, which is added to the width of the break character as it is placed.


 * cdef:The fields of a CHARDEFS structure are:
 * defSet:Character set definition. If defSet is passed as 0, the presentation driver must use the default device font (zero is passed only when the driver provides and manages its own default font). Otherwise, the significance of defSet depends upon the state of the CDEF_GENERIC flag, as follows:
 * If the flag is set, defSet is a pointer to an engine font.
 * If not set, defSet is a device font identifier defined by the driver.
 * When defSet is a pointer to an engine font, cdef is a pointer to an instance of the FOCAFONT data structure. The definition of the FOCAFONT data structure is included in the header file.
 * fFlags:Valid flags are:
 * CDEF_GENERIC:Engine font (not device font)
 * CDEF_BOLD:Font must be made bold
 * CDEF_ITALIC:Font must be made italic
 * CDEF_UNDERLINE:Font must be underlined
 * CDEF_STRIKEOUT:Font must be made overstrike
 * CodePage:Current code page. The presentation driver ignores this field when the font is not a multicode page font that needs translating.
 * charSpacing:Character spacing.

See the OS/2 Programming Guide for examples of these attributes.

Image Attributes
The device image attributes are bundled in a DIMAGEBUNDLE structure:

IMAGEBUNDLE Mask
This mask is used in calls to GreDeviceSetAttributes to identify fields in the IMAGEBUNDLE structure. Valid flags and the fields that they identify are:
 * ibnd:The fields of an IMAGEBUNDLE structure are:
 * lColor:Image foreground color
 * lBackColor:Image background color
 * usMixMode:Image foreground mix mode
 * usBackMixMode:Image background mix mode

Marker Attributes
The device marker attributes are bundled in a DMARKERBUNDLE structure:

MARKERBUNDLE Mask
This mask is used in calls to GreDeviceSetAttributes to identify fields in the MARKERBUNDLE structure. Valid flags and the fields that they identify are:
 * mbnd:The fields of a MARKERBUNDLE structure are:
 * lColor:Marker foreground color.
 * lBackColor:Marker background color.
 * usMixMode:Marker foreground mix mode.
 * usBackMixMode:Marker background mix mode.
 * usSet:Specifies a local identifier (lcid) for the logical font:
 * 0:Base marker set
 * Nonzero:Local identifier for the font identified in the mdef.defSet field of the marker attributes bundle.
 * usSymbol:Specifies the identity of the required marker symbol in the current marker set. If the value of usSymbol does not identify a marker in the current font, the standard default for the font is used. The default for the default font is a cross. For a loaded font, it is the character identified by the usDefaultChar field of the FOCAMETRICS structure.

All values in the range 0-255 are valid. The defined values for the default marker set are: MARKSYM_CROSS Cross MARKSYM_PLUS Plus MARKSYM_DIAMOND Diamond MARKSYM_SQUARE Square MARKSYM_SIXPOINTSTAR Six-point star MARKSYM_EIGHTPOINTSTAR Eight-point star MARKSYM_SOLIDDIAMOND Filled diamond MARKSYM_SOLIDSQUARE Filled square MARKSYM_DOT Dot MARKSYM_SMALLCIRCLE Small circle MARKSYM_BLANK Blank
 * Note:MARKSYM_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.
 * sizfxCell:Specifies fixed-point numbers for the width and height of a marker cell in world-coordinate space. This defines the background area for a marker. Each dimension is represented as a signed four-byte integer with a notational binary point between bit 16 and bit 15. Therefore, +2.5 is represented by 00028000h, and -2.5 is represented by FFFD8000h. The value of this attribute only affects the size of markers drawn with an outline (vector) font or marker set. Markers drawn from image (raster) sets are not affected.
 * mdef:The fields of a MARKERDEFS structure are:
 * defSet:Marker set definition. If this value is passed as 0, the presentation driver must use the default marker set. If the CDEF_GENERIC flag is set, this is a pointer to an engine font. Otherwise, it is a device-font identifier defined by the presentation driver.
 * fFlags:Valid flags are:
 * CDEF_GENERIC:Engine font (not device font)
 * CDEF_BOLD:Marker must be emboldened
 * CDEF_ITALIC:Marker must be italicized
 * CDEF_UNDERLINE:Marker must be underlined
 * CDEF_STRIKEOUT:Marker must be struck out
 * CodePage:Code page number.

Bit-Map Functions
Presentation drivers for hardcopy vector devices can return Failure on all bit-map operations. The same bit-map file format is used for bit maps, icons, and pointers. For details, refer to the Presentation Manager Programming Reference.

Color Functions
By default, the color mode for a DC is set to index mode, and the DC has a Logical Color Table set to the values given in the following list. When in index mode, these defaults are always considered to be part of the color table unless they are explicitly overwritten by GreCreateLogColorTable.


 * Note: Presentation drivers that support less than 16 colors must map Value 0 (CLR_BACKGROUND) through Value 15 (CLR_PALEGRAY) to device colors. If GreQueryColorData is called while the default color table is the current color table, the presentation driver returns the device colors.

Default values for the Logical Color Table are:

CLR_BLACK (-1). This index is never loaded explicitly. It always produces black when the default table is in force or when the index is set to RGB. When, with a realized color table and an index that is not RGB, this option is unavailable, it produces CLR_NEUTRAL.

CLR_BACKGROUND (0). This is the natural background color of the device. For a hardcopy device, it is the paper color and for a display device it is the default window color, SYSCLR_WINDOW.

CLR_BLUE (1)

CLR_RED (2)

CLR_PINK (3)

CLR_GREEN (4)

CLR_CYAN (5)

CLR_YELLOW (6)

CLR_NEUTRAL (7) This is a device-dependent contrasting color. For a display device, it is the default window text color, SYSCLR_WINDOWTEXT.

CLR_DARKGRAY (8)

CLR_DARKBLUE (9)

CLR_DARKRED (10)

CLR_DARKPINK (11)

CLR_DARKGREEN (12)

CLR_DARKCYAN (13)

CLR_BROWN (14)

CLR_PALEGRAY (15)

Colors with indexes greater than 15 are device-dependent defaults, which must be defined by the presentation driver. The effective range of the color table, which includes the default color table, is -5 through MaxIndex. Color indexes outside this range that have not been loaded are not used by applications because these colors cannot be guaranteed.

Where physically possible, the default colors are always available on a device. For devices that support more than 16 colors, requested colors can be mapped to colors other than the defaults (when they exist). Such colors cannot be guaranteed to be similar for different devices. They can be different for other releases of applications and presentation drivers. Applications that depend on precise colors beyond the defaults must query the available colors (see GreQueryRealColors) and, when necessary, realize their own color tables (see GreRealizeColorTable).

Support for Monochrome Devices
Presentation drivers for monochrome devices must be able to draw pictures intended for color devices. A simple solution for hardcopy drivers is to map as follows:


 * Background color to paper color.
 * Foreground color to printer foreground except when:
 * In RGB mode. If the foreground RGB matches the default background RGB, use paper color.
 * In index mode. If the RGB foreground index matches the RGB color for Index 0, use paper color.

To map the RGB colors to the device, the presentation driver must first establish the reset color, which is the base color for the device. The reset color can be one of the following:


 * Paper color for a hardcopy device with no loaded color table
 * SYSCLR_WINDOW for a monochrome display with no loaded color table
 * CLR_BACKGROUND for any monochrome device that has a loaded color table

Any color that is not the reset color is considered to be the contrast color. The values for the reset color and contrast color are either 000000h or FFFFFFh. When the reset color is 000000h, the contrast color is FFFFFFh. CLR_TRUE, CLR_FALSE, and CLR_DEFAULT are always honored independently of the reset color. The interpretation of CLR_BLACK and CLR_WHITE depends on the reset color.

When GreQueryNearestColor is called for a monochrome device, the value returned is either the reset color or the contrast color. GreErasePS causes the color to be set to the value of the reset color. GreBitblt can also be used to transfer a color bit map to a monochrome device or bit map. In this case, the source image background color becomes the reset color and all other pels are represented by the contrast color. More sophisticated presentation drivers for monochrome devices should use half-toning for colors to provide more usable output. Half-toning can be applied to all graphic primitives.

GreEscape
The GreEscape handling routine in the presentation driver supports the DevEscape function and its escape codes at the API. While the primary function of GreEscape is to implement the required support for the defined escape codes, it can be used to implement additional escape codes. There is a set of defined ranges for additional escape codes. The range chosen determines how the operating system processes the escape code when it is received as a parameter to DevEscape. On entry to GreEscape, the value of lEscape on the stack identifies the escape code. The action taken is determined by the escape code and the physical device that the presentation driver supports.

Support
GreEscape is called by DevEscape. GreEscape with the escape code, DEVESC_QUERYESCSUPPORT, must be supported by all presentation drivers. Hardcopy drivers also support the DEVESC_STARTDOC, DEVESC_ABORTDOC, DEVESC_NEXTFRAME, and DEVESC_ENDDOC escape codes. The other escape codes are optional. See Defined Escape Codes and the individual escape codes that follow.

Stack Frame
On entry to the GreEscape routine, the stack frame contains:

Return Codes
The handling routine returns:


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

Possible Errors Detected
When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:


 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_INV_LENGTH_OR_COUNT

Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further information.

Defined Escape Codes
The following list shows the escape codes that have been defined for Presentation Manager and the devices to which they apply. GreEscape returns DEVESC_NOTIMPLEMENTED for escape codes that it does not support.

Ranges from DEV_DBE_FIRST (24450) to DEV_DBE_LAST (24455) are reserved for DBCS support and used by DBCS display driver.

Ranges for Additional Escape Codes
The following table indicates the defined ranges for additional escape codes and shows how the operating system processes the escape codes when they are received as parameters to DevEscape:

Line Functions
The style of a line determines whether it is drawn solid, alternating, invisible, or as any one of a combination of dots and dashes. This style is determined by the usType parameter in the LINEBUND structure (see Line Attributes), which can have any one of the ten values shown in the following table. For each usType value, there is an associated 8-bit style mask whose bits form a template that corresponds to whether pels are set ON or OFF when the line is drawn on the device.

The 8-bit style masks used by OS/2 are as follows: The style masks can be put into an array of bytes as illustrated in the following code example:  const BYTE bStyleMask[ ] = { 0xFF,0xAA,0xCC,0xE4,0xA0,0xE7,0xEA,0xFF,0x00,0xAA };  Consider the following code example and comments:  DrawHorizontalLine( SHORT             sY,              /* Y-value               */  SHORT             sX0,             /* Starting x-value      */  SHORT             sX1,             /* Ending x-value        */  USHORT            usStyleRatio,    /* Style ratio           */  USHORT            usState          /* Current mask state    */  PLINEBUNDLE       pLbnd)           /* pLbnd contains usType */ /*  parameter           */ { USHORT            usStateOld;      /* Used for test         */ USHORT           usOrigMask;      /* Original mask         */ USHORT           usMask;          /* Current mask          */ 

The usState WORD structure is set up by the graphics engine. This structure is shown in the following table:
 * Note: This format is different from the way the graphics engine stores this value. The graphics engine keeps the high and low bytes swapped, therefore, the calling routine must swap them before calling this function.

The mask position has three bits and eight possible values, 0-7, that correspond to the number of bits in the style mask. Notice that when the error-term byte overflows (exceeds 0xFF), it will increment the mask position value. To get the unshifted mask value: usMask = usOrigMask = bStyleMasks[pLbnd -> usType]; The mask must be shifted to the current position as shown above: usMask <<= ((usState & 0x700) >> 8); For each pel: for(sX = sX0; sX <= sX1; sX++){ Because many devices have small pel sizes, it is often necessary to set more than one pel ON per corresponding bit in the style mask. This setting is accomplished by using a style ratio, which determines how many pels on the line correspond to a bit in the style mask. As an example, for each pel on the line, the most significant bit of the style mask is consulted. If this bit is 1, the pel is drawn. If this bit is 0, the pel is not drawn, as shown in the following example: if(usMask & 0x80) DrawPel(sX,sY);

usStateOld = usState; The style ratio is then added to the error-term byte of the usState parameter. When the error-term byte overflows, the mask position value (high byte of usState) is incremented to the next position. If the mask position exceeds 7, it is reset to 1.0: usState = (usState + usStyleRatio) & 0x7ff; The mask itself must now be shifted appropriately: if(HIBYTE(usState) | = HIBYTE(usStateOld)){    /* Has it changed? */  if(HIBYTE(usState) == 0)                     /* Back to zero? */     usMask - usOrigMask;                      /* Yes, reset it     */ else usMask <<= 1;                            /* Else shift it     */ } . . . return(usState);                               /* Return the state /* for the next line */ Styled line information is usually maintained by the presentation driver in the Device Context (DC) instance data structure. See Device Context. Remember that the DC is a structure that the presentation driver creates. The definition of the DC data structure is specific and can be unique for each unique presentation driver. This information can include: typedef struct _DC { . . . USHORT      usStyleRatioX;    /* X-style ratio                   */ USHORT      usStyleRatioY;    /* Y-style ratio                   */ ULONG       lLineStyle;       /* Current state information       */ /*  (GRE Backward Format)         */ LINEBUNDLE  lbnd;             /* Linebundle information contains */ /*  usType parameter              */ BYTE        bMyCurrentMask;   /* Current style mask              */ . . . DC; typedef DC *PDC; The lLineStyle value has much of the same information as the usState parameter in the example function. Its value is concurrently maintained by the graphics engine but has a different format from the example above. The graphics engine can set or query this value by calling the functions GreSetLineOrigin or GreGetLineOrigin, respectively. It is therefore reasonable to keep a copy in the graphics engine format.

The graphics engine's format for this value consists of three values: They are stored in the following manner: 8 bits Error-term byte 5 bits GRE internal flags 3 bits Mask position If two bytes of this low WORD are compared to the WORD in the previous example, they are swapped.
 * A flag indicating whether or not to draw the first pel of the current line
 * The current mask position (explained earlier)
 * The error-term byte (explained earlier)
 * High WORD: 16-bits. Draw first pel flag. Can be 0x0000 (do not draw first pel) or 0x0001 (draw first pel).
 * Low WORD 1: 6 bits, consisting of:

Style Radio
The most obvious way to generate styled lines is to draw a circle at the origin, and then draw a dashed line from the origin to all points on the circle. The number of dashes in each line will be the same and the lengths of all the dashes drawn will be equal. This is executed on microcode on some devices. However, it is too costly in terms of processor time to implement it in software. Therefore, an alternative method called the "maximum metric" is used in the graphics engine. This method can be visualized by drawing a square centered at the origin, and then drawing a dashed line to any point on the square. The number of dashes in each line will be the same but the lengths of the dashes will vary.

The maximum metric states that:  {y-major = ABS(y1-y0) > ABS(x1-x0) where (x0, y0) and (x1, y1) are the endpoints of the line in device-coordinate space}, add pDC -> usStyleRatioY to error-term value upon each increment of Y as the line is drawn   {x-major = ABS(x1-x0) > ABS(y1-y0) in device-coordinate space}, add pDC -> usStyleRatioX to error-term value upon each increment of X as line is drawn  The line style as viewed on the device is determined, as follows:  if (ABS(pDC -> usStyleRatioX * sDeltaX) > ABS(pDC -> usStyleRatioY * sDeltaY)) LineStyleAsItLooksOnTheDevice = X-MAJOR; else LineStyleAsItLooksOnTheDevice = Y-MAJOR;  This might be coded similar to the following:  if (ABS(pDC -> usStyleRatioX * sDeltaX) > ABS(pDC -> usStyleRatioY * sDeltaY)) { usChangeInStateForOnePixel = pDC -> usStyleRatioX; fAddThisWhen = X_INCREMENTS; } else { usChangeInStateForOnePixel = pDC -> usStyleRatioY; fAddThisWhen = Y_INCREMENTS; }  It follows that for a line (AB), the total change in style state can be expressed as:  usChangeInStateForWholeLine = MAX(ABS(pDC -> usStyleRatioX * sDeltaX),                             ABS(pDC -> usStyleRatioY * sDeltaY))  where sDeltaX = Bx-Ax and sDeltaY = By-Ay
 * If the line is Y-major as viewed on the device:
 * If the line is X-major as viewed on the device:

For example, an EGA device that has a 640 x 350 (X-to-Y) resolution is displayed on a display that has an X-to-Y ratio of 1-to-.75. To calculate the aspect ratio:

X/Y Ratio = 350/(640*.75) = .72917  Therefore: X = Y*.72917 or Y = X/.72917

This indicates that a pel is taller than it is wide. The following figure visually describes the ratio.

Pel Aspect Ratio

Assume that four pels in the X-direction is the desirable size of a styled-line dot. Because this display is 9.5 inches across and there are 640 pels across, the length of the four pels is:  (9.5inches/640pels) * 4pels = .059375inches This results in a pDC -> usStyleRatioX = 64&: 64 = 256/4  Note that 256 = 0x100, which corresponds to an overflow of the error-term byte into the mask position. To get the equivalent pDC → usStyleRatioY value, use the desired distance and multiply it by Y pels per inch, as follows:  (.059375inches * 350 pels)/7.125inches = 2.917pels Therefore:pDC ► usStyleRatioY = 256/2.917 = 87.76 (rounded to 88) </PRE> An easier method is to calculate pDC ► usStyleRatioY from pDC ► usStyleRatioX, using the following aspect ratio:

pDC ► usStyleRatioY = pDC ►  usStyleRatioX / .72917 = 87.76 (rounded to 88)

Note that the values pDC ► usStyleRatioX and pDC ► usStyleRatioY are the same as those returned by GreGetStyleRatio.

An example of what is meant by "as viewed on the device" follows:
 * If a line is drawn from (0, 0) to (100, 100) pels on the device, it is drawn as a diagonal line but does not look diagonal to an observer.Instead, it looks like a line drawn to (100, 73).


 * This change of perspective is because of the aspect ratio. Each unit (pel) in the X-direction covers only .72917 as much distance as a pel in the Y-direction. The images on the device do not look skewed because this ratio is factored in when the application draws a diagonal line (for example, by drawing from (0, 0) to (73, 100)).


 * The styled lines are affected when a line that is drawn in pels as X-major appears on the device as Y-major. In this case, a line drawn from (0, 0) to (85, 64) is X-major as drawn in pels (because ABS(x1-x0) > ABS(y1-y0)), but appears on the device to be Y-major. Notice that this line must be styled Y-major to look correct on the device, as follows:

 usChangeInStateForOnePixel = ABS(pDC -> usStyleRatioX * sDeltaX) > ABS(pDC -> usStyleRatioY                            * sDeltaY)? pDC -> usStyleRatioX :pDC -> usStyleRatioY; </PRE> where: ABS(pDC -> usStyleRatioX * sDeltaX) = 64 * 85 = 5440 ABS(pDC -> usStyleRatioY * sDeltaY) = 88 * 64 = 5632


 * Because 5440 < 5632, the line is styled Y-major by using pDC ► usStyleRatioY. The X-major diagonal line drawing routine usually adds pDC ► usStyleRatioX to the error-term byte for every increment of X. This is correct if the aspect ratio is 1:1.


 * However, because the aspect ratio is not 1:1, pDC → usStyleRatioY must be used in this case for every increment of Y, although the line is drawn as an X-major line with the X-major routine. This means that regardless of which way the line is drawn, it must be styled according to how it looks on the device, which is determined by the maximum metric method described previously.

LINETYPE_ALTERNATE is a special case of styled line. When drawing a line of this type (pLbnd → usType = LINETYPE_ALTERNATE), the X and Y style ratios are temporarily set to 256 to set every other pel on the line ON. Notice that changing the values returned by GreGetStyleRatio is not necessary because the graphics engine does not call this function if the line type is LINETYPE_ALTERNATE.

PolyShortLine and Styling
The graphics engine determines how to style the PolyShortLine, and either sets the PSL_YMAJOR bit of the style field or clears it to 0. Therefore: if(psl ► usStyle & PSL_YMAJOR) {

Style it Y-major by adding pDC ► usStyleRatioY to the error-term value upon each increment of y as it is drawn. } else {

Style it X-major by adding pDC ► usStyleRatioX to the error-term value upon each increment of x as it is drawn. }

First and Last Pel Considerations
The presentation driver ensures that a series of line, arc, and fillet orders all join up correctly including the ON/OFF counts defined by the current line attributes. For example, when drawing connected lines (PolyLines), the handling routine must not draw the first pel of the second and subsequent lines. Typically, the presentation driver maintains a flag in the DC instance data structure to indicate whether the first pel of a line is to be drawn. This flag is set by GreSetCurrentPosition and cleared by any subsequent drawing primitive. To ensure that a figure is closed correctly, GreCloseFigure does not draw the last pel in the closure line.

Some orders are defined as move type operations. A move causes three things to happen:
 * The line style sequence is reset.
 * The next line, arc, fillet, or partial arc primitive is drawn with first and last pel (subject to the line style sequence).
 * In an area, if the current figure is not closed (that is, the current device coordinate position is not the same as the start device coordinate position), an implicit closure line is drawn to close it.

Subsequent start line, arc, fillet, and partial arc primitives are drawn to include the last but not the first pel (subject to the line style sequence). Any closed figure (full arc, box, or pie slice drawn with a boundary), is drawn with its boundary complete (no missing pels) and with the line-pattern sequence honored around all the parts of its boundary. Such closed figures are not considered to be move type operations and, therefore, allow construction of complex area boundaries.

Move type operations are:
 * GreSetCurrentPosition.
 * Any GreSetxxx function, such as GreSetModelTransform or GreSetWindow/ViewportTransform, that changes or might change the transform from world-coordinate space to device coordinates.
 * Any GreSetxxx function, such as GreSetViewingLimits, which changes or might change the current clipping.

A different set of rules is necessary to construct a boundary for scan-line area filling. For example a rule might be "ignore line style and draw all lines solid with first pel OFF, last pel ON" (see GreGetLineOrigin). This boundary is different from the boundary that is drawn on the screen after the interior is filled. Functions such as GrePolyLine, GreArc, and GrePolyFillet that are preceded by a move operation are drawn with the first pel ON and the last pel set OFF.

Mandatory Functions for All Drivers by Category
Related mandatory functions for all presentation drivers can be grouped together into the following categories:


 * Attribute Functions (INCL_GRE_DEVMISC1)
 * GreDeviceGetAttributes
 * GreDeviceSetAttributes
 * GreDeviceSetGlobalAttribute
 * GreGetPairKerningTable


 * Bit-Map Functions (INCL_GRE_BITMAPS)
 * GreBitblt
 * GreDeviceCreateBitmap
 * GreDeviceDeleteBitmap
 * GreDeviceSelectBitmap
 * GreDrawBits
 * GreDrawBorder
 * GreGetBitmapBits
 * GreGetPel
 * GreImageData
 * GreSetBitmapBits
 * GreSetPel


 * Color Table Functions (INCL_GRE_COLORTABLE)
 * GreCreateLogColorTable
 * GreQueryColorData
 * GreQueryColorIndex
 * GreQueryLogColorTable
 * GreQueryNearestColor
 * GreQueryRealColors
 * GreQueryRGBColor
 * GreRealizeColorTable
 * GreUnrealizeColorTable


 * Device Functions 2 (INCL_GRE_DEVMISC2)
 * GreDeviceQueryFontAttributes
 * GreDeviceQueryFonts
 * GreErasePS
 * GreNotifyClipChange
 * GreNotifyTransformChange
 * GreRealizeFont


 * Device Functions 3 (INCL_GRE_DEVMISC3)
 * GreAccumulateBounds
 * GreDeviceSetDCOrigin
 * GreGetBoundsData
 * GreGetCodePage
 * GreGetDCOrigin
 * GreGetLineOrigin
 * GreLockDevice
 * GreResetBounds
 * GreSetCodePage
 * GreSetLineOrigin
 * GreUnlockDevice


 * GreEscape Functions (INCL_GRE_DEVICE)
 * GreEscape DEVESC_ABORTDOC
 * GreEscape DEVESC_ACQUIREFB
 * GreEscape DEVESC_BREAK_EXTRA
 * GreEscape DEVESC_CHAR_EXTRA
 * GreEscape DEVESC_DBE_FONTMANAGEMENT
 * GreEscape DEVESC_DEACQUIREFB
 * GreEscape DEVESC_DRAFTMODE
 * GreEscape DEVESC_ENDDOC
 * GreEscape DEVESC_EXTGET
 * GreEscape DEVESC_EXTPUT
 * GreEscape DEVESC_EXTQUERY
 * GreEscape DEVESC_FLUSHOUTPUT
 * GreEscape DEVESC_GETAPERTURE
 * GreEscape DEVESC_GETCP
 * GreEscape DEVESC_GETJOBID
 * GreEscape DEVESC_GETSCALINGFACTOR
 * GreEscape DEVESC_HWREQUEST
 * GreEscape DEVESC_NEWFRAME
 * GreEscape DEVESC_NEXTBAND
 * GreEscape DEVESC_QUERYESCSUPPORT
 * GreEscape DEVESC_QUERYFB
 * GreEscape DEVESC_QUERYVIOCELLSIZES
 * GreEscape DEVESC_RAWDATA
 * GreEscape DEVESC_REGISTER
 * GreEscape DEVESC_SETMODE
 * GreEscape DEVESC_SETUPBLITTERNOTIFY
 * GreEscape DEVESC_STARTDOC
 * GreEscape DEVESC_STD_JOURNAL
 * GreEscape DEVESC_SWITCHBANK
 * GreEscape DEVESC_VIDEOHIDDEN
 * GreEscape DEVESC_VRAMALLOC


 * Line Functions (INCL_GRE_LINES, INCL_GRE_SCANS)
 * GreDisjointLines
 * GreDrawLinesInPath
 * GreGetCurrentPosition
 * GrePolyLine
 * GrePolyScanline
 * GrePolyShortLine
 * GreSetCurrentPosition


 * Marker Functions (INCL_GRE_MARKERS)
 * GrePolyMarker


 * Query Functions (INCL_GRE_DEVICE)
 * GreQueryDeviceBitmaps
 * GreQueryDeviceCaps
 * GreQueryDevResource

For a complete description of each Mandatory function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * Text Functions (INCL_GRE_STRINGS)
 * GreCharString
 * GreCharStringPos
 * GreQueryCharPositions
 * GreQueryTextBox
 * GreQueryWidthTable

Mandatory Functions for Display Drivers
This section describes the functions that must be supported by the display driver for the primary screen. Although these functions are not required for hardcopy drivers, hardcopy drivers should provide a default routine to handle the functions described in this section, and at FillLogicalDeviceBlock time, put a pointer to the default routine in the relevant entries in the dispatch table. The default routine will post a warning PMERR_DEV_FUNC_NOT_INSTALLED and return BOOLEAN TRUE.

Descriptions of these mandatory functions for display drivers are provided. The functions are grouped according to the conditional include sections of the header file, as follows:


 * AVIO functions (INCL_AVIOP, INCL_GRE_DEVMISC1)
 * Bit-map functions (INCL_GRE_BITMAPS)
 * Device functions 2 (INCL_GRE_DEVMISC2)
 * Device functions 3 (INCL_GRE_DEVMISC3)
 * Miscellaneous screen functions (INCL_GRE_PICK, INCL_WINPOINTERS)

Each description shows what the handling routine is expected to do, the parameters passed to the routine, and the values that the routine returns.

AVIO Functions
Advanced VIO (AVIO) functions are used to display characters. These functions must be supported for Display DCs. Hardcopy drivers do not support AVIO functions. When writing to an AVIO presentation space, an application must ensure that windows containing alphanumeric data are device-cell-aligned, where appropriate. The presentation driver can determine whether any characters that are not cell-aligned are visible. Most column, row, length, width, and height values correspond to cells within the presentation space Logical Video Buffer (LVB), whose origin is assumed to be at the bottom-left corner of the buffer (0,0).

The presentation driver is expected to clip alphanumeric data to the DC region. This is performed in the same way as it is for normal graphics, by enumerating the rectangles using GreGetClipRects and clipping each line to a single rectangle. Although the presentation driver is neither expected to test for correlation hits nor to accumulate GPI_BOUNDS, it should accumulate USER_BOUNDS for AVIO functions if the COM_ALT_BOUNDS command flag is set.

The VIO presentation space is passed to the display driver as a pointer to a VioPresentationSpace structure. The display driver uses this structure to extract the current state data to allow it to update the display. The VioPresentationSpace structure is defined as:


 * PresentationSpaceLock:Lock (not used by the presentation driver).
 * pLVB:Pointer to the logical video buffer (LVB). The LVB is a two-dimensional array of character cells and is assumed to begin at offset 0 within the segment. The presentation driver must not alter the contents of this field.
 * pBVSCB:Not used by the presentation driver.
 * rgfAVio:Not used by the presentation driver.
 * CellByteSize:Size in bytes of a cell in the LVB. This value is either 2 or 4. The presentation driver must not alter the contents of this field.
 * BufferRowCount:Number of cell rows in the logical video buffer. The presentation driver must not alter the contents of this field.
 * BufferColumnCount:Number of cell columns in the logical video buffer. The presentation driver must not alter the contents of this field.
 * WindowOriginRow:Row index for the logical video buffer. This field, together with the parameter WindowOriginColumn, indicates the logical video buffer cell that is drawn in the bottom left of the window's client area. The presentation driver must not alter the contents of this field.
 * WindowOriginColumn:Column index for logical video buffer (see WindowOriginRow). The presentation driver must not alter the contents of this field.
 * TextCursorRow:Row coordinate of flashing text cursor relative to the logical video buffer. The presentation driver must not alter the contents of this field.
 * TextCursorColumn:Column coordinate of flashing text cursor relative to the logical video buffer. The presentation driver must not alter the contents of this field.
 * TextCursorStartLine:First scan line of a character-cell image overlaid by the text cursor. Lines in the cell image are numbered from top to bottom. The first line is 0. The presentation driver must not alter the contents of this field.
 * TextCursorEndLine:Last scan line of a character-cell image, overlaid by the text cursor. The presentation driver must not alter the contents of this field.
 * TextCursorWidth:Width of text cursor in pels. The presentation driver must not alter the contents of this field.
 * TextCursorVisible:Indicates whether the cursor is visible (nonzero) or invisible (zero). The presentation driver must not alter the contents of this field.
 * CellImageHeight:Height of character cell in pels. When the value passed is 0 or invalid, the presentation driver should reset it to the device default value.
 * CellImageWidth:Width of character cell in pels. When the value passed is 0 or invalid, the presentation driver should reset it to the device default value.
 * CodePageID:ID of current code page for this presentation space. When the value passed is 0 or invalid, the presentation driver should reset it to the device default value.
 * WindowHeight:Not used by the presentation driver.
 * WindowWidth:Not used by the presentation driver.
 * hConsoleDisplayContext:Device context handle associated with the presentation space. The presentation driver must not alter the contents of this field.
 * hVioWindow Not used by the display driver.
 * RowOrgLatch:See "ColOrgLatch".
 * ColOrgLatch:Window-origin coordinates (WindowOriginRow and WindowOriginColumn) saved on completion of the last call to GreUpdateCursor. RowOrgLatch and ColOrgLatch are used by the display driver to record the state of the currently displayed cursor. They are interrogated by GreUpdateCursor to determine whether the cursor has moved.
 * CursorRow:See "CursorCol".
 * CursorCol:Cursor coordinates (TextCursorRow and TextCursorColumn) saved on completion of the last call to GreUpdateCursor. These fields are used by the display driver to record the state of the currently displayed cursor so that it can be successfully erased.
 * CursorStartLine:See "CursorEndLine".
 * CursorEndLine:Cursor start and end lines (TextCursorStartLine and TextCursorEndLine) saved on completion of the last call to GreUpdateCursor. These fields are used by the display driver to record the state of the currently displayed cursor so that it can be successfully erased.
 * CursorWidth:Cursor width (TextCursorWidth) saved on completion of the last call to GreUpdateCursor. This field is used by the display driver to record the state of the currently displayed cursor so that it can be successfully erased.
 * PartialCellAdjust:This is a negative value reflecting the partial cell height that must be below the bottom of the window to ensure that a complete cell is positioned at the top of the window (actual window height = WindowHeight rounded up to next complete character cell - PartialCellAdjust). The presentation driver must not alter the contents of this field.
 * XLatch:See "YLatch".
 * YLatch:Pel coordinates of the bottom-left corner of the cursor rectangle relative to the bottom-left corner of the window.
 * WidthLatch:See "HeightLatch".
 * HeightLatch:The height and width in pels of the cursor saved on completion of the last call to GreUpdateCursor. These are taken to be CellImageHeight and the difference between TextCursorStartLine and TextCursorEndLine, taking account of any wrapping. The width and height latches are used by GreUpdateCursor to record the screen region corresponding to an exclusive-OR cursor.
 * CellHeightLatch:The height in pels of the character cell for which the cursor was last drawn. This parameter is used to detect cell height changes. These values were saved on completion of the last call to GreUpdateCursor.
 * rgfShieldStates:Flags:
 * CursorShowing (0x0001) Cursor is visible on the screen. This flag is maintained by the display driver.
 * fHasTheFocus (0x0002) This window has the input focus. This flag is not modified by the display driver.
 * fCursorIsOn (0x0004) Set to indicate that this is the ON phase of the blink cycle. The cursor should be invisible during the OFF phase of the blink cycle. This flag is not modified by the display driver.


 * pFontsLoaded[3]:Array of pointers for AVIO fonts 1, 2, and 3.
 * pMapFontsLoaded[3]:Array of pointers to code page maps for AVIO Fonts 1, 2, and 3.
 * FormatID Presentation-space format. This identifies the format of the attribute bytes in the LVB, as follows:
 * 0H CGA
 * 0H Extended
 * 70H World-wide format
 * The presentation driver must not alter the value of this field.


 * lpNLSExt:Pointer to a National Language Support (NLS) extension structure where Double-Byte Character Set (DBCS) environment vectors are set for AVIO Fonts 1, 2, and 3. If the display driver is required to display DBCS, it must maintain the array of DBCSEvInfox4x, instead of DBCSEvInfox0x. When the display driver provides NLS, it must set the DBCS vectors for lcid 1-3.
 * Each character cell is contained in a two-byte or four-byte array in the LVB. The format of the character-cell array is:
 * Code Point Position of the character in the code table.
 * CGA Attribute Byte Character attributes. The four low-order bits represent the foreground color and the high-order bits represent the character background color. Each 4-bit color value corresponds to an explicit 24-bit RGB value. The RGB values are defined within the graphics engine and match the colors available on a CGA device.
 * Extended Attribute Byte Applies only to four-byte cells. It is defined as:
 * Bit 7 Underscore.
 * Bit 6 Reverse video.
 * Bit 4 Background transparency. When set, the background is transparent. When not set, the background is opaque.
 * Bits 1-0 Character Set 0, 1, 2, or 3.
 * Extended Attribute Byte (World-wide format). Applies only to four-byte cells. It is defined as:
 * Bit 7 Underscore.
 * Bit 6 Reverse video.
 * Bit 4 Background transparency. When set, the background is transparent. When not set, the background is opaque.
 * Bit 3 Left vertical grid.
 * Bit 2 Top horizontal grid.
 * Bits 1-0 Character Set 0, 1, 2, or 3.
 * Spare Attribute Byte Applies only to four-byte character cells.
 * It is reserved for the system.
 * Spare Attribute Byte (World-wide format). Applies only to four-byte character cells.
 * Bit 7 DBCS trailing byte maintained by the operating system.
 * Bits 6-1 Reserved for the system.
 * Bit 0 DBCS byte maintained by the operating system.
 * Note that applications are not allowed to set bit 7 and bit 0.

Mandatory Functions (for Display Driver) by Category
Related mandatory functions for display drivers can be grouped together into the following categories:


 * AVIO Functions (INCL_AVIOP, INCL_GRE_DEVMISC1)
 * GreCharRect
 * GreCharStr
 * GreDeviceSetAVIOFont
 * GreScrollRect
 * GreUpdateCursor


 * Bitmap Functions (INCL_GRE_BITMAPS)
 * GreDeviceSetCursor
 * GreRestoreScreenBits
 * GreSaveScreenBits


 * Device Functions 2 (INCL_GRE_DEVMISC2)
 * GreDeviceInvalidateVisRegion
 * GreGetStyleRatio
 * GreSetStyleRatio


 * Device Functions 3 (INCL_GRE_DEVMISC3)
 * GreDeath
 * GreResurrection

For a complete description of each Mandatory function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * Miscellaneous Functions (INCL_GRE_PICK, INCL_WINPOINTERS)
 * GreGetPickWindow
 * GreSetColorCursor
 * GreSetPickWindow

Direct Interface Video Extensions (DIVE) Functions
The DIVE architecture provides a device-independent interface for direct access to display memory through DEVESC_ functions. Using the DIVE architecture, the OS/2 software motion video decompression subsystem writes directly to video memory. The subsystem performs window clipping, color translation and scaling required to write the data in a window. On bank-switched configurations, the software must detect when video memory bank boundaries are crossed, then switch the bank accordingly.

DIVE Display Engine Functional Characteristics
The OS/2 Version 3 DIVE Display Engine is a single, system-level API that enables efficient transfer of data to video memory with clipping, scaling and color translation. The Display Engine exports the following functions:
 * Query for display capabilities
 * Open instance
 * Visible region specification
 * Allocation of image data buffers
 * Buffer to screen/buffer-to-buffer transfer (blitter) setup
 * 8-bit CLUT color palette simulation/specification
 * Transfer buffer-to-image display/transfer buffer-to-buffer
 * Utillity functions useful for direct access, including window starting address calculation
 * Frame buffer acquire/deacquire
 * VRAM bank selection (for bank-switched displays)
 * Close instance

Enhanced Direct Interface Video Extension (EnDIVE)
The DIVE architecture has been enhanced in OS/2 Version 3 to support motion video accelerator hardware. This enhanced architecture is called EnDIVE. It provides additional DEVESC_ functions for querying information about the color formats supported by the hardware, video memory management and image processing.

The Display Engine detects and uses acceleration hardware (via EnDIVE) and substitutes software algorithms whenever necessary.

The DIVE and EnDIVE DEVESC_ functions are listed below: For detailed information about the DIVE architecture, refer to the OS/2 Multimedia Application Programming Guide and to the individual functions included in Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * GreEscape DEVESC_ACQUIREFB
 * GreEscape DEVESC_DEACQUIREFB
 * GreEscape DEVESC_EXTGET
 * GreEscape DEVESC_EXTPUT
 * GreEscape DEVESC_EXTQUERY
 * GreEscape DEVESC_GETAPERTURE
 * GreEscape DEVESC_HWREQUEST
 * GreEscape DEVESC_QUERYFB
 * GreEscape DEVESC_REGISTER
 * GreEscape DEVESC_SETUPBLITTERNOTIFY
 * GreEscape DEVESC_SWITCHBANK
 * GreEscape DEVESC_VIDEOHIDDEN
 * GreEscape DEVESC_VRAMALLOC

Simulated Functions
These functions are simulated by handling routines in the graphics engine and are called through pointers in the default dispatch table. Any simulated functions can be "hooked" to improve performance or to exploit special features of the device. Hooking is performed by overwriting the pointer in the presentation driver's copy of the dispatch table with a pointer to the presentation driver's handling routine. If this is done, the original pointer must be saved in order to pass calls to the engine's handling routine.

When the presentation driver has hooked a function, all calls to that function are passed through the dispatch table directly to the driver's handling routine. If the presentation driver cannot completely handle a hooked function, it can pass the call to the engine's routine for completion.

The functions in this section are grouped according to the conditional include sections of the header file: Each description defines what the handling routine is expected to do, the parameters passed to the routine, and the values that the routine returns.
 * Arc functions (INCL_GRE_ARCS)
 * Area and Path functions (INCL_GRE_PATHS)
 * Clip functions (INCL_GRE_CLIP)
 * Line functions (INCL_GRE_LINE)
 * Palette Manager functions (INCL_GRE_PALETTE)
 * Region functions (INCL_GRE_REGIONS)
 * Transform functions (INCL_GRE_XFORMS)

Arc Functions
Drawing functions pass individual drawing orders to the graphics engine. The graphics engine then draws, correlates, and takes, or takes bounds on, the drawing primitives as directed by the flags. The graphics engine is assumed to clip to the appropriate part of the window, which is the region excluding any window border or frills.

Coordinates are passed as signed 32-bit numbers in a logical space called "world-coordinate space". Angles are also passed as signed 32-bit numbers. Zero refers to the direction of the positive X-axis; 2(31st power) represents 360°. Positive values are counterclockwise from the positive X-axis.

Area and Patch Functions
A "path" is an area or a shape that can be used to define:
 * Wide lines and curves to which changes of scale can be applied
 * Shapes and areas for filling
 * Irregular shapes to which subsequent primitives are clipped. This is known as a "clip path".

Clip Functions
"Clip regions" are defined as rectangles in world coordinates. The boundaries of a clip region rectangle are inclusive of the rectangle they define.

Region Functions
"Regions" are defined as rectangles in device coordinates. They are inclusive at the bottom-left boundary and exclusive at the top-right boundary. That is, the top-right coordinates are outside the rectangle they define and the bottom-left coordinates are inside the rectangle. When both coordinate pairs are equal, the rectangle dimension is 0.

Transform Functions
"Transform functions" provide a complete viewing pipeline whereby coordinates are transformed from world-coordinates to model space to presentation page to device space. The following figure diagrams the viewing pipeline.



Matrix Element Format
The matrix elements for the model and viewing transforms are held in XFORM structures: fxM11 fxM12 fxM21 fxM22 lM41 lM42 M11, M12, M21, and M22 are fixed-point numbers represented as signed four-byte integers with a notational binary point between bits 16 and 15: +2.5 is represented by 00028000H -2.5 is represented by FFFD8000H -0.5 is represented by FFFF8000H M41 and M42 are signed four-byte numbers.

Device Transform Definition by Presentation Page Viewport
For a transform, defined by viewport and window rectangles whose bottom-left and top-right coordinates are represented by (X1, Y1), (X2, Y2), (X3, Y3), and (X4, Y4), respectively, the matrix elements are determined as shown in the following example. The point (X3-1/2, Y3-1/2) transforms to (X1-1/2, Y1-1/2), and the point (X4+1/2, Y4+1/2) transforms to (X2+1/2, Y2+1/2). Therefore:  M12 = 0 M21 = 0

If X4 >= X3 then M11 = (X2-X1+1) / (X4-X3+1) M41 = (X1*X4-X3*X2+1/2 * (X2-X4 + X1-X3)) / (X4-X3+1)

If X4 < X3 then M11 = (X2-X1+1) / (X4-X3-1) M41 = (X1*X4-X3*X2-1/2 * (X2+X4+X1+X3)) / (X4-X3-1)

If Y4 >= Y3 then M22 = (Y2-Y1+1) / (Y4-Y3+1) M42 = (Y1*Y4-Y3*Y2+1/2 * (Y2-Y4 + Y1-Y3)) / (Y4-Y3+1)

If Y4 < Y3 then M22 = (Y2-Y1+1) / (Y4-Y3-1) M42 = (Y1*Y4-Y3*Y2-1/2 * (Y2+Y4+Y1+Y3)) / (Y4-Y3-1) </PRE>
 * Note: X4 is always greater than X3 and Y4 is always greater than Y3.

In the case of device transforms, (X3, Y3) is always (0, 0), Y4 is always greater than Y3, and the device space coordinates (X2, Y2) are exclusive. This simplifies the formula to:  M12 = 0 M21 = 0

M11 = (X2-X1) / (X4+1) M41 = (X1*X4+1/2 * (X2-1-X4+X1)) / (X4+1) = X1+1/2 (M11-1)

M22 = (Y2-Y1) / (Y4+1) M42 = (Y1*Y4+1/2 * (Y2-1-Y4+Y1)) / (Y4+1) = Y1+1/2 (M22-1) </PRE>

Bounds, Correlation, and Clipping
All presentation drivers must support bounds computation for both GPI bounds (COM_BOUND) and user bounds (COM_ALT_BOUND). Bounds are calculated on unclipped primitives for all operations that draw to the device, including AVIO functions. GPI bounds are passed in model space coordinates. User bounds are calculated in device-coordinate space. To prevent inaccuracies from occurring when the transform changes, the typical presentation driver maintains bounds in both coordinate sets in its instance data structure. It then accumulates the transforms as they occur.

Correlation is performed in page-coordinate space on the output of primitives that have been clipped only to the viewing limits and graphics field. Correlation is also performed on all operations that draw to the device, except the AVIO function. Note that hardcopy drivers are not required to perform correlation.

Simulation Functions by Category
Related simulated functions can be grouped together into the following categories:


 * Arc Functions (INCL_GRE_ARCS)
 * GreArc
 * GreBoxBoth
 * GreBoxBoundary
 * GreBoxInterior
 * GreFullArcBoth
 * GreFullArcBoundary
 * GreFullArcInterior
 * GreGetArcParameters
 * GrePartialArc
 * GrePolyFillet
 * GrePolyFilletSharp
 * GrePolySpline
 * GreSetArcParameters


 * Area and Path Functions (INCL_GRE_PATHS)
 * GreAreaSetAttributes
 * GreBeginArea
 * GreBeginPath
 * GreCloseFigure
 * GreEndArea
 * GreEndPath
 * GreFillPath
 * GreModifyPath
 * GreOutlinePath
 * GreRestorePath
 * GreSavePath
 * GreSelectClipPath
 * GreStrokePath


 * Clip Functions (INCL_GRE_CLIP)
 * GreCopyClipRegion
 * GreExcludeClipRectangle
 * GreGetClipBox
 * GreGetClipRects
 * GreIntersectClipRectangle
 * GreOffsetClipRegion
 * GrePtVisible
 * GreQueryClipRegion
 * GreRectVisible
 * GreRegionSelectBitmap
 * GreRestoreRegion
 * GreSaveRegion
 * GreSelectClipRegion
 * GreSelectPathRegion
 * GreSetupDC
 * GreSetXformRect


 * Line Functions (INCL_GRE_LINE)
 * GreDrawRLE
 * GrePolygonSet


 * Palette Manager Functions (INCL_GRE_PALETTE)
 * GreDeviceAnimatePalette
 * GreDeviceCreatePalette
 * GreDeviceDeletePalette
 * GreDeviceResizePalette
 * GreDeviceSetPaletteEntries
 * GreQueryHWPaletteInfo
 * GreQueryPaletteRealization
 * GreRealizePalette
 * GreUpdateColors


 * Region Functions (INCL_GRE_REGIONS)
 * GreCombineRectRegion
 * GreCombineRegion
 * GreCombineShortLineRegion
 * GreCreateRectRegion
 * GreDestroyRegion
 * GreEqualRegion
 * GreGetRegionBox
 * GreGetRegionRects
 * GreOffsetRegion
 * GrePaintRegion
 * GrePtInRegion
 * GreRectInRegion
 * GreSetRectRegion

For a complete description of each Simulated function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * Transform Functions (INCL_GRE_XFORMS)
 * GreConvert
 * GreGetGlobalViewingXform
 * GreGetGraphicsField
 * GreGetModelXform
 * GreGetPageUnits
 * GreGetPageViewport
 * GreGetViewingLimits
 * GreGetWindowViewportXform
 * GreMultiplyXforms
 * GreRestoreXform
 * GreRestoreXformData
 * GreSaveXform
 * GreSaveXformData
 * GreSetGlobalViewingXform
 * GreSetGraphicsField
 * GreSetModelXform
 * GreSetPageUnits
 * GreSetPageViewport
 * GreSetViewingLimits
 * GreSetWindowViewportXform

Palette Manager Functions
The hardware (HW) palette, or device physical palette, is divided into two parts: At startup, the HW palette is assigned the device default colors because there are no Palette Manager DCs at this time. When Palette Manager palettes are created and subsequently selected and realized, their palette colors must be allocated slots in the HW palette. Therefore, the proportion of the HW palette allocated to the default colors is reduced to produce free slots, which then can be allocated to the Palette Manager palettes. If the number of Palette Manager slots is reduced, the number of slots allocated to the default colors is increased to improve the appearance of the non-Palette Manager DCs.
 * Device default colors, which are the entries used by nonpalette manager DCs
 * Palette Manager palette colors

Non-Palette Manager DCs can only use the default colors found in the device HW palette. There are five possible sizes of device default colors: 256-, 128-, 64-, 32-, and 16-entries. The 256-entry default palette is the same as the standard 8514 8bpp palette. The 16-entry default palette is the same as VGA palette. For OD_MEMORY DCs, the 256-entry device default palette is always used. For OD_DIRECT DCs, the device HW palette can be changed to permit allocation of HW palette slots to Palette Manager DCs.

Within the HW palette, the device default colors are always positioned symmetrically in two halves at the top and bottom of the HW palette. The slots in the center are used for Palette Manager slots. Therefore, when mixing the device default colors, the result is always another device default color. The colors within the device default palette are arranged so that the inverse mixes always give the expected results.

Accessing The Device Default Palette
The device default palette is accessed through two pointers, DirectDeviceDefaultPalette and MemoryDeviceDefaultPalette, depending on whether an OD_DIRECT or OD_MEMORY DC is in use. The size of the DirectDeviceDefaultPalette is always kept in ulDirectDeviceDefaultPaletteSize.

The direct device default palette is changed by the ReduceDefaultPaletteSize and IncreaseDefaultPaletteSize functions. These functions change the ulDirectDeviceDefaultPaletteSize, DirectDeviceDefaultPalette, and DefaultDirectLogicalColorTable variables, and update the entries in the DirectSpecialColorTable.

Accessing the Default Logical Color Tables
There are five possible default logical color tables, which correspond to the five device default palette sets of colors. Each of these color tables contains the same RGB entries. However, they have different indexes into the HW palette. The indexes provide the nearest colors available when each of the device default color sets are loaded into the HW palette.

The default logical color tables are accessed through two pointers, DefaultDirectLogicalColorTable and DefaultMemoryLogicalColorTable, depending on whether an OD_DIRECT or OD_MEMORY DC is in use. There are also two copies of the special color table, which hold system colors and other special colors. These table copies, DirectSpecialColorTable and MemorySpecialColorTable, correspond to OD_DIRECT and OD_MEMORY DCs. Unlike the default logical color tables and the device default palette, these tables are changed by altering their entries rather than by pointing to different versions of the tables.

The special color tables should be updated by the display driver when the system colors change. All of the default logical color tables are updated immediately when the system colors are changed using CLR_BACKGROUND and CLR_NEUTRAL.

Updating the Logical Color Tables
To keep the logical color tables updated in all of the DCs, a field in each DC's instance data points to the device default palette that was current for that DC when the physical indexes into the palette were last calculated. When the EnterDriver function is called, it must check to see if this palette is the current device default palette for that DC. If it is not, EnterDriver updates the logical color table and the current device default palette field.

If the logical color table is one of the five defaults, it can be updated by changing it to point to the current default logical color table. If the logical color table is not one of the defaults, each index has to be recalculated using the current device default palette, which must calculate the nearest default physical index.

Palette Manager Function List
These functions are grouped according to the "conditional include" sections of the header file, Palette Manager functions (INCL_GRE_PALETTE). Each description shows what the handling routine is expected to do, the parameters passed to the routine, and the values that the routine returns.

The Palette Manager functions and their page locations are listed below: For a complete description of each Palette Manager function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * GreDeviceAnimatePalette
 * GreDeviceCreatePalette
 * GreDeviceDeletePalette
 * GreDeviceResizePalette
 * GreDeviceSetPaletteEntries
 * GreQueryHWPaletteInfo
 * GreQueryPaletteRealization
 * GreRealizePalette
 * GreUpdateColors

Software Motion Video Support
The software motion video component of the Multimedia Presentation Manager/2 must update bit maps very quickly. The system must be able to play movie files at 15 frames per second or faster, with each frame having a bit map size of 320 x 240 pels or larger.

GPI calls such as GpiBitBlt cannot meet these objectives. A set of DevEscape calls are provided so that the software motion video component can directly update the Video Random Access Memory (VRAM) of packed-pel display adapters.

Most of the movie frames are delta frames, containing only those pels that have changed from the previously displayed frame. By directly updating VRAM, the software motion video component only needs to selectively update a small number of pels in a typical 320 x 240 pel image. This selective updating allows better performance than a GPI call, which requires redrawing of the entire bit map and makes a heavy call/return overhead when updating small runs of pels.

Software motion video DevEscape functions are provided to:
 * Query the attributes of the aperture (DEVESC_GETAPERTURE)
 * Switch the bank address (DEVESC_SWITCHBANK)
 * Reserve a video adapter (DEVESC_ACQUIREFB)
 * Release a video adapter (DEVESC_DEACQUIREFB)

Architecture Objectives
These DevEscape calls allow the Multimedia Presentation Manager/2 software motion video component to efficiently display rapidly changing pels in real time.

By allowing this efficient, device-independent access technique, there is sufficient processor power available for improved software video decompression, which results in the following benefits:
 * Software motion video that scales video quality according to available system resources
 * Improved video quality

Architecture Definition
These software motion video calls let MMPM/2 determine the exact location and size of memory-mapped VRAM. For video adapters with bank-switched VRAM, efficient, device-independent means are provided to safely gain access to the VRAM resources, manipulate the bank switch mechanism, and release the adapter. This architecture follows the same rationale as WIN-OS/2 seamless windows, using the same mechanisms to ensure reliable sharing of the device.

Description of Functions
Four DevEscape functions in the XGA and SVGA Presentation Manager device drivers are implemented. They provide the ability to allow calling routines to share access to memory-mapped VRAM.

For a complete description of each software motion video function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.

Enhanced Direct Interface Video Extension (EnDIVE)
The Direct Interface Video Extensions (DIVE) architecture has been enhanced in OS/2 Version 3. The enhanced architecture is called EnDIVE and it supports the use of motion video accelerator hardware. Additional DEVESC_ functions are available for querying information about the color formats supported by the hardware, video memory management and image processing.

The additional DEVESC_ functions are provided to:
 * Copy an image from the screen to system memory or to off-screen video memory in a compressed format (DEVESC_EXTGET)
 * Copy an image to the screen (DEVESC_EXTPUT)
 * Acquire information about the motion video accelerator (DEVESC_EXTQUERY)
 * Take advantage of enhanced acquire functions and check on video memory buffer location (DEVESC_HWREQUEST)
 * Acquire information about the frame buffer (DEVESC_QUERYFB)
 * Register and unregister EnDIVE use (DEVESC_REGISTER)
 * Allocate off-screen video memory (DEVESC_VRAMALLOC)
 * Indicate if the hardware can support the current image blitting parameters (DEVESC_SETUPBLITTERNOTIFY)
 * Inform the driver that video is hidden (DEVESC_VIDEOHIDDEN)

For a complete description of each EnDIVE function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.

Graphics System Engine Internal Functions
The handling routines for these functions are in the graphics engine. Because they are not called through the dispatch table, they cannot be hooked by the presentation driver. Descriptions of these internal functions are provided. The functions are grouped according to the conditional include sections of the header file.

Each description defines what the function does, the parameters passed to the engine, and the values that the function returns.

Graphics Engine Functions by Category
Related graphics engine functions can be grouped together into the following categories:


 * Device Context Functions (INCL_GRE_DCS)
 * GreCloseDC
 * GreGetHandle
 * GreGetProcessControl
 * GreOpenDC
 * GreQueryEngineVersion
 * GreResetDC
 * GreRestoreDC
 * GreSaveDC
 * GreSetHandle
 * GreSetProcessControl


 * Device Support Functions (INCL_GRE_DEVSUPPORT)
 * GreCreateBitmap
 * GreDeleteBitmap
 * GreGetAttributes
 * GreGetBitmapDimension
 * GreGetBitmapParameters
 * GreGetDefaultArcParameters
 * GreGetDefaultAttributes
 * GreGetDefaultViewingLimits
 * GreInitializeAttributes
 * GreSelectBitmap
 * GreSetAttributes
 * GreSetBitmapDimension
 * GreSetDefaultArcParameters
 * GreSetDefaultAttributes
 * GreSetDefaultViewingLimits
 * GreSetGlobalAttribute


 * Font Functions (INCL_GRE_FONTS)
 * GreCreateLogicalFont
 * GreLoadFont
 * GreQueryCodePageVector
 * GreQueryFontAttributes
 * GreQueryFontFileDescriptions
 * GreQueryFonts
 * GreQueryLogicalFont
 * GreUnLoadFont


 * Journal Functions (Hard Copy Only) (INCL_GRE_JOURNALING)
 * GreCreateJournalFile
 * GreDeleteJournalFile
 * GreOpenJournalFile
 * GrePlayJournalFile
 * GreStartJournalFile
 * GreStopJournalFile


 * LCID Functions (INCL_GRE_LCID)
 * GreCopyDCLoadData
 * GreQueryBitmapHandle
 * GreSetBitmapID

For a complete description of each Graphics Engine function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * Set ID Functions (INCL_GRE_SETID)
 * GreDeleteSetId
 * GreQueryNumberSetIds
 * GreQuerySetIds

Font Functions
When Presentation Manager is initialized, the engine is responsible for establishing the default image and outline fonts, and the default pattern and marker sets.

The presentation driver can supply device fonts as default fonts. If this is done, the driver can request the graphics engine to manage the device fonts by setting the CAPS_FONT_OUTLINE_MANAGE or CAPS_FONT_IMAGE_MANAGE flag in the array of device capabilities (see GreQueryDeviceCaps). When these flags are set, the engine performs any mapping and transforms that might be necessary. To use a default font belonging to the presentation driver, the font handle is passed to the engine in response to GreQueryDevResource.

Font Matching
When requested by an application, the mapping of a font to a loaded font that is physically available is done by the graphics engine. A physical font can be one that is built into a particular device or a public font loaded from a .FON file when Presentation Manager is initialized. The engine matches fonts by checking the values for szFacename and lMatch (in the font metrics structures) against those passed to it in GreCreateLogicalFont. If no match is found, the engine proceeds as if the match number was passed with a value of 0. When a value of 0 is passed for either szFaceName or lMatch, the engine ignores that parameter and considers it to match anything. If no face name is specified, the engine supplies a default font from the presentation driver (see GreQueryDevResource), or if none is available, maps the requested font to one of its own default fonts.

When a face name is specified and the match number is 0, the engine checks to see if an image font was requested and, if so, searches for a font of the specified dimensions. If this search fails, the engine then attempts to match the font to an outline font with the face name and selection flags requested. When the match number is 0 and the required font is an outline font, the engine searches for an outline font. Should all these searches fail, a default font is used. See GreRealizeFont.

Journal Functions (Hard Copy Only)
Journal functions allow presentation drivers to optimize the processing of data for raster devices such as dot-matrix or laser printers, which print bands of data. The size of a band is determined by the type of device and the amount of memory the driver can use to build its bit map. As an example, a color laser printer might need the full 24 bits per pel. In this case, several bands might be needed to make a page. A simple dot-matrix printer that uses one bit per pel could treat the whole page as a single band. Refer to Banding for a description of how a presentation driver would use journaling functions to perform the technique of banding.

The hardcopy driver creates a journal file when the DC is enabled and starts recording in response to GreEscape (DEVESC_STARTDOC). The graphics engine stores the Grexxx functions in the journal file as they are passed to the DC until told to stop recording by the hardcopy driver.

If the presentation driver passes the bit flag JNL_DRAW_OPTIMIZATION when it calls GreCreateJournalFile, the hardcopy driver processes the calls to produce the first band while the journal file is being accumulated. Otherwise, the COM_DRAW command bit flag is turned OFF and the hardcopy driver is, in effect, told not to draw while the journal file is being accumulated.

When the journal file is complete, if the JNL_DRAW_OPTIMIZATION bit flag was set ON when the function GreCreateJournalFile was called, the hardcopy driver passes the completed band to the spooler or hardcopy device. It then plays the journal file and reprocesses the calls to produce the next band. Otherwise, the hardcopy driver plays the journal file and reprocesses the calls to produce all bands, including the first.

System Functions
This section describes system functions that are available to presentation drivers: For a complete description of each System function, see Mandatory and Simulated Graphics Engine Function Reference. The functions are listed alphabetically in the index table for that chapter.
 * GetDriverInfo
 * SetDriverInfo
 * SSAllocMem
 * SSFreeMem
 * VisRegionNotify
 * WinSetErrorInfo