PDRREF:Presentation Manager Function Categories

Presentation Device Driver Reference for OS/2

Introduction to OS/2 Presentation Drivers Design Considerations for All Drivers Graphics Engine/Presentation Driver Design Changes Design Considerations for Display Drivers Design Considerations for Hardcopy Drivers Display Drivers Distributed Console Access Facility (DCAF) Architecture Graphics Engine Hardcopy Drivers Queue Drivers Port Drivers Presentation Manager Function Categories Exported Driver Function Reference Mandatory and Simulated Graphics Engine Function Reference Device Support Function Reference 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.

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.defSet 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 │ │ │ │routine 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 │3 bits (mask │8 bits (error-term byte, value│ │used) │position, value│0-0xFF) │ │ │0-7) │ │ └───────────────┴───────────────┴──────────────────────────────┘

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.

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

• GreDeviceGetAttributes
• GreDeviceSetAttributes
• GreDeviceSetGlobalAttribute
• GreGetPairKerningTable

Bit-Map Functions

• GreBitblt
• GreDeviceCreateBitmap
• GreDeviceDeleteBitmap
• GreDeviceSelectBitmap
• GreDrawBits
• GreDrawBorder
• GreGetBitmapBits
• GreGetPel
• GreImageData
• GreSetBitmapBits
• GreSetPel

Color Table Functions

• GreCreateLogColorTable
• GreQueryColorData
• GreQueryColorIndex
• GreQueryLogColorTable
• GreQueryNearestColor
• GreQueryRealColors
• GreQueryRGBColor
• GreRealizeColorTable
• GreUnrealizeColorTable

Device Functions 2

• GreDeviceQueryFontAttributes
• GreDeviceQueryFonts
• GreErasePS
• GreNotifyClipChange
• GreNotifyTransformChange
• GreRealizeFont

Device Functions 3

• GreAccumulateBounds
• GreDeviceSetDCOrigin
• GreGetBoundsData
• GreGetCodePage
• GreGetDCOrigin
• GreGetLineOrigin
• GreLockDevice
• GreResetBounds
• GreSetCodePage
• GreSetLineOrigin
• GreUnlockDevice

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

• GrePolyMarker

Query Functions

• GreQueryDeviceBitmaps
• GreQueryDeviceCaps
• GreQueryDevResource
• GreQueryDeviceCaps

Text Functionss

• GreCharString
• GreCharStringPos
• GreQueryCharPositions
• GreQueryTextBox
• GreQueryWidthTable

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.

System Functions

This section describes system functions that are available to presentation drivers:

• GetDriverInfo
• SetDriverInfo
• SSAllocMem
• SSFreeMem
• VisRegionNotify
• WinSetErrorInfo

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.