Difference between revisions of "PDRREF:Presentation Manager Function Categories"

From EDM2
Jump to: navigation, search
(Simulation Functions by Category)
m (Graphics Engine Functions by Category)
Line 1,502: Line 1,502:
  
 
Device Support Functions (INCL_GRE_DEVSUPPORT)
 
Device Support Functions (INCL_GRE_DEVSUPPORT)
*GreCreateBitmap
+
*[[GreCreateBitmap]]
*GreDeleteBitmap
+
*[[GreDeleteBitmap]]
 
*GreGetAttributes
 
*GreGetAttributes
 
*GreGetBitmapDimension
 
*GreGetBitmapDimension

Revision as of 03:18, 16 January 2020

Presentation Device Driver Reference for OS/2
  1. Introduction to OS/2 Presentation Drivers
  2. Design Considerations for All Drivers
  3. Graphics Engine/Presentation Driver Design Changes
  4. Design Considerations for Display Drivers
  5. Design Considerations for Hardcopy Drivers
  6. Display Drivers
  7. Distributed Console Access Facility (DCAF) Architecture
  8. Graphics Engine Hardcopy Drivers
  9. Queue Drivers
  10. Port Drivers
  11. Presentation Manager Function Categories
  12. Exported Driver Function Reference
  13. Mandatory and Simulated Graphics Engine Function Reference
  14. Device Support Function Reference
  15. DBIDI Command Structures and Command Flow

Appendixes

A - OS/2 Version Compatibility Considerations
B - Syntax Conventions
C - Format of the Journal File
D - Bit-Map Simulation for 16-Bit Hardcopy Drivers
E - Data Types
F - Notices

Miscellaneous

G - Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

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.

Contents

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:

  • 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

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:

  • 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)

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.

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
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.

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.

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:

Parameter Description
cAttr Size of the logical attribute bundle.
cDefs Size of the LINEDEFS structure.
lbnd LINEBUNDLE structure. The logical line bundle as seen by the application. See LINEBUNDLE Mask: following this table.
ldef LINEDEFS structure: defType Line definition. This is ignored by the presentation driver.

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:

Flag Field
LBB_COLOR lColor
LBB_BACK_COLOR lBackColor
LBB_MIX_MODE usMixMode
LBB_BACK_MIX_MODE usBackMixMode
LBB_WIDTH fxWidth
LBB_GEOM_WIDTH lGeomWidth
LBB_TYPE usType
LBB_END usEnd
LBB_JOIN usJoin
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:

Parameter Description
cAttr Size of the logical area bundle.
cDefs Size of the AREADEFS structure. This is 0 when no device area bundle exists.
abnd AREABUNDLE structure. See text following AREABUNDLE Mask:.
adef AREADEFS structure. See text following AREABUNDLE Mask:.

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:

Flag Field
ABB_COLOR lColor
ABB_BACK_COLOR lBackColor
ABB_MIX_MODE usMixMode
ABB_BACK_MIX_MODE usBackMixMode
ABB_SET usSet
ABB_SYMBOL usSymbol
ABB_REF_POINT ptlRefPoint
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:

Parameter Description
cAttr Size of the attribute bundle.
cDefs Size of the CHARDEFS structure.
cbnd CHARBUNDLE structure. See text following CHARBUNDLE Mask:.
cdef CHARDEFS 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:

Flag Field
CBB_COLOR lColor
CBB_BACK_COLOR lBackColor
CBB_MIX_MODE usMixMode
CBB_BACK_MIX_MODE usBackMixMode
CBB_SET usSet
CBB_MODE usPrecision
CBB_BOX sizfxCell
CBB_ANGLE ptlAngle
CBB_SHEAR ptlShear
CBB_DIRECTION usDirection
CBB_TEXT_ALIGN usTextAlign
CBB_EXTRA fxExtra
CBB_BREAK_EXTRA fxBreakExtra
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:

Parameter Description
cAttr Size of the attributes structure.
cDefs Set to 0. There is no IMAGEDEFS structure.
ibnd IMAGEBUNDLE structure. See text following IMAGEBUNDLE Mask:

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:

Flag Field
IBB_COLOR lColor
IBB_BACK_COLOR lBackColor
IBB_MIX_MODE usMixMode
IBB_BACK_MIX_MODE usBackMixMode
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:

Parameter Description
cAttr Size of MARKERBUNDLE structure.
cDefs Size of MARKERDEFS structure.
mbnd MARKERBUNDLE structure. See text following MARKERBUNDLE Mask:.
mdef MARKERDEFS structure. See text following MARKERBUNDLE Mask:.

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:

Flag Field
MBB_COLOR lColor
MBB_BACK_COLOR lBackColor
MBB_MIX_MODE usMixMode
MBB_BACK_MIX_MODE usBackMixMode
MBB_SET usSet
MBB_SYMBOL usSymbol
MBB_BOX sizfxCell
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_FALSE (-5). All color planes or bits, or both, are FALSE.
CLR_TRUE (-4). All color planes or bits, or both, are TRUE.
CLR_DEFAULT (-3). This is the API default. It is a reserved value and is not passed to the presentation driver.
CLR_WHITE (-2). This index is never loaded explicitly. It always produces white 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_BACKGROUND.

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:

Parameter Data Type Description
hdc HDC Device context handle.
lEscape LONG Escape code.
cInCount LONG Number of bytes pointed to by pInData.
pInData PBYTE Pointer to input data structure.
pcOutCount PLONG Pointer to the number of bytes in output data structure. If the escape code is one that returns data in the output data structure, the handling outine changes the value addressed by pcOutCount to show the number of bytes returned.
pOutData PLONG Pointer to output data structure.
pInstance PVOID Pointer to instance data.
lFunction ULONG High-order WORD=flags; Low-order WORD=NGreEscape.

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.

DEVESC_ABORTDOC (Hardcopy drivers only)
DEVESC_ACQUIREFB (software motion video)
DEVESC_BREAK_EXTRA (Hardcopy drivers only)
DEVESC_CHAR_EXTRA (Hardcopy drivers only)
DEVESC_DBE_FONTMANAGEMENT (DBCS support)
DEVESC_DEACQUIREFB (software motion video)
DEVESC_DRAFTMODE (Hardcopy drivers only)
DEVESC_ENDDOC (Hardcopy drivers only)
DEVESC_EXTGET (EnDIVE support)
DEVESC_EXTPUT (EnDIVE support)
DEVESC_EXTQUERY (EnDIVE support)
DEVESC_FLUSHOUTPUT (Hardcopy drivers only)
DEVESC_GETAPERTURE (EnDIVE support)
DEVESC_GETCP (Hardcopy drivers only)
DEVESC_GETJOBID (Hardcopy drivers only)
DEVESC_GETSCALINGFACTOR (Hardcopy drivers only)
DEVESC_HWREQUEST (EnDIVE support)
DEVESC_NEWFRAME (Hardcopy drivers only)
DEVESC_NEXTBAND (Hardcopy drivers only)
DEVESC_QUERYESCSUPPORT (All drivers)
DEVESC_QUERYFB (EnDIVE support)
DEVESC_QUERYVIOCELLSIZES (Display drivers only)
DEVESC_RAWDATA (Hardcopy drivers only)
DEVESC_REGISTER (EnDIVE support)
DEVESC_SETMODE (Hardcopy drivers only)
DEVESC_SETUPBLITTERNOTIFY (EnDIVE support)
DEVESC_STARTDOC (Hardcopy drivers only)
DEVESC_STD_JOURNAL (Hardcopy drivers only)
DEVESC_SWITCHBANK (software motion video)
DEVESC_VIDEOHIDDEN (EnDIVE support)
DEVESC_VRAMALLOC (EnDIVE support)

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:

32768-40959 Escape is not metafiled or recorded by the spooler. The escape is passed to the presentation driver in all cases.
40960-49151 Escape is metafiled but is not recorded by the spooler. For an OD_QUEUED device with PM_Q_STD data and for all device types other than OD_METAFILE, the escape is passed to the presentation driver.
49152-57343 Escape is metafiled and recorded by the spooler. For an OD_METAFILE device or for OD_QUEUED with PM_Q_STD data, the escape is not passed to the presentation driver.
57344-65535 Escape is recorded by the spooler. The escape is passed to the presentation driver except when the DC is an OD_QUEUED device with PM_Q_STD data.

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:

8-Bit Style Masks
usType Value StyleMask Bits Comment
LINETYPE_DEFAULT 0 0xFF 11111111 Solid line.
LINETYPE_DOT 1 0xAA 10101010
LINETYPE_SHORTDASH 2 0xCC 11001100
LINETYPE_DASHDOT 3 0xE4 11100100
LINETYPE_DOUBLEDOT 4 0xA0 10100000
LINETYPE_LONGDASH 5 0xE7 11100111
LINETYPE_DASHDOUBLEDOT 6 0xEA 11101010
LINETYPE_SOLID 7 0xFF 11111111
LINETYPE_INVISIBLE 8 0x00 00000000
LINETYPE_ALTERNATE 9 0xAA 10101010

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:

5 bits (not used) 3 bits (mask position, value 0-7) 8 bits (error-term byte, value 0-0xFF)
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:

  • 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)

They are stored in the following manner:

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:
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.

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:

  • If the line is Y-major as viewed on the device:
{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
  • If the line is X-major as viewed on the device:
{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

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.

PDRREF pel.png 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)

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;

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

Bit-Map Functions

Color Table Functions

Device Functions 2

Device Functions 3

GreEscape Functions

  • 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

  • GreDisjointLines
  • GreDrawLinesInPath
  • GreGetCurrentPosition
  • GrePolyLine
  • GrePolyScanline
  • GrePolyShortLine
  • GreSetCurrentPosition

Marker Functions

Query Functions

Text Functions

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.

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

  • GreCharRect
  • GreCharStr
  • GreDeviceSetAVIOFont
  • GreScrollRect
  • GreUpdateCursor

Bitmap Functions

Device Functions 2

  • GreDeviceInvalidateVisRegion
  • GreGetStyleRatio
  • GreSetStyleRatio

Device Functions 3

  • GreDeath
  • GreResurrection

Miscellaneous Functions

  • GreGetPickWindow
  • GreSetColorCursor
  • GreSetPickWindow

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.

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:

  • 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

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.

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:

  • 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)

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

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.

PDRREF transform.png

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)
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)

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

Area and Path Functions

Clip Functions

  • GreCopyClipRegion
  • GreExcludeClipRectangle
  • GreGetClipBox
  • GreGetClipRects
  • GreIntersectClipRectangle
  • GreOffsetClipRegion
  • GrePtVisible
  • GreQueryClipRegion
  • GreRectVisible
  • GreRegionSelectBitmap
  • GreRestoreRegion
  • GreSaveRegion
  • GreSelectClipRegion
  • GreSelectPathRegion
  • GreSetupDC
  • GreSetXformRect

Line Functions

Palette Manager Functions

  • GreDeviceAnimatePalette
  • GreDeviceCreatePalette
  • GreDeviceDeletePalette
  • GreDeviceResizePalette
  • GreDeviceSetPaletteEntries
  • GreQueryHWPaletteInfo
  • GreQueryPaletteRealization
  • GreRealizePalette
  • GreUpdateColors

Region Functions

  • GreCombineRectRegion
  • GreCombineRegion
  • GreCombineShortLineRegion
  • GreCreateRectRegion
  • GreDestroyRegion
  • GreEqualRegion
  • GreGetRegionBox
  • GreGetRegionRects
  • GreOffsetRegion
  • GrePaintRegion
  • GrePtInRegion
  • GreRectInRegion
  • GreSetRectRegion

Transform Functions

  • GreConvert
  • GreGetGlobalViewingXform
  • GreGetGraphicsField
  • GreGetModelXform
  • GreGetPageUnits
  • GreGetPageViewport
  • GreGetViewingLimits
  • GreGetWindowViewportXform
  • GreMultiplyXforms
  • GreRestoreXform
  • GreRestoreXformData
  • GreSaveXform
  • GreSaveXformData
  • GreSetGlobalViewingXform
  • GreSetGraphicsField
  • GreSetModelXform
  • GreSetPageUnits
  • GreSetPageViewport
  • GreSetViewingLimits
  • GreSetWindowViewportXform

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.

Palette Manager Functions

The hardware (HW) palette, or device physical palette, is divided into two parts:

  • Device default colors, which are the entries used by nonpalette manager DCs
  • Palette Manager palette colors

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.

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:

  • GreDeviceAnimatePalette
  • GreDeviceCreatePalette
  • GreDeviceDeletePalette
  • GreDeviceResizePalette
  • GreDeviceSetPaletteEntries
  • GreQueryHWPaletteInfo
  • GreQueryPaletteRealization
  • GreRealizePalette
  • GreUpdateColors

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.

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)

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)

Set ID Functions (INCL_GRE_SETID)

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.

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.