═══ 1. Data Types ═══

The following data types are used in Graphics Presentation Interface. They are 
listed in alphabetic order. 


═══ 1.1. ARCPARAMS ═══

Arc-parameters structure. 

typedef struct _ARCPARAMS {
  LONG     lP;  /*  P coefficient. */
  LONG     lQ;  /*  Q coefficient. */
  LONG     lR;  /*  R coefficient. */
  LONG     lS;  /*  S coefficient. */
} ARCPARAMS;

typedef ARCPARAMS *PARCPARAMS;


═══ <hidden> ARCPARAMS Field - lP ═══

 lP (LONG) 
    P coefficient. 


═══ <hidden> ARCPARAMS Field - lQ ═══

 lQ (LONG) 
    Q coefficient. 


═══ <hidden> ARCPARAMS Field - lR ═══

 lR (LONG) 
    R coefficient. 


═══ <hidden> ARCPARAMS Field - lS ═══

 lS (LONG) 
    S coefficient. 


═══ 1.2. AREABUNDLE ═══

Area-attributes bundle structure. 

typedef struct _AREABUNDLE {
  LONG       lColor;         /*  Area foreground color. */
  LONG       lBackColor;     /*  Area background color. */
  USHORT     usMixMode;      /*  Area foreground-mix mode. */
  USHORT     usBackMixMode;  /*  Area background-mix mode. */
  USHORT     usSet;          /*  Pattern set. */
  USHORT     usSymbol;       /*  Pattern symbol. */
  POINTL     ptlRefPoint;    /*  Pattern reference point. */
} AREABUNDLE;

typedef AREABUNDLE *PAREABUNDLE;


═══ <hidden> AREABUNDLE Field - lColor ═══

 lColor (LONG) 
    Area foreground color. 


═══ <hidden> AREABUNDLE Field - lBackColor ═══

 lBackColor (LONG) 
    Area background color. 


═══ <hidden> AREABUNDLE Field - usMixMode ═══

 usMixMode (USHORT) 
    Area foreground-mix mode. 


═══ <hidden> AREABUNDLE Field - usBackMixMode ═══

 usBackMixMode (USHORT) 
    Area background-mix mode. 


═══ <hidden> AREABUNDLE Field - usSet ═══

 usSet (USHORT) 
    Pattern set. 


═══ <hidden> AREABUNDLE Field - usSymbol ═══

 usSymbol (USHORT) 
    Pattern symbol. 


═══ <hidden> AREABUNDLE Field - ptlRefPoint ═══

 ptlRefPoint (POINTL) 
    Pattern reference point. 


═══ 1.3. BITMAPINFO ═══

Bit-map information structure. 

Each bit plane logically contains (cx * cy * cBitCount) bits, although the 
actual length can be greater because of padding. 

See also BITMAPINFO2, which is preferred. 

typedef struct _BITMAPINFO {
  ULONG      cbFix;         /*  Length of fixed portion of structure. */
  USHORT     cx;            /*  Bit-map width in pels. */
  USHORT     cy;            /*  Bit-map height in pels. */
  USHORT     cPlanes;       /*  Number of bit planes. */
  USHORT     cBitCount;     /*  Number of bits per pel within a plane. */
  RGB        argbColor[1];  /*  Array of RGB values. */
} BITMAPINFO;

typedef BITMAPINFO *PBITMAPINFO;


═══ <hidden> BITMAPINFO Field - cbFix ═══

 cbFix (ULONG) 
    Length of fixed portion of structure. 

    This length can be determined using sizeof(BITMAPINFOHEADER). 


═══ <hidden> BITMAPINFO Field - cx ═══

 cx (USHORT) 
    Bit-map width in pels. 


═══ <hidden> BITMAPINFO Field - cy ═══

 cy (USHORT) 
    Bit-map height in pels. 


═══ <hidden> BITMAPINFO Field - cPlanes ═══

 cPlanes (USHORT) 
    Number of bit planes. 


═══ <hidden> BITMAPINFO Field - cBitCount ═══

 cBitCount (USHORT) 
    Number of bits per pel within a plane. 


═══ <hidden> BITMAPINFO Field - argbColor[1] ═══

 argbColor[1] (RGB) 
    Array of RGB values. 

    This is a packed array of 24-bit RGB values. If there are N bits per pel 
    (N =cPlanes * cBitCount), the array contains 2**N RGB values. However, if 
    N = 24, the bit map does not need the color color array because the 
    standard-format bit map, with 24 bits per pel, is assumed to contain RGB 
    values. 


═══ 1.4. BITMAPINFO2 ═══

Bit-map information structure. 

Each bit plane logically contains (cx * cy * cBitCount) bits, although the 
actual length can be greater because of padding. 

Note:  Many functions can accept either this structure or the BITMAPINFO 
structure. Where possible, BITMAPINFO2 should be used. 

The cbFix field is used to find the color table, if any, that goes with the 
information in this structure. A color table is an array of color (RGB2) 
values. If there are N bits per pel (N = cPlanes * cBitCount), the array 
contains 2**N color values. However, if N = 24, the color table is not required 
(because the standard-format bit map, with 24 bits per pel, is assumed to 
contain RGB values), unless either cclrUsed or cclrImportant is non-zero. 

typedef struct _BITMAPINFO2 {
  ULONG      cbFix;            /*  Length of fixed portion of structure. */
  ULONG      cx;               /*  Bit-map width in pels. */
  ULONG      cy;               /*  Bit-map height in pels. */
  USHORT     cPlanes;          /*  Number of bit planes. */
  USHORT     cBitCount;        /*  Number of bits per pel within a plane. */
  ULONG      ulCompression;    /*  Compression scheme used to store the bit map. */
  ULONG      cbImage;          /*  Length of bit-map storage data, in bytes. */
  ULONG      cxResolution;     /*  Horizontal component of the resolution of target device. */
  ULONG      cyResolution;     /*  Vertical component of the resolution of the target device. */
  ULONG      cclrUsed;         /*  Number of color indexes used. */
  ULONG      cclrImportant;    /*  Minimum number of color indexes for satisfactory appearance of the bit map. */
  USHORT     usUnits;          /*  Units of measure. */
  USHORT     usReserved;       /*  Reserved. */
  USHORT     usRecording;      /*  Recording algorithm. */
  USHORT     usRendering;      /*  Halftoning algorithm. */
  ULONG      cSize1;           /*  Size value 1. */
  ULONG      cSize2;           /*  Size value 2. */
  ULONG      ulColorEncoding;  /*  Color encoding. */
  ULONG      ulIdentifier;     /*  Reserved for application use. */
  RGB2       argbColor[1];     /*  Array of RGB values. */
} BITMAPINFO2;

typedef BITMAPINFO2 *PBITMAPINFO2;


═══ <hidden> BITMAPINFO2 Field - cbFix ═══

 cbFix (ULONG) 
    Length of fixed portion of structure. 

    The structure can be truncated after cBitCount or any subsequent field. 

    The length does not include the length of the color table. Where the color 
    table is present, it is at an offset of cbFix from the start of the 
    BITMAPINFO2 structure. 

    This length can range from 16 (BITMAPINFOHEADER through field cBitCount) up 
    to sizeof(BITMAPINFOHEADER2) bytes. 


═══ <hidden> BITMAPINFO2 Field - cx ═══

 cx (ULONG) 
    Bit-map width in pels. 


═══ <hidden> BITMAPINFO2 Field - cy ═══

 cy (ULONG) 
    Bit-map height in pels. 


═══ <hidden> BITMAPINFO2 Field - cPlanes ═══

 cPlanes (USHORT) 
    Number of bit planes. 


═══ <hidden> BITMAPINFO2 Field - cBitCount ═══

 cBitCount (USHORT) 
    Number of bits per pel within a plane. 


═══ <hidden> BITMAPINFO2 Field - ulCompression ═══

 ulCompression (ULONG) 
    Compression scheme used to store the bit map. 

    BCA_UNCOMP 
              Bit map is uncompressed. 

    BCA_HUFFMAN1D 
              The bit map is compressed by a modified Huffman encoding. This is 
              valid for a bi-level (one bit per pel) bit map. 

    BCA_RLE4 
              The bit map is a 4-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    BCA_RLE8 
              The bit map is an 8-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    BCA_RLE24 
              The bit map is a 24-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    Format of Compressed Data 

    Encoding a run length: 

    Run-length encoded bit maps are encoded in the buffer in a controlled 
    format. In all cases, if the first byte is non-zero, it is the length of a 
    run of pels of a particular color or, in the case of a BCA_RLE4 bit map, a 
    run of a length of pels of alternating colors. 


        1st-byte       pel repetition count >= 1
        2nd-4th bytes  (BCA_RLE24 only) RGB value of pel.
        2nd-byte       (BCA_RLE8) color index of pel to be repeated
                       (BCA_RLE4) the second byte contains 2 4-bit
                       color indexes.  The repetition count is
                       completed by alternately choosing the high-order
                       nibble followed by the low-order nibble for the
                       succeeding pels until the count is exhausted.

    Unencoded run: 

    An unencoded run is a string of pels to be placed in consecutive positions 
    in the destination bit map. 


        1st-byte     0
        2nd-byte     COUNT = a multiple of 3 for BCA_RLE24 bit maps, or
                     COUNT >= 3 (for BCA_RLE4 and BCA_RLE8 bit maps).

    followed by the bytes as follows: 

    BCA_RLE24 
              A string of bytes specifying the RGB color values of succeeding 
              pels.  If COUNT is odd, it must be padded by a zero byte for an 
              even length overall. 

    BCA_RLE8 
              A string of bytes specifying color indexes for succeeding pels. 
              If COUNT is odd, it must be padded by a zero byte for an even 
              length overall. 

    BCA_RLE4 
              A string of bytes, each byte providing two color indexes, with 
              the high-order nibble specifying the index of the pel preceding 
              the low-order nibble. The COUNT specifies the number of indexes. 
              The overall length of the string must be an even number of bytes, 
              and thus may be padded with a zero byte, and the low order nibble 
              of the last significant byte may also be zero and not used. 

    Delta record: 

    A delta record indicates a shift in position in the destination bit map 
    before the next record is decoded. 


        1st-byte        0
        2nd-byte        2
        3rd-byte        Delta-x (unsigned)
        4th-byte        Delta-y (unsigned)

    This is a relative jump record.  It implies that the next record is to be 
    decoded into a position in the destination bit map at an offset from the 
    current position, determined by changing the horizontal and vertical 
    positions by Delta-x and Delta-y, respectively. 

    End-of-line record: 

    The end-of-line record signifies that the data for the current scan line is 
    complete and that decoding of the next record should begin at the start of 
    the next scan line. 


        1st-byte        0
        2nd-byte        0

    End-of-RLE record: 

    The end-of-RLE record signifies the end of the data in the RLE compressed 
    bit map. 


        1st-byte        0
        2nd-byte        1


═══ <hidden> BITMAPINFO2 Field - cbImage ═══

 cbImage (ULONG) 
    Length of bit-map storage data, in bytes. 

    If the bit map is uncompressed, zero (default) can be specified for this. 


═══ <hidden> BITMAPINFO2 Field - cxResolution ═══

 cxResolution (ULONG) 
    Horizontal component of the resolution of target device. 

    The resolution of the device the bit map is intended for, in the units 
    specified by usUnits. This information enables an application to select 
    from a resource group the bit map that best matches the characteristics of 
    the current output device. 


═══ <hidden> BITMAPINFO2 Field - cyResolution ═══

 cyResolution (ULONG) 
    Vertical component of the resolution of the target device. 

    See the description of cxResolution. 


═══ <hidden> BITMAPINFO2 Field - cclrUsed ═══

 cclrUsed (ULONG) 
    Number of color indexes used. 

    The number of color indexes from the color table that are used by the bit 
    map. If it is zero (the default), all the indexes are used. If it is 
    non-zero, only the first cclrUsed entries in the table are accessed by the 
    system, and further entries can be omitted. 

    For the standard formats with a cBitCount of 1, 4, or 8 (and cPlanes equal 
    to 1), any indexes beyond cclrUsed are not valid. For example, a bit map 
    with 64 colors can use the 8-bitcount format without having to supply the 
    other 192 entries in the color table. For the 24-bitcount standard format, 
    cclrUsed is the number of colors used by the bit map. 


═══ <hidden> BITMAPINFO2 Field - cclrImportant ═══

 cclrImportant (ULONG) 
    Minimum number of color indexes for satisfactory appearance of the bit map. 

    More colors may be used in the bit map, but it is not necessary to assign 
    them to the device palette. These additional colors may be mapped to the 
    nearest colors available. 

    Zero (the default) means that all entries are important. 

    For a 24-bitcount standard format bit map, the cclrImportant colors are 
    also listed in the color table following the BITMAPINFO2 structure. 


═══ <hidden> BITMAPINFO2 Field - usUnits ═══

 usUnits (USHORT) 
    Units of measure. 

    Units of measure of the horizontal and vertical components of resolution, 
    cxResolution and cyResolution. 

    BRU_METRIC          Pels per meter. This is the default value. 


═══ <hidden> BITMAPINFO2 Field - usReserved ═══

 usReserved (USHORT) 
    Reserved. 

    This is a reserved field. 


═══ <hidden> BITMAPINFO2 Field - usRecording ═══

 usRecording (USHORT) 
    Recording algorithm. 

    The format in which the bit map data is recorded. 

    BRA_BOTTOMUP             Scan lines are recorded bottom to top. This is the 
                             default value. 


═══ <hidden> BITMAPINFO2 Field - usRendering ═══

 usRendering (USHORT) 
    Halftoning algorithm. 

    The algorithm used to record bit map data that has been digitally 
    halftoned. 

    BRH_NOTHALFTONED              Bit-map data is not halftoned. This is the 
                                  default value. 

    BRH_ERRORDIFFUSION            Error Diffusion or Damped Error Diffusion 
                                  algorithm. 

    BRH_PANDA                     Processing Algorithm for Non-coded Document 
                                  Acquisition. 

    BRH_SUPERCIRCLE               Super Circle algorithm. 


═══ <hidden> BITMAPINFO2 Field - cSize1 ═══

 cSize1 (ULONG) 
    Size value 1. 

    If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error 
    damping as a percentage in the range 0 through 100. A value of 100% 
    indicates no damping, and a value of 0% indicates that any errors are not 
    diffused. 

    If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the x dimension of 
    the pattern used, in pels. 


═══ <hidden> BITMAPINFO2 Field - cSize2 ═══

 cSize2 (ULONG) 
    Size value 2. 

    If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is 
    ignored. 

    If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the y dimension of 
    the pattern used, in pels. 


═══ <hidden> BITMAPINFO2 Field - ulColorEncoding ═══

 ulColorEncoding (ULONG) 
    Color encoding. 

    BCE_RGB             Each element in the color array is an RGB2 datatype. 
                        This is the default value. 


═══ <hidden> BITMAPINFO2 Field - ulIdentifier ═══

 ulIdentifier (ULONG) 
    Reserved for application use. 


═══ <hidden> BITMAPINFO2 Field - argbColor[1] ═══

 argbColor[1] (RGB2) 
    Array of RGB values. 

    This is a packed array of 24-bit RGB values. If there are N bits per pel 
    (N =cPlanes * cBitCount), the array contains 2**N RGB values. However, if 
    N = 24, the bit map does not need the color array because the 
    standard-format bit map, with 24 bits per pel, is assumed to contain RGB 
    values. 


═══ 1.5. BITMAPINFOHEADER ═══

Bit-map information header structure. 

Each bit plane logically contains (cx * cy * cBitCount) bits, although the 
actual length can be greater because of padding. 

See also BITMAPINFOHEADER2, which is preferred. 

typedef struct _BITMAPINFOHEADER {
  ULONG      cbFix;      /*  Length of structure. */
  USHORT     cx;         /*  Bit-map width in pels. */
  USHORT     cy;         /*  Bit-map height in pels. */
  USHORT     cPlanes;    /*  Number of bit planes. */
  USHORT     cBitCount;  /*  Number of bits per pel within a plane. */
} BITMAPINFOHEADER;

typedef BITMAPINFOHEADER *PBITMAPINFOHEADER;


═══ <hidden> BITMAPINFOHEADER Field - cbFix ═══

 cbFix (ULONG) 
    Length of structure. 


═══ <hidden> BITMAPINFOHEADER Field - cx ═══

 cx (USHORT) 
    Bit-map width in pels. 


═══ <hidden> BITMAPINFOHEADER Field - cy ═══

 cy (USHORT) 
    Bit-map height in pels. 


═══ <hidden> BITMAPINFOHEADER Field - cPlanes ═══

 cPlanes (USHORT) 
    Number of bit planes. 


═══ <hidden> BITMAPINFOHEADER Field - cBitCount ═══

 cBitCount (USHORT) 
    Number of bits per pel within a plane. 


═══ 1.6. BITMAPINFOHEADER2 ═══

Bit-map information header structure. 

Each bit plane logically contains (cx * cy * cBitCount) bits, although the 
actual length can be greater because of padding. 

Note:  Many functions can accept either this structure or the BITMAPINFOHEADER 
structure. Where possible, use BITMAPINFOHEADER2. 

typedef struct _BITMAPINFOHEADER2 {
  ULONG      cbFix;            /*  Length of structure. */
  ULONG      cx;               /*  Bit-map width in pels. */
  ULONG      cy;               /*  Bit-map height in pels. */
  USHORT     cPlanes;          /*  Number of bit planes. */
  USHORT     cBitCount;        /*  Number of bits per pel within a plane. */
  ULONG      ulCompression;    /*  Compression scheme used to store the bit map. */
  ULONG      cbImage;          /*  Length of bit-map storage data, in bytes. */
  ULONG      cxResolution;     /*  Horizontal component of the resolution of target device. */
  ULONG      cyResolution;     /*  Vertical component of the resolution of target device. */
  ULONG      cclrUsed;         /*  Number of color indexes used. */
  ULONG      cclrImportant;    /*  Minimum number of color indexes for satisfactory appearance of the bit map. */
  USHORT     usUnits;          /*  Units of measure. */
  USHORT     usReserved;       /*  Reserved. */
  USHORT     usRecording;      /*  Recording algorithm. */
  USHORT     usRendering;      /*  Halftoning algorithm. */
  ULONG      cSize1;           /*  Size value 1. */
  ULONG      cSize2;           /*  Size value 2. */
   ULONG      ulColorEncoding;  /*  Color encoding.

  BCE_RGB   Each element in the color array is an RGB2 datatype. This is the default value.
   */
    ULONG      ulIdentifier;     /*  Reserved for application use. */
  } BITMAPINFOHEADER2;

  typedef BITMAPINFOHEADER2 *PBITMAPINFOHEADER2;


═══ <hidden> BITMAPINFOHEADER2 Field - cbFix ═══

 cbFix (ULONG) 
    Length of structure. 

    The structure can be truncated after cBitCount or any subsequent field. 


═══ <hidden> BITMAPINFOHEADER2 Field - cx ═══

 cx (ULONG) 
    Bit-map width in pels. 


═══ <hidden> BITMAPINFOHEADER2 Field - cy ═══

 cy (ULONG) 
    Bit-map height in pels. 


═══ <hidden> BITMAPINFOHEADER2 Field - cPlanes ═══

 cPlanes (USHORT) 
    Number of bit planes. 


═══ <hidden> BITMAPINFOHEADER2 Field - cBitCount ═══

 cBitCount (USHORT) 
    Number of bits per pel within a plane. 


═══ <hidden> BITMAPINFOHEADER2 Field - ulCompression ═══

 ulCompression (ULONG) 
    Compression scheme used to store the bit map. 

    BCA_UNCOMP 
              Bit map is uncompressed. 

    BCA_HUFFMAN1D 
              The bit map is compressed by a modified Huffman encoding. This is 
              valid for a bi-level (one bit per pel) bit map. 

    BCA_RLE4 
              The bit map is a 4-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    BCA_RLE8 
              The bit map is an 8-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    BCA_RLE24 
              The bit map is a 24-bit per pel run-length encoded bit map. See 
              the following section, "Format of Compressed Data," for a 
              description of the format of the compressed data. 

    Format of Compressed Data 

    Encoding a run length: 

    Run length encoded bit maps are encoded in the buffer in a controlled 
    format. In all cases, if the first byte is non-zero, it is the length of a 
    run of pels of a particular color or, in the case of a BCA_RLE4 bit map, a 
    run of a length of pels of alternating colors. 


        1st-byte       pel repetition count >= 1
        2nd-4th bytes  (BCA_RLE24 only) RGB value of pel.
        2nd-byte       (BCA_RLE8) color index of pel to be repeated
                       (BCA_RLE4) the second byte contains 2 4-bit
                       color indexes.  The repetition count is
                       completed by alternately choosing the high-order
                       nibble followed by the low-order nibble for the
                       succeeding pels until the count is exhausted.

    Unencoded run: 

    An unencoded run is a string of pels to be placed in consecutive positions 
    in the destination bit map. 


        1st-byte     0
        2nd-byte     COUNT = a multiple of 3 for BCA_RLE24 bit maps, or
                     COUNT >= 3 (for BCA_RLE4 and BCA_RLE8 bit maps).

    followed by the bytes as follows: 

    BCA_RLE24 
              A string of bytes specifying the RGB color values of succeeding 
              pels.  If COUNT is odd, it must be padded by a zero byte for an 
              even length overall. 

    BCA_RLE8 
              A string of bytes specifying color indexes for succeeding pels. 
              If COUNT is odd, it must be padded by a zero byte for an even 
              length overall. 

    BCA_RLE4 
              A string of bytes, each byte providing two color indexes, with 
              the high-order nibble specifying the index of the pel preceding 
              the low-order nibble. The COUNT specifies the number of indexes. 
              The overall length of the string must be an even number of bytes, 
              and thus may be padded with a zero byte, and the low order nibble 
              of the last significant byte may also be zero and not used. 

    Delta record: 

    A delta record indicates a shift in position in the destination bit map 
    before the next record is decoded. 


        1st-byte        0
        2nd-byte        2
        3rd-byte        Delta-x (unsigned)
        4th-byte        Delta-y (unsigned)

    This is a relative jump record.  It implies that the next record is to be 
    decoded into a position in the destination bit map at an offset from the 
    current position, determined by changing the horizontal and vertical 
    positions by Delta-x and Delta-y, respectively. 

    End-of-line record: 

    The end-of-line record signifies that the data for the current scan line is 
    complete and that decoding of the next record should begin at the start of 
    the next scan line. 


        1st-byte        0
        2nd-byte        0

    End-of-RLE record: 

    The end-of-RLE record signifies the end of the data in the RLE compressed 
    bit map. 


        1st-byte        0
        2nd-byte        1


═══ <hidden> BITMAPINFOHEADER2 Field - cbImage ═══

 cbImage (ULONG) 
    Length of bit-map storage data, in bytes. 

    If the bit map is uncompressed, zero (the default) can be specified for 
    this. 


═══ <hidden> BITMAPINFOHEADER2 Field - cxResolution ═══

 cxResolution (ULONG) 
    Horizontal component of the resolution of target device. 

    The resolution of the device the bit map is intended for, in the units 
    specified by usUnits. This information enables applications to select from 
    a resource group the bit map that best matches the characteristics of the 
    current output device. 


═══ <hidden> BITMAPINFOHEADER2 Field - cyResolution ═══

 cyResolution (ULONG) 
    Vertical component of the resolution of target device. 

    See the description of cxResolution. 


═══ <hidden> BITMAPINFOHEADER2 Field - cclrUsed ═══

 cclrUsed (ULONG) 
    Number of color indexes used. 

    The number of color indexes from the color table that are used by the bit 
    map. If this is zero (the default), all the indexes are used. If it is 
    non-zero, only the first cclrUsed entries in the table are accessed by the 
    system, and further entries can be omitted. 

    For the standard formats with a cBitCount of 1, 4, or 8 (and cPlanes equal 
    to 1), any indexes beyond cclrUsed are invalid. For example, a bit map with 
    64 colors can use the 8-bitcount format without having to supply the other 
    192 entries in the color table. For the 24-bitcount standard format, 
    cclrUsed is the number of colors used by the bit map. 


═══ <hidden> BITMAPINFOHEADER2 Field - cclrImportant ═══

 cclrImportant (ULONG) 
    Minimum number of color indexes for satisfactory appearance of the bit map. 

    More colors may be used in the bit map, but it is not necessary to assign 
    them to the device palette. These additional colors may be mapped to the 
    nearest colors available. 

    Zero (the default) means that all entries are important. 

    For a 24-bitcount standard format bit map, the cclrImportant colors are 
    also listed in the color table relating to this bit map. 


═══ <hidden> BITMAPINFOHEADER2 Field - usUnits ═══

 usUnits (USHORT) 
    Units of measure. 

    Units of measure of the horizontal and vertical resolution, cxResolution 
    and cyResolution. 

    BRU_METRIC     Pels per meter. This is the default value. 


═══ <hidden> BITMAPINFOHEADER2 Field - usReserved ═══

 usReserved (USHORT) 
    Reserved. 

    This is a reserved field. If present, it must be zero. 


═══ <hidden> BITMAPINFOHEADER2 Field - usRecording ═══

 usRecording (USHORT) 
    Recording algorithm. 

    The format in which the bit-map data is recorded. 

    BRA_BOTTOMUP        Scan lines are recorded bottom to top. This is the 
                        default value. 


═══ <hidden> BITMAPINFOHEADER2 Field - usRendering ═══

 usRendering (USHORT) 
    Halftoning algorithm. 

    The algorithm used to record bit-map data that has been digitally 
    halftoned. 

    BRH_NOTHALFTONED Bit-map data is not halftoned. This is the default value. 

    BRH_ERRORDIFFUSION Error Diffusion or Damped Error Diffusion algorithm. 

    BRH_PANDA      Processing Algorithm for Non-coded Document Acquisition. 

    BRH_SUPERCIRCLE Super Circle algorithm. 


═══ <hidden> BITMAPINFOHEADER2 Field - cSize1 ═══

 cSize1 (ULONG) 
    Size value 1. 

    If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error 
    damping as a percentage in the range 0 through 100. A value of 100% 
    indicates no damping, and a value of 0% indicates that any errors are not 
    diffused. 

    If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the x dimension of 
    the pattern used, in pels. 


═══ <hidden> BITMAPINFOHEADER2 Field - cSize2 ═══

 cSize2 (ULONG) 
    Size value 2. 

    If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is 
    ignored. 

    If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the y dimension of 
    the pattern used, in pels. 


═══ <hidden> BITMAPINFOHEADER2 Field - ulColorEncoding ═══

 ulColorEncoding (ULONG) 
    Color encoding. 

    BCE_RGB        Each element in the color array is an RGB2 datatype. This is 
                   the default value. 


═══ <hidden> BITMAPINFOHEADER2 Field - ulIdentifier ═══

 ulIdentifier (ULONG) 
    Reserved for application use. 


═══ 1.7. BOOL ═══

Boolean. 

Valid values are FALSE, which is 0, and TRUE, which is 1. 

typedef unsigned long BOOL;


═══ 1.8. BYTE ═══

A byte. 

typedef unsigned char BYTE;


═══ 1.9. CHAR ═══

Single-byte character. 

#define CHAR char


═══ 1.10. CHARBUNDLE ═══

Character-attributes bundle structure. 

typedef struct _CHARBUNDLE {
  LONG       lColor;         /*  Character foreground color. */
  LONG       lBackColor;     /*  Character background color. */
  USHORT     usMixMode;      /*  Character foreground-mix mode. */
  USHORT     usBackMixMode;  /*  Character background-mix mode. */
  USHORT     usSet;          /*  Character set. */
  USHORT     usPrecision;    /*  Character precision. */
  SIZEF      sizfxCell;      /*  Character cell size. */
  POINTL     ptlAngle;       /*  Character angle. */
  POINTL     ptlShear;       /*  Character shear. */
  USHORT     usDirection;    /*  Character direction. */
  USHORT     usTextAlign;    /*  Text alignment. */
  FIXED      fxExtra;        /*  Character extra. */
  FIXED      fxBreakExtra;   /*  Character break extra. */
} CHARBUNDLE;

typedef CHARBUNDLE *PCHARBUNDLE;


═══ <hidden> CHARBUNDLE Field - lColor ═══

 lColor (LONG) 
    Character foreground color. 


═══ <hidden> CHARBUNDLE Field - lBackColor ═══

 lBackColor (LONG) 
    Character background color. 


═══ <hidden> CHARBUNDLE Field - usMixMode ═══

 usMixMode (USHORT) 
    Character foreground-mix mode. 


═══ <hidden> CHARBUNDLE Field - usBackMixMode ═══

 usBackMixMode (USHORT) 
    Character background-mix mode. 


═══ <hidden> CHARBUNDLE Field - usSet ═══

 usSet (USHORT) 
    Character set. 


═══ <hidden> CHARBUNDLE Field - usPrecision ═══

 usPrecision (USHORT) 
    Character precision. 


═══ <hidden> CHARBUNDLE Field - sizfxCell ═══

 sizfxCell (SIZEF) 
    Character cell size. 


═══ <hidden> CHARBUNDLE Field - ptlAngle ═══

 ptlAngle (POINTL) 
    Character angle. 


═══ <hidden> CHARBUNDLE Field - ptlShear ═══

 ptlShear (POINTL) 
    Character shear. 


═══ <hidden> CHARBUNDLE Field - usDirection ═══

 usDirection (USHORT) 
    Character direction. 


═══ <hidden> CHARBUNDLE Field - usTextAlign ═══

 usTextAlign (USHORT) 
    Text alignment. 


═══ <hidden> CHARBUNDLE Field - fxExtra ═══

 fxExtra (FIXED) 
    Character extra. 


═══ <hidden> CHARBUNDLE Field - fxBreakExtra ═══

 fxBreakExtra (FIXED) 
    Character break extra. 


═══ 1.11. CONVCONTEXT ═══

Dynamic-data-exchange conversation context structure. 

typedef struct _CONVCONTEXT {
  ULONG     cb;           /*  Length of structure. */
  ULONG     fsContext;    /*  Options. */
  ULONG     idCountry;    /*  Country code. */
  ULONG     usCodepage;   /*  Code-page identity. */
  ULONG     usLangID;     /*  Language. */
  ULONG     usSubLangID;  /*  Sub-language. */
} CONVCONTEXT;

typedef CONVCONTEXT *PCONVCONTEXT;


═══ <hidden> CONVCONTEXT Field - cb ═══

 cb (ULONG) 
    Length of structure. 

    This must be set to the length of the CONVCONTEXT structure. 


═══ <hidden> CONVCONTEXT Field - fsContext ═══

 fsContext (ULONG) 
    Options. 

    DDECTXT_CASESENSITIVE 
            All strings in this conversation are case sensitive. 


═══ <hidden> CONVCONTEXT Field - idCountry ═══

 idCountry (ULONG) 
    Country code. 


═══ <hidden> CONVCONTEXT Field - usCodepage ═══

 usCodepage (ULONG) 
    Code-page identity. 


═══ <hidden> CONVCONTEXT Field - usLangID ═══

 usLangID (ULONG) 
    Language. 

    Zero is valid and means no language information. 


═══ <hidden> CONVCONTEXT Field - usSubLangID ═══

 usSubLangID (ULONG) 
    Sub-language. 

    Zero is valid and means no sub-language information. 


═══ 1.12. DDEINIT ═══

Dynamic-data-exchange initiation structure. 

typedef struct _DDEINIT {
  ULONG     cb;              /*  Length of structure. */
  PSZ       pszAppName;      /*  Application name. */
  PSZ       pszTopic;        /*  Topic. */
  ULONG     offConvContext;  /*  Conversation context. */
} DDEINIT;

typedef DDEINIT *PDDEINIT;


═══ <hidden> DDEINIT Field - cb ═══

 cb (ULONG) 
    Length of structure. 

    This must be set to the length of the DDEINIT structure. 


═══ <hidden> DDEINIT Field - pszAppName ═══

 pszAppName (PSZ) 
    Application name. 

    Pointer to name of the server application. 

    Application names must not contain slashes or backslashes. These characters 
    are reserved for future use in network implementations. 


═══ <hidden> DDEINIT Field - pszTopic ═══

 pszTopic (PSZ) 
    Topic. 

    Pointer to name of the topic. 


═══ <hidden> DDEINIT Field - offConvContext ═══

 offConvContext (ULONG) 
    Conversation context. 

    Offset to a CONVCONTEXT structure. 


═══ 1.13. DDESTRUCT ═══

Dynamic-data-exchange control structure. 

typedef struct _DDESTRUCT {
  ULONG      cbData;         /*  Length of the data. */
  USHORT     fsStatus;       /*  Status of the data exchange. */
  USHORT     usFormat;       /*  DDE data format. */
  USHORT     offszItemName;  /*  Offset to item name. */
  USHORT     offabData;      /*  Offset to beginning of data. */
} DDESTRUCT;

typedef DDESTRUCT *PDDESTRUCT;

DDE formats, specified in the usFormat parameter, are registered with the atom 
manager, using the system atom table.  The predefined DDE formats are 
guaranteed not to conflict with the values returned by the atom manager. 

Applications can define their own data formats; however, each nonstandard DDE 
format must have a unique identification number. To receive an identification 
number for a nonstardard format, the application must register the name of the 
format in the system atom table. Other applications that have the name of the 
format can then query the system atom table for the format's identification 
number. This method ensures that all applications use the same atom to identify 
a format. 


═══ <hidden> DDESTRUCT Field - cbData ═══

 cbData (ULONG) 
    Length of the data. 

    This is the length of data that occurs after the offabData parameter. If no 
    data exists, this field should contain a zero (0). 


═══ <hidden> DDESTRUCT Field - fsStatus ═══

 fsStatus (USHORT) 
    Status of the data exchange. 

    DDE_FACK 
            Positive acknowledgement 
    DDE_FBUSY 
            Application is busy 
    DDE_FNODATA 
            No data transfer for advise 
    DDE_FACKREQ 
            Acknowledgements are requested 
    DDE_FRESPONSE 
            Response to WM_DDE_REQUEST 
    DDE_NOTPROCESSED 
            DDE message not understood 
    DDE_FAPPSTATUS 
            A 1-byte field of bits that are reserved for application-specific 
            returns. 


═══ <hidden> DDESTRUCT Field - usFormat ═══

 usFormat (USHORT) 
    DDE data format. 

    This parameter can be set to one of the following values: 

    DDEFMT_TEXT 
            System-defined standard format for exchanging text data. 
    SZFMT_BITMAP 
            Specifies that the data is a bit map. 
    SZFMT_CPTEXT 
            Specifies text whose format is defined by a CPTEXT data structure. 
            Applications can use this format to pass multiple-language strings 
            without changing the conversation context. 
    SZFMT_DIF 
            Specifies that the data is in Data Image Format (DIF). 
    SZFMT_DSPBITMAP 
            Specifies that the data is a bit-map representation of a private 
            data format. 
    SZFMT_DSPMETAFILE 
            Specifies that the data is a metafile representation of a private 
            data format. 
    SZFMT_DSPMETAFILEPICT 
            Specifies that the data is a metafile picture representation of a 
            private data format. 
    SZFMT_DSPTEXT 
            Specifies that the data is a text representation of a private data 
            format. 
    SZFMT_LINK 
            Specifies that the data is in link-file format. 
    SZFMT_METAFILE 
            Specifies that the data is a metafile. 
    SZFMT_METAFILEPICT 
            Specifies that the data is a metafile picture defined by an MFP 
            data structure. 
    SZFMT_OEMTEXT 
            Specifies that the data is in OEM Text format. 
    SZFMT_PALETTE 
            Specifies that the data is in palette format. 
    SZFMT_SYLK 
            Specifies that the data is in Synchronous Link format. 
    SZFMT_TEXT 
            Specifies that the data is an array of text characters. These 
            characters can include new-line characters to indicate linebreaks. 
            The zero-length character indicates the end of the text data. 
    SZFMT_TIFF 
            Specifies that the data is in Tag Image File Format (TIFF). 


═══ <hidden> DDESTRUCT Field - offszItemName ═══

 offszItemName (USHORT) 
    Offset to item name. 

    This is the offset to the item name from the start of this structure. Item 
    name is a null (0x00) terminated string. If no item name exists, there must 
    be a single null (0x00) character in this position. (That is, ItemName is 
    ALWAYS a null terminated string.) 


═══ <hidden> DDESTRUCT Field - offabData ═══

 offabData (USHORT) 
    Offset to beginning of data. 

    This is the offset to the data, from the start of this structure. This 
    field should be calculated regardless of the presence of data. If no data 
    exists, cbData must be zero (0). 

    For compatibility reasons, this data should not contain embedded pointers. 
    Offsets should be used instead. 


═══ 1.14. DEVOPENSTRUC ═══

Open-device data structure. 

typedef struct _DEVOPENSTRUC {
  PSZ           pszLogAddress;       /*  Logical address. */
  PSZ           pszDriverName;       /*  Driver name. */
  PDRIVDATA     pdriv;               /*  Driver data. */
  PSZ           pszDataType;         /*  Data type. */
  PSZ           pszComment;          /*  Comment. */
  PSZ           pszQueueProcName;    /*  Queue-processor name. */
  PSZ           pszQueueProcParams;  /*  Queue-processor parameters. */
  PSZ           pszSpoolerParams;    /*  Spooler parameters. */
  PSZ           pszNetworkParams;    /*  Network parameters. */
} DEVOPENSTRUC;

typedef DEVOPENSTRUC *PDEVOPENSTRUC;


═══ <hidden> DEVOPENSTRUC Field - pszLogAddress ═══

 pszLogAddress (PSZ) 
    Logical address. 

    This is required for an OD_DIRECT device being opened with DevOpenDC; it is 
    the logical device address, such as "LPT1" on OS/2. Some drivers may accept 
    a file name for this parameter or even a named pipe. 

    Where output is to be queued (for an OD_QUEUED device), this is the name of 
    the queue for the output device. The queue name can be a UNC name. 

    Note:  This parameter can be a port name for a printer device context. 


═══ <hidden> DEVOPENSTRUC Field - pszDriverName ═══

 pszDriverName (PSZ) 
    Driver name. 

    Character string identifying the printer driver, for example, LASERJET. The 
    Default Device Driver field of the PRQINFO3 structure, associated with the 
    required print queue, gives the driver and device name, separated by a 
    period, for example LASERJET.HP LaserJet IIID. It can contain only the name 
    up to the period, for example LASERJET. 


═══ <hidden> DEVOPENSTRUC Field - pdriv ═══

 pdriv (PDRIVDATA) 
    Driver data. 

    Data that is to be passed directly to the PM device driver. Whether any of 
    this is required depends upon the device driver. 

    For printer device context, this is a pointer to the job properties data. 


═══ <hidden> DEVOPENSTRUC Field - pszDataType ═══

 pszDataType (PSZ) 
    Data type. 

    For an OD_QUEUED or OD_DIRECT device, this parameter defines the type of 
    data that is to be queued as follows: 

    PM_Q_STD        Standard format 
    PM_Q_RAW        Raw format 

    Note that a device driver can define other data types. 

    For OD_QUEUED or OD_DIRECT defice types, the default is supplied by the 
    device driver if pszDataType is not specified. For any other device type, 
    pszDataType is ignored. 


═══ <hidden> DEVOPENSTRUC Field - pszComment ═══

 pszComment (PSZ) 
    Comment. 

    Optional character string that the printer object displays to the user in a 
    job settings notebook. It is recommended that the application include its 
    own name in this comment string. 

    Note:  The job title text is derived from the document name passed to 
           DevEscape (DEVESC_STARTDOC). 


═══ <hidden> DEVOPENSTRUC Field - pszQueueProcName ═══

 pszQueueProcName (PSZ) 
    Queue-processor name. 

    This is the name of the queue processor, for queued output, and is usually 
    the default. 


═══ <hidden> DEVOPENSTRUC Field - pszQueueProcParams ═══

 pszQueueProcParams (PSZ) 
    Queue-processor parameters. 

    Queue processor parameters (optional). They can include information such as 
    the number of copies you want to print and the size of the output area on 
    the printed page. 

    The first parameter (COP) is used for all spool-file formats. The remaining 
    parameters are valid for PM_Q_STD spool files only. Because PM_Q_STD data 
    are used mainly for graphic data, these parameters are described in 
    relation to the printing of picture files. 

    The PMPRINT/PMPLOT queue-processor parameters are separated by spaces and 
    are: 

    COP=n 
             The COP parameter specifies the number of copies of the spool file 
             that you want printed. The value of n must be an integer in the 
             range of 1 through 999. 

             The default is COP=1. 

    ARE=C | w,h,l,t 
             The ARE parameter determines the size and position of the output 
             area. This is the area of the physical page to which printing is 
             restricted. 

             The default value of ARE=C means that the output area is the whole 
             page. Note, however, that the printer cannot print outside its own 
             device clip limits. 

             To size and position the output area at a specific point on the 
             page, use ARE=w,h,l,t, where: 

             w, h                are the width and height of the desired output 
                                 area. 

             l, t                are the offsets of the upper-left corner of 
                                 the output area from the left (l) and from the 
                                 top (t) of the maximum output area. 

             These four values must be given as percentages of the maximum 
             output dimensions. The maximum output area is the area within the 
             device clip limits. 

    FIT=S | l,t 
             The FIT parameter determines which part of the picture is to be 
             printed. You can request the whole of the picture, scaled to fit 
             the output area; or you can position the picture (actual size) 
             anywhere within the output area. This could mean that the picture 
             is clipped at the boundaries of the output area. 

             The default value of FIT=S causes the output to be scaled until 
             the larger of the height or width just fits within the defined 
             output area. The aspect ratio of the picture is maintained. 

             To print the picture in actual size, use FIT=l,t, where l,t are 
             the coordinates of the point in the picture that you want 
             positioned at the center of the output area: l is measured from 
             the left edge of the picture; and t is measured from the top edge. 
             The coordinates must be given as percentages of the actual 
             dimensions of the picture. 

    XFM=0 | 1 
             The XFM parameter enables you to override the picture-positioning 
             and clipping instructions that are provided by the ARE and FIT 
             parameters, including their defaults. 

             The default value of XFM=1 allows the appearance of the output to 
             be determined by the settings of the ARE and FIT parameters. 

             A value of XFM=0 yields output as specified in the picture file. 
             For example, applications that use many different forms can define 
             different positions on each form for their output. 

    COL=M | C 
             The COL parameter enables you to specify color output if you have 
             a color printer. 

             A value of COL=M creates monochrome output (black foreground with 
             no background color). This is supported by all devices. 

             A value of COL=C creates color output. If you request color output 
             on a monochrome device, the printer presentation driver tries to 
             satisfy your request, which can cause problems because the only 
             color available is black. For example, if the picture file 
             specifies a red line on a blue background, both are drawn in 
             black. 

             The default is COL=M when you are addressing a monochrome printer 
             and COL=C when you are addressing a color printer. 

    MAP=N | A 
             The MAP parameter enables you to decide how the neutral colors 
             (those that are not specified in the picture file) are printed. 

             The default value of MAP=N yields a normal representation of the 
             screen picture on a printed page, which means that the page 
             background is white and the foreground is black. 

             A value of MAP=A provides the reverse of the normal 
             representation:  the background is black and the foreground is 
             white on the printed page. 

    CDP=codepage 
             The CDP parameter overrides the codepage to being used for 
             PM_Q_RAW print jobs. The print queue driver uses DEVESC_SETMODE to 
             set the codepage, but not all printer drivers support this device 
             escape. 

    XLT=0 | 1 
             The XLT parameter can eliminate the translation component when 
             printing a metafile if XLT=1. 

             When the resolution of the device is higher than that of the world 
             coordinate space, a small translation of world coordinate point 
             (0,0) occurs on the device to preserve the accuracy of the mapping 
             from world to device coordinate units. For example, (0,0) becomes 
             (1,1) if there are 3 pels to every world coordinate. 

             Normally, this is not noticeable, but it can be a problem with 
             some devices. For example, in order to draw a complete row of 80 
             characters using a device font, a device may require the text to 
             start at device coordinate position zero. Starting at a position 
             other than zero may cause one or more characters at the end of the 
             row to be clipped. In such cases, elimination of the translation 
             is important and can be accomplished by specifying XLT=1. 

             The default is XLT=0. 


═══ <hidden> DEVOPENSTRUC Field - pszSpoolerParams ═══

 pszSpoolerParams (PSZ) 
    Spooler parameters. 

    Spooler parameters (optional) are separated by spaces. They are used for 
    scheduling print jobs and are as follows: 

        The form names that identify the paper to be used, for example, 
         FORM=A4,A5,ENV. The form names are optional; but if they are provided, 
         the spooler is able to hold off printing the jobs until the required 
         form is installed in the printer. If the form name is not provided, 
         the spooler attempts to print the job. The printer driver recognizes 
         that there is a forms problem and displays a FORMS MISMATCH message 
         box. 

        Priority of the print job, for example, PRTY=60. The priority is 
         specified as an integer in the range 1 through 99; 99 is the highest. 
         The default priority value is 50. The application can use the spooler 
         priority parameter to prioritize its own jobs; however, it is not good 
         practice for an application always to use priority 99 in an attempt to 
         get its jobs printed first. 


═══ <hidden> DEVOPENSTRUC Field - pszNetworkParams ═══

 pszNetworkParams (PSZ) 
    Network parameters. 

    Optional parameter that can be used to specify network options; for 
    example, USER=JOESMITH. 


═══ 1.15. DRIVDATA ═══

Driver-data structure. 

typedef struct _DRIVDATA {
  LONG     cb;                /*  Length. */
  LONG     lVersion;          /*  Version. */
  CHAR     szDeviceName[32];  /*  Device name. */
  CHAR     abGeneralData[1];  /*  General data. */
} DRIVDATA;

typedef DRIVDATA *PDRIVDATA;


═══ <hidden> DRIVDATA Field - cb ═══

 cb (LONG) 
    Length. 

    The length of the structure. 


═══ <hidden> DRIVDATA Field - lVersion ═══

 lVersion (LONG) 
    Version. 

    The version number of the data. Version numbers are defined by particular 
    PM device drivers. 


═══ <hidden> DRIVDATA Field - szDeviceName[32] ═══

 szDeviceName[32] (CHAR) 
    Device name. 

    A string in a 32-byte field identifying the particular device (model 
    number, and so on). Again, valid values are defined by PM device drivers. 


═══ <hidden> DRIVDATA Field - abGeneralData[1] ═══

 abGeneralData[1] (CHAR) 
    General data. 

    Data as defined by the Presentation Manager device driver. 

    The data type of this field is defined by the Presentation Manager device 
    driver. It does not contain pointers, as these are not necessarily valid 
    when passed to the device driver. 


═══ 1.16. ERRORID ═══

Error identity. 

typedef ULONG ERRORID;


═══ 1.17. ERRINFO ═══

Error-information structure. 

typedef struct _ERRINFO {
  ULONG       cbFixedErrInfo;  /*  Length of fixed data to this structure. */
  ERRORID     idError;         /*  Error identity. */
  ULONG       cDetailLevel;    /*  Number of levels of detail. */
  ULONG       offaoffszMsg;    /*  Offset to the array of message offsets. */
  ULONG       offBinaryData;   /*  Offset to the binary data. */
} ERRINFO;

typedef ERRINFO *PERRINFO;


═══ <hidden> ERRINFO Field - cbFixedErrInfo ═══

 cbFixedErrInfo (ULONG) 
    Length of fixed data to this structure. 


═══ <hidden> ERRINFO Field - idError ═══

 idError (ERRORID) 
    Error identity. 

    This is identical to the value returned by WinGetLastError. 


═══ <hidden> ERRINFO Field - cDetailLevel ═══

 cDetailLevel (ULONG) 
    Number of levels of detail. 

    This is the number of entries in the array of words pointed to by the 
    following field. One level of detail is provided. 


═══ <hidden> ERRINFO Field - offaoffszMsg ═══

 offaoffszMsg (ULONG) 
    Offset to the array of message offsets. 

    This is an offset to an array of 16-bit offsets to null-terminated strings. 
    Each string is a printable message that offers varying levels of 
    information.  The first level is the least amount of detail, and the 
    remaining levels offer more and more detail. 

    The first level of detail is always an error message string, in the 
    following format: 

            xxxnnnns

            where    xxx    is the product identifier
                     nnnn   is the message number
                     s      is the message severity letter
                              W = warning
                              E = error
                              S = severe error
                              U = unrecoverable


═══ <hidden> ERRINFO Field - offBinaryData ═══

 offBinaryData (ULONG) 
    Offset to the binary data. 

    This can contain additional information relating to the error. 


═══ 1.18. FACENAMEDESC ═══

Face-name description structure. See GpiQueryFaceString. 

typedef struct _FACENAMEDESC {
  USHORT     usSize;         /*  Length of structure. */
  USHORT     usWeightClass;  /*  Weight class. */
  USHORT     usWidthClass;   /*  Width class. */
  USHORT     usReserved;     /*  Reserved. */
  ULONG      flOptions;      /*  Other characteristics of the font. */
} FACENAMEDESC;

typedef FACENAMEDESC *PFACENAMEDESC;


═══ <hidden> FACENAMEDESC Field - usSize ═══

 usSize (USHORT) 
    Length of structure. 


═══ <hidden> FACENAMEDESC Field - usWeightClass ═══

 usWeightClass (USHORT) 
    Weight class. 

    Indicates the visual weight (thickness of strokes) of the characters in the 
    font: 

    FWEIGHT_DONT_CARE 
                                   Any font weight satisfies the request. 
    FWEIGHT_ULTRA_LIGHT 
                                   Ultra-light. 
    FWEIGHT_EXTRA_LIGHT 
                                   Extra-light. 
    FWEIGHT_LIGHT 
                                   Light. 
    FWEIGHT_SEMI_LIGHT 
                                   Semi-light. 
    FWEIGHT_NORMAL 
                                   Medium (normal) weight. 
    FWEIGHT_SEMI_BOLD 
                                   Semi-bold. 
    FWEIGHT_BOLD 
                                   Bold. 
    FWEIGHT_EXTRA_BOLD 
                                   Extra-bold. 
    FWEIGHT_ULTRA_BOLD 
                                   Ultra-bold. 


═══ <hidden> FACENAMEDESC Field - usWidthClass ═══

 usWidthClass (USHORT) 
    Width class. 

    Indicates the relative aspect ratio of the characters of the font in 
    relation to the normal aspect ratio for this type of font: 

    FWIDTH_DONT_CARE 
                                   Any font width satisfies the request. 
    FWIDTH_ULTRA_CONDENSED 
                                   Ultra-condensed (50% of normal). 
    FWIDTH_EXTRA_CONDENSED 
                                   Extra-condensed (62.5% of normal). 
    FWIDTH_CONDENSED 
                                   Condensed (75% of normal). 
    FWIDTH_SEMI_CONDENSED 
                                   Semi-condensed (87.5% of normal). 
    FWIDTH_NORMAL 
                                   Medium (normal). 
    FWIDTH_SEMI_EXPANDED 
                                   Semi-expanded (112.5% of normal). 
    FWIDTH_EXPANDED 
                                   Expanded (125% of normal). 
    FWIDTH_EXTRA_EXPANDED 
                                   Extra-expanded (150% of normal). 
    FWIDTH_ULTRA_EXPANDED 
                                   Ultra-expanded (200% of normal). 


═══ <hidden> FACENAMEDESC Field - usReserved ═══

 usReserved (USHORT) 
    Reserved. 


═══ <hidden> FACENAMEDESC Field - flOptions ═══

 flOptions (ULONG) 
    Other characteristics of the font. 

    FTYPE_ITALIC 
                                   Italic font required. If not specified, 
                                   non-italic font required. 

    FTYPE_ITALIC_DONT_CARE 
                                   Italic and non-italic fonts can satisfy the 
                                   request. If this option is specified, 
                                   FTYPE_ITALIC is ignored. 

    FTYPE_OBLIQUE 
                                   Oblique font required. If not specified, 
                                   non-oblique font required. 

    FTYPE_OBLIQUE_DONT_CARE 
                                   Oblique and non-oblique fonts can satisfy 
                                   the request. If this option is specified, 
                                   FTYPE_OBLIQUE is ignored. 

    FTYPE_ROUNDED 
                                   Rounded font required. If not specified, 
                                   non-rounded font required. 

    FTYPE_ROUNDED_DONT_CARE 
                                   Rounded and non-rounded fonts can satisfy 
                                   the request. If this option is specified, 
                                   FTYPE_ROUNDED is ignored. 


═══ 1.19. FATTRS ═══

Font-attributes structure. 

typedef struct _FATTRS {
  USHORT     usRecordLength;        /*  Length of record. */
  USHORT     fsSelection;           /*  Selection indicators. */
  LONG       lMatch;                /*  Matched-font identity. */
  CHAR       szFacename[FACESIZE];  /*  Typeface name. */
  USHORT     idRegistry;            /*  Registry identifier. */
  USHORT     usCodePage;            /*  Code page. */
  LONG       lMaxBaselineExt;       /*  Maximum baseline extension. */
  LONG       lAveCharWidth;         /*  Average character width. */
  USHORT     fsType;                /*  Type indicators. */
  USHORT     fsFontUse;             /*  Font-use indicators. */
} FATTRS;

typedef FATTRS *PFATTRS;


═══ <hidden> FATTRS Field - usRecordLength ═══

 usRecordLength (USHORT) 
    Length of record. 


═══ <hidden> FATTRS Field - fsSelection ═══

 fsSelection (USHORT) 
    Selection indicators. 

    Flags causing the following features to be simulated by the system. 

    Note:  If an italic flag is applied to a font that is itself defined as 
           italic, the font is slanted further by italic simulation. 

    Underscore or strikeout lines are drawn using the appropriate attributes 
    (for example, color) from the character bundle (see the CHARBUNDLE 
    datatype), not the line bundle (see LINEBUNDLE). The width of the line, and 
    the vertical position of the line in font space, are determined by the 
    font. Horizontally, the line starts from a point in font space directly 
    above or below the start point of each character, and extends to a point 
    directly above or below the escapement point for that character. 

    For this purpose, the start and escapement points are those applicable to 
    left-to-right or right-to-left character directions (see 
    GpiSetCharDirection in Graphics Programming Interface Programming 
    Reference), even if the string is currently being drawn in a top-to-bottom 
    or bottom-to-top direction. 

    For left-to-right or right-to-left directions, any white space generated by 
    the character extra and character break extra attributes (see 
    GpiSetCharExtra and GpiSetCharBreakExtra in Graphics Programming Interface 
    Programming Reference), as well as increments provided by the vector of 
    increments on GpiCharStringPos and GpiCharStringPosAt, are also 
    underlined/overstruck, so that in these cases the line is continuous for 
    the string. 

    FATTR_SEL_ITALIC                   Generate italic font. 

    FATTR_SEL_UNDERSCORE               Generate underscored font. 

    FATTR_SEL_BOLD                     Generate bold font. (Note that the 
                                       resulting characters are wider than 
                                       those in the original font.) 

    FATTR_SEL_STRIKEOUT                Generate font with overstruck 
                                       characters. 

    FATTR_SEL_OUTLINE                  Use an outline font with hollow 
                                       characters. If this flag is not set, 
                                       outline font characters are filled. 
                                       Setting this flag normally gives better 
                                       performance, and for sufficiently small 
                                       characters (depending on device 
                                       resolution) there may be little visual 
                                       difference. 


═══ <hidden> FATTRS Field - lMatch ═══

 lMatch (LONG) 
    Matched-font identity. 


═══ <hidden> FATTRS Field - szFacename[FACESIZE] ═══

 szFacename[FACESIZE] (CHAR) 
    Typeface name. 

    The typeface name of the font, for example, Tms Rmn. 


═══ <hidden> FATTRS Field - idRegistry ═══

 idRegistry (USHORT) 
    Registry identifier. 

    Font registry identifier (zero if unknown). 


═══ <hidden> FATTRS Field - usCodePage ═══

 usCodePage (USHORT) 
    Code page. 

    If zero, the current Gpi code page (see GpiSetCp in Graphics Programming 
    Interface Programming Reference) is used. A subsequent GpiSetCp function 
    changes the code page used for this logical font. 


═══ <hidden> FATTRS Field - lMaxBaselineExt ═══

 lMaxBaselineExt (LONG) 
    Maximum baseline extension. 

    For raster fonts, this should be the height of the required font, in world 
    coordinates. 

    For outline fonts, this should be zero. 


═══ <hidden> FATTRS Field - lAveCharWidth ═══

 lAveCharWidth (LONG) 
    Average character width. 

    For raster fonts, this should be the width of the required font, in world 
    coordinates. 

    For outline fonts, this should be zero. 


═══ <hidden> FATTRS Field - fsType ═══

 fsType (USHORT) 
    Type indicators. 

    FATTR_TYPE_KERNING                 Enable kerning (PostScript only). 

    FATTR_TYPE_MBCS                    Font for mixed single- and double-byte 
                                       code pages. 

    FATTR_TYPE_DBCS                    Font for double-byte code pages. 

    FATTR_TYPE_ANTIALIASED             Antialiased font required. Only valid if 
                                       supported by the device driver. 


═══ <hidden> FATTRS Field - fsFontUse ═══

 fsFontUse (USHORT) 
    Font-use indicators. 

    These flags indicate how the font is to be used. They affect presentation 
    speed and font quality. 

    FATTR_FONTUSE_NOMIX 
                                  Text is not mixed with graphics and can be 
                                  written without regard to any interaction 
                                  with graphics objects. 

    FATTR_FONTUSE_OUTLINE 
                                  Select an outline (vector) font. The font 
                                  characters can be used as part of a path 
                                  definition. If this flag is not set, an 
                                  outline font might or might not be selected. 
                                  If an outline font is selected, however, 
                                  character widths are rounded to an integral 
                                  number of pels. 

    FATTR_FONTUSE_TRANSFORMABLE 
                                  Characters can be transformed (for example, 
                                  scaled, rotated, or sheared). 


═══ 1.20. FIXED ═══

Signed-integer fraction (16:16). This can be treated as a LONG where the value 
has been multiplied by 65 536. 

typedef LONG FIXED;


═══ 1.21. FFDESCS ═══

Font-file descriptor. 

typedef CHAR FFDESCS[2][FACESIZE];


═══ 1.22. FFDESCS2 ═══

Font-file descriptor. 

typedef struct _FFDESCS2 {
  ULONG     cbLength;          /*  Structure length. */
  ULONG     cbFacenameOffset;  /*  Offset of Facename in the structure. */
  BYTE      abFamilyName[1];   /*  Family name. */
} FFDESCS2;

typedef FFDESCS2 *PFFDESC2;


═══ <hidden> FFDESCS2 Field - cbLength ═══

 cbLength (ULONG) 
    Structure length. 

    cbLength is the overall length of the FFDESCS2 structure. It is always 
    rounded up to a multiple of four. 


═══ <hidden> FFDESCS2 Field - cbFacenameOffset ═══

 cbFacenameOffset (ULONG) 
    Offset of Facename in the structure. 

    The facename is a null terminated string. It starts at cbFacenameOffset 
    bytes offset into FFDESCS2. 


═══ <hidden> FFDESCS2 Field - abFamilyName[1] ═══

 abFamilyName[1] (BYTE) 
    Family name. 

    abFamilyName is a null terminated string. 


═══ 1.23. FOCAMETRICS ═══

FOCAMETRICS data structure. 

This structure is returned to applications on the GPIQueryFonts and 
GPIQueryFontMetrics calls and conveys information from the font creator to the 
application. 

typedef struct _FOCAMETRICS {
  ULONG      ulIdentity;                          /*  Structure identity code. */
  ULONG      ulSize;                              /*  Structure size in bytes. */
  CHAR       szFamilyname[32];  /*  Font family name. */
  CHAR       szFacename[32];    /*  Face name. The typeface name defines the particular font; for example, "Times New Roman Bold Italic."** This string is null terminated and is, therefore, limited to 32 characters in length. */
  SHORT      usRegistryId;                        /*  Registry identifier. */
  USHORT     usCodePage;                          /*  Code page supported by the font. */
  SHORT      yEmHeight;                           /*  Em height. */
  SHORT      yXHeight;                            /*  X height. */
  SHORT      yMaxAscender;                        /*  Maximum ascender. */
  SHORT      yMaxDescender;                       /*  Maximum descender. */
  SHORT      yLowerCaseAscent;                    /*  Lowercase ascent. */
  SHORT      yLowerCaseDescent;                   /*  Lowercase descent. */
  SHORT      yInternalLeading;                    /*  Internal leading. */
  SHORT      yExternalLeading;                    /*  External leading. */
  SHORT      xAveCharWidth;                       /*  Average character width. */
  SHORT      xMaxCharInc;                         /*  Maximum character increment. */
  SHORT      xEmInc;                              /*  Em increment. */
  SHORT      yMaxBaselineExt;                     /*  Maximum baseline extent. */
  SHORT      sCharSlope;                          /*  Character slope. */
  SHORT      sInlineDir;                          /*  Inline direction. */
  SHORT      sCharRot;                            /*  Character rotation. */
  USHORT     usWeightClass;                       /*  Weight class. */
  USHORT     usWidthClass;                        /*  Width class. */
  SHORT      xDeviceRes;                          /*  X-device resolution. */
  SHORT      yDeviceRes;                          /*  Y-device resolution. */
  SHORT      usFirstChar;                         /*  First character. */
  SHORT      usLastChar;                          /*  Last character. */
  SHORT      usDefaultChar;                       /*  Default character. */
  SHORT      usBreakChar;                         /*  Break character. */
  SHORT      usNominalPointSize;                  /*  Nominal point size. */
  SHORT      usMinimumPointSize;                  /*  Minimum point size. */
  SHORT      usMaximumPointSize;                  /*  Maximum point size. */
  SHORT      usTypeFlags;                         /*  Type indicators. */
  SHORT      fsDefn;                              /*  Definition indicators. */
  SHORT      fsSelectionFlags;                    /*  Selection indicators. */
  SHORT      fsCapabilities;                      /*  Capabilities. */
  SHORT      ySubscriptXSize;                     /*  Subscript X-size. */
  SHORT      ySubscriptYSize;                     /*  Subscript Y-size. */
  SHORT      ySubscriptXOffset;                   /*  Subscript X-offset. */
  SHORT      ySubscriptYOffset;                   /*  Subscript Y-offset. */
  SHORT      ySuperscriptXSize;                   /*  Superscript X-size. */
  SHORT      ySuperscriptYSize;                   /*  Superscript Y-size. */
  SHORT      ySuperscriptXOffset;                 /*  Superscript X-offset. */
  SHORT      ySuperscriptYOffset;                 /*  Superscript Y-offset. */
  SHORT      yUnderscoreSize;                     /*  Underscore size. */
  SHORT      yUnderscorePosition;                 /*  Underscore position. */
  SHORT      yStrikeoutSize;                      /*  Strikeout size. */
  SHORT      yStrikeoutPosition;                  /*  Strikeout position. */
  SHORT      usKerningPairs;                      /*  Kerning pairs. */
  SHORT      sFamilyClass;                        /*  Font family design classification. */
  PSZ        pszDeviceNameOffset;                 /*  Address where device name is stored. */
} FOCAMETRICS;

typedef FOCAMETRICS *PFOCAMETRICS;


═══ <hidden> FOCAMETRICS Field - ulIdentity ═══

 ulIdentity (ULONG) 
    Structure identity code. 

    Value must be one (1). This field is not part of the FONTMETRICS structure. 


═══ <hidden> FOCAMETRICS Field - ulSize ═══

 ulSize (ULONG) 
    Structure size in bytes. 

    This must be set to the size of the FOCAMETRICS structure. This field is 
    not part of the FONTMETRICS structure. 


═══ <hidden> FOCAMETRICS Field - szFamilyname[32] ═══

 szFamilyname[32] (CHAR) 
    Font family name. 

    The family name defines the basic appearance of the font; for example, 
    "Times New Roman."** This string is null terminated and is, therefore, 
    limited to 32 characters in length. 


═══ <hidden> FOCAMETRICS Field - szFacename[32] ═══

 szFacename[32] (CHAR) 
    Face name. The typeface name defines the particular font; for example, 
    "Times New Roman Bold Italic."** This string is null terminated and is, 
    therefore, limited to 32 characters in length. 


═══ <hidden> FOCAMETRICS Field - usRegistryId ═══

 usRegistryId (SHORT) 
    Registry identifier. 

    The IBM registered number (or zero). 


═══ <hidden> FOCAMETRICS Field - usCodePage ═══

 usCodePage (USHORT) 
    Code page supported by the font. 

    Defines the registered code page supported by the font. A value of zero (0) 
    implies that the font may be used with any of the code pages supported by 
    OS/2. 

    When a font contains special symbols for which there is no registered code 
    page, then code page 65400 is used. 


═══ <hidden> FOCAMETRICS Field - yEmHeight ═══

 yEmHeight (SHORT) 
    Em height. 

    The height of the Em square in world coordinate units. This height 
    corresponds to the point size for the font. 


═══ <hidden> FOCAMETRICS Field - yXHeight ═══

 yXHeight (SHORT) 
    X height. 

    The nominal height above the baseline for lowercase characters (ignoring 
    ascenders), in world coordinate units. 


═══ <hidden> FOCAMETRICS Field - yMaxAscender ═══

 yMaxAscender (SHORT) 
    Maximum ascender. 

    The maximum height above the baseline reached by any part of any symbol in 
    the font, in world coordinate units. This field may exceed yEmHeight. 


═══ <hidden> FOCAMETRICS Field - yMaxDescender ═══

 yMaxDescender (SHORT) 
    Maximum descender. 

    The maximum depth below the baseline reached by any part of any symbol in 
    the font, in world coordinate units. This field may exceed yEmHeight. 


═══ <hidden> FOCAMETRICS Field - yLowerCaseAscent ═══

 yLowerCaseAscent (SHORT) 
    Lowercase ascent. 

    The maximum height above the baseline reached by any part of any lowercase 
    (Latin unaccented ' a ' through ' z ') symbol in the font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - yLowerCaseDescent ═══

 yLowerCaseDescent (SHORT) 
    Lowercase descent. 

    The maximum depth below the baseline reached by any part of any lowercase 
    (Latin unaccented ' a ' through ' z ') symbol in the font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - yInternalLeading ═══

 yInternalLeading (SHORT) 
    Internal leading. 

    The amount of space which, when subtracted from yMaxAscender, gives a 
    measure of the distance above the baseline that characters extend. This 
    measure is font-design dependent, but glyph-set independent. Therefore, 
    this calculation approximates the visual top to a row of characters without 
    actually looking at the characters in the row. 

    It is recommended that applications use this field to position the first 
    line of a block of text by subtracting yInternalLeading from yMaxAscender. 
    Then position the baseline that distance below the preceding information 
    (text or graphic element). 

    Note:  This use does not guarantee that characters will not overwrite those 
           above them; it does give a font designer's view of where to place 
           the text. Collision should be tested for and additional space 
           allocated if necessary. 


═══ <hidden> FOCAMETRICS Field - yExternalLeading ═══

 yExternalLeading (SHORT) 
    External leading. 

    The amount of guaranteed white space advised by the font designer to appear 
    between adjacent rows of text. This value may be zero (0). 

    Note:  The fonts built into Presentation Manager have zero (0) in this 
           field. 


═══ <hidden> FOCAMETRICS Field - xAveCharWidth ═══

 xAveCharWidth (SHORT) 
    Average character width. 

    This is determined by multiplying the width of each lowercase character  by 
    a constant, adding the products, and then dividing by 1000. The letters, 
    plus their constants, are listed below: 

         Letter  Constant 
    a            64 
    b            14 
    c            27 
    d            35 
    e            100 
    f            20 
    g            14 
    h            42 
    i            63 
    j            3 
    k            6 
    l            35 
    m            20 
    n            56 
    o            56 
    p            17 
    q            4 
    r            49 
    s            56 
    t            71 
    u            31 
    v            10 
    w            18 
    x            3 
    y            18 
    z            2 
    space        166 

                 Note:  For fixed pitch fonts, this value will be the same as 
                        the (A width + B width + C width) escapement of each 
                        character. 


═══ <hidden> FOCAMETRICS Field - xMaxCharInc ═══

 xMaxCharInc (SHORT) 
    Maximum character increment. 

    The maximum character increment for the font, in world coordinate units. 


═══ <hidden> FOCAMETRICS Field - xEmInc ═══

 xEmInc (SHORT) 
    Em increment. 

    The width of the Em square in world coordinate units. This width 
    corresponds to the point size of the font. When the horizontal device 
    resolution equals the vertical device resolution, width is equal to the em 
    height. 


═══ <hidden> FOCAMETRICS Field - yMaxBaselineExt ═══

 yMaxBaselineExt (SHORT) 
    Maximum baseline extent. 

    The maximum vertical space occupied by the font, in world coordinate units. 
    This space is the sum of yMaxAscender and yMaxDescender if both are 
    positive. It is also the sum of yInternalLeading and yEmHeight. 

    One possible line spacing can be computed by adding yMaxBaselineExt to 
    yInternalLeading. Such a line spacing, however, would be dependent on the 
    glyph set included in the font. If a new version of the font is made 
    available with new glyphs, then it is possible that this value will change 
    because one of the new glyphs has gone above the previous yMaxAscender or 
    below the previous yMaxDescender. More sophisticated applications will base 
    their line spacing on the point size (yEmHeight) of the font, which is an 
    invariant of the font, multiplied by some factor (for example, 120%), plus 
    any external leading. 

    yMaxBaselineExt may exceed yEmHeight. 


═══ <hidden> FOCAMETRICS Field - sCharSlope ═══

 sCharSlope (SHORT) 
    Character slope. 

    Defines the nominal slope of the characters of a font. The slope is defined 
    in degrees, increasing clockwise from the vertical. An italic font is an 
    example of a font with a nonzero slope. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in the following example. 


                      180 degrees 59 minutes would be represented as:

                      │   < byte 1  > │   < byte 2   >  │

                      │ │ < Minutes > │   < Degrees >   │

                      │0│1 1 1 0 1 1  │0 1 0 1 1 0 1 0 0│

                        │  59 min     │   180 degrees   │


═══ <hidden> FOCAMETRICS Field - sInlineDir ═══

 sInlineDir (SHORT) 
    Inline direction. 

    The direction in which the characters in the font are designed for viewing. 
    Shown in degrees, increasing clockwise from the horizontal (left-to-right). 
    Characters are added to a line of text in the inline direction. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in sCharSlope. 


═══ <hidden> FOCAMETRICS Field - sCharRot ═══

 sCharRot (SHORT) 
    Character rotation. 

    The rotation of the character glyphs with respect to the baseline, the 
    angle increasing counterclockwise. This is the angle assigned by the font 
    designer. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in sCharSlope. 


═══ <hidden> FOCAMETRICS Field - usWeightClass ═══

 usWeightClass (USHORT) 
    Weight class. 

    Indicates the visual weight (thickness of strokes) of the characters in the 
    font: 

         Value   Description 
    1000         Ultra-light 
    2000         Extra-light 
    3000         Light 
    4000         Semi-light 
    5000         Medium (normal) 
    6000         Semi-bold 
    7000         Bold 
    8000         Extra-bold 
    9000         Ultra-bold 


═══ <hidden> FOCAMETRICS Field - usWidthClass ═══

 usWidthClass (USHORT) 
    Width class. 

    Indicates the relative aspect ratio of the font characters in relation to 
    the normal aspect ratio for this type of font: 

        ┌───────────────┬──────────────────────────────┬───────────────┐
        │Value          │Description                   │% of Normal    │
        │               │                              │Width          │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │1000           │Ultra-condensed               │50             │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │2000           │Extra-condensed               │62.5           │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │3000           │Condensed                     │75             │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │4000           │Semi-condensed                │87.5           │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │5000           │Medium (normal)               │100            │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │6000           │Semi-expanded                 │112.5          │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │7000           │Expanded                      │125            │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │8000           │Extra-expanded                │150            │
        ├───────────────┼──────────────────────────────┼───────────────┤
        │9000           │Ultra-expanded                │200            │
        └───────────────┴──────────────────────────────┴───────────────┘


═══ <hidden> FOCAMETRICS Field - xDeviceRes ═══

 xDeviceRes (SHORT) 
    X-device resolution. 

    For bit-map fonts, this is the resolution in the X direction of the 
    intended target device, measured in pels per inch. 

    For outline fonts, this is the number of notional units in the X direction 
    of the Em square, measured in notional units per Em. (Notional units are 
    the units in which the outline is defined.) 


═══ <hidden> FOCAMETRICS Field - yDeviceRes ═══

 yDeviceRes (SHORT) 
    Y-device resolution. 

    For bit-map fonts, this is the resolution in the Y direction of the 
    intended target device, measured in pels per inch. 

    For outline fonts, this is the number of notional units in the Y direction 
    of the Em square, measured in notional units per Em. (Notional units are 
    the units in which the outline is defined.) 


═══ <hidden> FOCAMETRICS Field - usFirstChar ═══

 usFirstChar (SHORT) 
    First character. 

    The code point of the first character in the font. 


═══ <hidden> FOCAMETRICS Field - usLastChar ═══

 usLastChar (SHORT) 
    Last character. 

    The code point of the last character in the font, expressed as an offset 
    from usFirstChar. 

    All code points between the first and last character specified must be 
    supported by the font. 


═══ <hidden> FOCAMETRICS Field - usDefaultChar ═══

 usDefaultChar (SHORT) 
    Default character. 

    The code point that is used if a code point outside the range supported by 
    the font is used, expressed as an offset from usFirstChar. 


═══ <hidden> FOCAMETRICS Field - usBreakChar ═══

 usBreakChar (SHORT) 
    Break character. 

    The code point that represents the "space" or "break" character for this 
    font, expressed as an offset from usFirstChar. For example, if the first 
    character is the space in code page 850, usFirstChar = 32, and usBreakChar 
    = 0. 


═══ <hidden> FOCAMETRICS Field - usNominalPointSize ═══

 usNominalPointSize (SHORT) 
    Nominal point size. 

    For a bit-map font, this field contains the height of the font. 

    For an outline font, this field contains the height that the font designer 
    intended for this font. For example, some fonts are designed for text use, 
    in which case a value of 120 (12 point) would probably be placed in this 
    field. Other fonts are designed for "display" use ("display" is a 
    typographer's term for larger point sizes). This is not the only size at 
    which the font can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FOCAMETRICS Field - usMinimumPointSize ═══

 usMinimumPointSize (SHORT) 
    Minimum point size. 

    For a bit-map font, this field is not applicable. 

    For an outline font, this field contains the minimum height that the font 
    designer intended for this font. Note that this is not a restriction on the 
    size at which the font can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FOCAMETRICS Field - usMaximumPointSize ═══

 usMaximumPointSize (SHORT) 
    Maximum point size. 

    For a bit-map font, this field is not applicable. 

    For an outline font, this field contains the maximum height that the font 
    designer intended for this font. Note that this is not a restriction on the 
    size at which the font can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FOCAMETRICS Field - usTypeFlags ═══

 usTypeFlags (SHORT) 
    Type indicators. 

    These flags contain the following information: 

    FM_TYPE_FIXED                 Characters in the font have the same fixed 
                                  width. 
    FM_TYPE_LICENSED              Licensed (protected) font. 
    FM_TYPE_KERNING               Font contains kerning information. 
    FM_TYPE_64K                   Font is larger than 64KB (KB equals 1024 
                                  bytes) in size. Only one of the following 
                                  bits (FM_TYPE_DBCS or FM_TYPE_MCBS) may be 
                                  set. If both of those bits are false (not 
                                  set), the font is for single-byte code pages. 
    FM_TYPE_DBCS                  Font is for double-byte code pages. 
    FM_TYPE_MBCS                  Font is for mixed single- and double-byte 
                                  code pages. 
    FM_TYPE_FACETRUNC             Font szFacename[32] has been truncated. 
    FM_TYPE_FAMTRUNC              Font szFamilyname[32] has been truncated. 


═══ <hidden> FOCAMETRICS Field - fsDefn ═══

 fsDefn (SHORT) 
    Definition indicators. 

    These indicators contain the following font definition data: 

    FM_DEFN_OUTLINE               Font is a vector (outline) font; otherwise, 
                                  it is a bit map font. 
    FM_DEFN_GENERIC               Font is in a format that can be used by the 
                                  GPI; otherwise, it is a device font. 


═══ <hidden> FOCAMETRICS Field - fsSelectionFlags ═══

 fsSelectionFlags (SHORT) 
    Selection indicators. 

    These indicators contain information about the font patterns in the 
    physical font. 

    Note:  The flags do not reflect simulations applied to the physical font. 

    FM_SEL_ITALIC                 TRUE indicates that this font is designed as 
                                  an italic font. 
    FM_SEL_UNDERSCORE             TRUE indicates that this font is designed 
                                  with underscores included in each character. 
    FM_SEL_NEGATIVE               TRUE indicates that this font is designed 
                                  with the background and foreground reversed. 
    FM_SEL_OUTLINE                TRUE indicates that this font is designed 
                                  with outline (hollow) characters. 
    FM_SEL_STRIKEOUT              TRUE indicates that this font is designed 
                                  with an overstrike through each character. 
    FM_SEL_BOLD                   TRUE indicates that this font is designed 
                                  with bold characters. 


═══ <hidden> FOCAMETRICS Field - fsCapabilities ═══

 fsCapabilities (SHORT) 
    Capabilities. 

    This attribute applies only to device fonts. 

    FM_CAP_NOMIX           Characters may not be mixed with graphics. 
    QUALITY                The most significant byte may contain the following 
                           numeric value: 
                           0        Undefined 

                           1        DP quality 

                           2        DP draft 

                           3        Near Letter Quality 

                           4        Letter Quality 


═══ <hidden> FOCAMETRICS Field - ySubscriptXSize ═══

 ySubscriptXSize (SHORT) 
    Subscript X-size. 

    The recommended horizontal point size for subscripts for this font, in 
    world coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySubscriptYSize ═══

 ySubscriptYSize (SHORT) 
    Subscript Y-size. 

    The recommended vertical point size for subscripts for this font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySubscriptXOffset ═══

 ySubscriptXOffset (SHORT) 
    Subscript X-offset. 

    The recommended baseline X-offset for subscripts for this font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySubscriptYOffset ═══

 ySubscriptYOffset (SHORT) 
    Subscript Y-offset. 

    The recommended baseline Y-offset for subscripts for this font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySuperscriptXSize ═══

 ySuperscriptXSize (SHORT) 
    Superscript X-size. 

    The recommended horizontal point size for superscripts for this font, in 
    world coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySuperscriptYSize ═══

 ySuperscriptYSize (SHORT) 
    Superscript Y-size. 

    The recommended vertical point size for superscripts for this font, in 
    world coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySuperscriptXOffset ═══

 ySuperscriptXOffset (SHORT) 
    Superscript X-offset. 

    The recommended baseline X-offset for superscripts for this font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - ySuperscriptYOffset ═══

 ySuperscriptYOffset (SHORT) 
    Superscript Y-offset. 

    The recommended baseline Y-offset for superscripts for this font, in world 
    coordinate units. 


═══ <hidden> FOCAMETRICS Field - yUnderscoreSize ═══

 yUnderscoreSize (SHORT) 
    Underscore size. 

    The width (thickness) of the underscore stroke, in world coordinate units. 
    This describes the actual underscore in the font if FM_SEL_UNDERSCORE is 
    also set. Otherwise, it describes what the graphics engine will simulate if 
    underscore is requested in GpiCreateLogFont. 


═══ <hidden> FOCAMETRICS Field - yUnderscorePosition ═══

 yUnderscorePosition (SHORT) 
    Underscore position. 

    The position of the underscore stroke from the baseline, in world 
    coordinate units. This value describes the actual underscore in the font if 
    FM_SEL_UNDERSCORE is also set. Otherwise, it describes what the graphics 
    engine will simulate if underscore is requested in GpiCreateLogFont. 

    Note:  Positive values mean below the baseline. 


═══ <hidden> FOCAMETRICS Field - yStrikeoutSize ═══

 yStrikeoutSize (SHORT) 
    Strikeout size. 

    The width of the strikeout stroke, in world coordinate units. This value 
    describes the actual strikeout in the font if FM_SEL_STRIKEOUT is also set. 
    Otherwise, it describes what the graphics engine will simulate if 
    overstrike is requested in GpiCreateLogFont. 


═══ <hidden> FOCAMETRICS Field - yStrikeoutPosition ═══

 yStrikeoutPosition (SHORT) 
    Strikeout position. 

    The position of the strikeout stroke relative to the baseline, in world 
    coordinate units. This value describes the actual strikeout in the font if 
    FM_SEL_STRIKEOUT is also set. Otherwise, it describes what the graphics 
    engine will simulate if overstrike is requested in GpiCreateLogFont. 


═══ <hidden> FOCAMETRICS Field - usKerningPairs ═══

 usKerningPairs (SHORT) 
    Kerning pairs. 

    The number of kerning pairs in the kerning pair table. 


═══ <hidden> FOCAMETRICS Field - sFamilyClass ═══

 sFamilyClass (SHORT) 
    Font family design classification. 

    This value contains a font class and its subclass. 


═══ <hidden> FOCAMETRICS Field - pszDeviceNameOffset ═══

 pszDeviceNameOffset (PSZ) 
    Address where device name is stored. 


═══ 1.24. FONTMETRICS ═══

Font-metrics structure. 

This structure is returned to applications on the GpiQueryFonts and 
GpiQueryFontMetrics calls and conveys information from the font creator to the 
application. 

typedef struct _FONTMETRICS {
  CHAR       szFamilyname[FACESIZE];  /*  Family name. */
  CHAR       szFacename[FACESIZE];    /*  Face name. */
  USHORT     idRegistry;              /*  Registry identifier. */
  USHORT     usCodePage;              /*  Code page. */
  LONG       lEmHeight;               /*  Em height. */
  LONG       lXHeight;                /*  X height. */
  LONG       lMaxAscender;            /*  Maximum ascender. */
  LONG       lMaxDescender;           /*  Maximum descender. */
  LONG       lLowerCaseAscent;        /*  Lowercase ascent. */
  LONG       lLowerCaseDescent;       /*  Lowercase descent. */
  LONG       lInternalLeading;        /*  Internal leading. */
  LONG       lExternalLeading;        /*  External leading. */
  LONG       lAveCharWidth;           /*  Average character width. */
  LONG       lMaxCharInc;             /*  Maximum character increment. */
  LONG       lEmInc;                  /*  Em increment. */
  LONG       lMaxBaselineExt;         /*  Maximum baseline extent. */
  SHORT      sCharSlope;              /*  Character slope. */
  SHORT      sInlineDir;              /*  Inline direction. */
  SHORT      sCharRot;                /*  Character rotation. */
  USHORT     usWeightClass;           /*  Weight class. */
  USHORT     usWidthClass;            /*  Width class. */
  SHORT      sXDeviceRes;             /*  X-device resolution. */
  SHORT      sYDeviceRes;             /*  Y-device resolution. */
  SHORT      sFirstChar;              /*  First character. */
  SHORT      sLastChar;               /*  Last character. */
  SHORT      sDefaultChar;            /*  Default character. */
  SHORT      sBreakChar;              /*  Break character. */
  SHORT      sNominalPointSize;       /*  Nominal point size. */
  SHORT      sMinimumPointSize;       /*  Minimum point size. */
  SHORT      sMaximumPointSize;       /*  Maximum point size. */
  USHORT     fsType;                  /*  Type indicators. */
  USHORT     fsDefn;                  /*  Definition indicators. */
  USHORT     fsSelection;             /*  Selection indicators. */
  USHORT     fsCapabilities;          /*  Font capabilities. */
  LONG       lSubscriptXSize;         /*  Subscript x-size. */
  LONG       lSubscriptYSize;         /*  Subscript y-size. */
  LONG       lSubscriptXOffset;       /*  Subscript x-offset. */
  LONG       lSubscriptYOffset;       /*  Subscript y-offset. */
  LONG       lSuperscriptXSize;       /*  Superscript x-size. */
  LONG       lSuperscriptYSize;       /*  Superscript y-size. */
  LONG       lSuperscriptXOffset;     /*  Superscript x-offset. */
  LONG       lSuperscriptYOffset;     /*  Superscript y-offset. */
  LONG       lUnderscoreSize;         /*  Underscore size. */
  LONG       lUnderscorePosition;     /*  Underscore position. */
  LONG       lStrikeoutSize;          /*  Strikeout size. */
  LONG       lStrikeoutPosition;      /*  Strikeout position. */
  SHORT      sKerningPairs;           /*  Kerning pairs. */
  SHORT      sFamilyClass;            /*  Font family design classification. */
  LONG       lMatch;                  /*  Matched font identity. */
  LONG       FamilyNameAtom;          /*  Font family name atom. */
  LONG       FaceNameAtom;            /*  Font facename atom. */
  PANOSE     panose;                  /*  Panose font descriptor. */
} FONTMETRICS;

typedef FONTMETRICS *PFONTMETRICS;


═══ <hidden> FONTMETRICS Field - szFamilyname[FACESIZE] ═══

 szFamilyname[FACESIZE] (CHAR) 
    Family name. 

    The family name of the font that describes the basic appearance of the 
    font, for example, Times New Roman** This string is null terminated, and 
    therefore is limited to 31 characters in length. Longer names may be 
    retrieved by using the FamilyNameAtom field to retrieve the full name from 
    the System Atom table. 


═══ <hidden> FONTMETRICS Field - szFacename[FACESIZE] ═══

 szFacename[FACESIZE] (CHAR) 
    Face name. 

    The typeface name that defines the particular font, for example, Times New 
    Roman Bold Italic. This string is null terminated, and therefore is limited 
    to 31 characters in length. Longer names may be retrieved by using the 
    FaceNameAtom field to retrieve the full name from the System Atom table. 


═══ <hidden> FONTMETRICS Field - idRegistry ═══

 idRegistry (USHORT) 
    Registry identifier. 

    The IBM registered number (or zero). 


═══ <hidden> FONTMETRICS Field - usCodePage ═══

 usCodePage (USHORT) 
    Code page. 

    Defines the registered code page supported by the font. For example, the 
    original IBM PC code page is 437. A value of 0 implies that the font may be 
    used with any of the OS/2 supported code pages. 

    Where a font contains special symbols for which there is no registered code 
    page, then code page 65400 is used. 


═══ <hidden> FONTMETRICS Field - lEmHeight ═══

 lEmHeight (LONG) 
    Em height. 

    The height of the Em square in world coordinate units. This corresponds to 
    the point size for the font. 


═══ <hidden> FONTMETRICS Field - lXHeight ═══

 lXHeight (LONG) 
    X height. 

    The nominal height above the baseline for lowercase characters (ignoring 
    ascenders) in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lMaxAscender ═══

 lMaxAscender (LONG) 
    Maximum ascender. 

    The maximum height above the baseline reached by any part of any symbol in 
    the font in world coordinate units. This field may exceed lEmHeight. 


═══ <hidden> FONTMETRICS Field - lMaxDescender ═══

 lMaxDescender (LONG) 
    Maximum descender. 

    The maximum depth below the baseline reached by any part of any symbol in 
    the font in world coordinate units. This field may exceed lEmHeight. 


═══ <hidden> FONTMETRICS Field - lLowerCaseAscent ═══

 lLowerCaseAscent (LONG) 
    Lowercase ascent. 

    The maximum height above the baseline reached by any part of any lowercase 
    (Latin unaccented "a" through "z") symbol in the font in world coordinate 
    units. 


═══ <hidden> FONTMETRICS Field - lLowerCaseDescent ═══

 lLowerCaseDescent (LONG) 
    Lowercase descent. 

    The maximum depth below the baseline reached by any part of any lowercase 
    (Latin unaccented "a" through "z") symbol in the font in world coordinate 
    units. 


═══ <hidden> FONTMETRICS Field - lInternalLeading ═══

 lInternalLeading (LONG) 
    Internal leading. 

    The amount of space which, when subtracted from lMaxAscender, gives a 
    font-design dependent, but glyph-set independent, measure of the distance 
    above the baseline that characters extend. This calculation approximates 
    the visual top to a row of characters without actually looking at the 
    characters in the row. 

    For optimum results, this field should be used by applications to position 
    the first line of a block of text by subtracting it from lMaxAscender and 
    positioning the baseline that distance below whatever is above the text. 

    Note:  This does not guarantee that characters will not overwrite 
           information above them, but does give a font designer's view of 
           where to place the text. Collision should be tested for, and 
           additional space allocated if necessary. 


═══ <hidden> FONTMETRICS Field - lExternalLeading ═══

 lExternalLeading (LONG) 
    External leading. 

    The amount of guaranteed white space advised by the font designer to appear 
    between adjacent rows of text. This value may be zero. 

    Note:  The fonts built in to Presentation Manager have zero in this field. 


═══ <hidden> FONTMETRICS Field - lAveCharWidth ═══

 lAveCharWidth (LONG) 
    Average character width. 

    This is determined by multiplying the width of each lowercase character by 
    a constant, adding the products, and then dividing by 1000. The letters 
    involved in this, plus their constants, are as follows: 

         Letter    Constant 
    a              64 
    b              14 
    c              27 
    d              35 
    e              100 
    f              20 
    g              14 
    h              42 
    i              63 
    j              3 
    k              6 
    l              35 
    m              20 
    n              56 
    o              56 
    p              17 
    q              4 
    r              49 
    s              56 
    t              71 
    u              31 
    v              10 
    w              18 
    x              3 
    y              18 
    z              2 
    space          166 

    Note:  For fixed pitch fonts, this value will be the same as the (A width + 
           B width + C width) escapement of each character. 


═══ <hidden> FONTMETRICS Field - lMaxCharInc ═══

 lMaxCharInc (LONG) 
    Maximum character increment. 

    The maximum character increment for the font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lEmInc ═══

 lEmInc (LONG) 
    Em increment. 

    The width of the Em square in world coordinate units. This corresponds to 
    the point size of the font.  When the horizontal device resolution equals 
    the vertical device resolution this is equal to the em height. 


═══ <hidden> FONTMETRICS Field - lMaxBaselineExt ═══

 lMaxBaselineExt (LONG) 
    Maximum baseline extent. 

    The maximum vertical space occupied by the font, in world coordinate units. 
    This is the sum of lMaxAscender and lMaxDescender if both are positive. It 
    is also the sum of lInternalLeading and lEmHeight. 

    One possible type of line spacing can be computed by adding lMaxBaselineExt 
    to lExternalLeading. Such a line spacing, however, would be dependent on 
    the glyph set included in the font. If a new version of the font should be 
    made available, with new glyphs, then it is possible that this value will 
    change because one of the new glyphs has gone above the previous 
    lMaxAscender or below the previous lMaxDescender. More sophisticated 
    applications will base line spacing on the point size (lEmHeight) of the 
    font, which is an invariant of the font, multiplied by some factor (for 
    example, 120%) plus any external leading. 

    This field may exceed lEmHeight. 


═══ <hidden> FONTMETRICS Field - sCharSlope ═══

 sCharSlope (SHORT) 
    Character slope. 

    Defines the nominal slope for the characters of a font. The slope is 
    defined in degrees increasing clockwise from the vertical. An italic font 
    is an example of a font with a nonzero slope. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in the following example: 


                      180 degrees 59 minutes would be represented as :

                      │   < byte 1  > │   < byte 2   >  │

                      │ │ < Minutes > │   < Degrees >   │

                      │0│1 1 1 0 1 1  │0 1 0 1 1 0 1 0 0│

                        │  59 min     │   180 degrees   │


═══ <hidden> FONTMETRICS Field - sInlineDir ═══

 sInlineDir (SHORT) 
    Inline direction. 

    The direction in which the characters in the font are designed for viewing. 
    The direction is defined in degrees increasing clockwise from the 
    horizontal (left-to-right). Characters are added to a line of text in the 
    inline direction. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in sCharSlope. 


═══ <hidden> FONTMETRICS Field - sCharRot ═══

 sCharRot (SHORT) 
    Character rotation. 

    The rotation of the character glyphs with respect to the baseline, the 
    angle increasing counter clockwise. This is the angle assigned by the font 
    designer. 

    Note:  The units for this metric are degrees and minutes, encoded as shown 
           in sCharSlope. 


═══ <hidden> FONTMETRICS Field - usWeightClass ═══

 usWeightClass (USHORT) 
    Weight class. 

    Indicates the visual weight (thickness of strokes) of the characters in the 
    font: 

         Value   Description 
    1            Ultra-light 
    2            Extra-light 
    3            Light 
    4            Semi-light 
    5            Medium (normal) 
    6            Semi-bold 
    7            Bold 
    8            Extra-bold 
    9            Ultra-bold 


═══ <hidden> FONTMETRICS Field - usWidthClass ═══

 usWidthClass (USHORT) 
    Width class. 

    Indicates the relative aspect ratio of the characters of the font in 
    relation to the normal aspect ratio for this type of font: 

        ┌─────┬───────────────┬────────────────────┐
        │Value│Description    │% of normal width   │
        ├─────┼───────────────┼────────────────────┤
        │1    │Ultra-condensed│50                  │
        ├─────┼───────────────┼────────────────────┤
        │2    │Extra-condensed│62.5                │
        ├─────┼───────────────┼────────────────────┤
        │3    │Condensed      │75                  │
        ├─────┼───────────────┼────────────────────┤
        │4    │Semi-condensed │87.5                │
        ├─────┼───────────────┼────────────────────┤
        │5    │Medium (normal)│100                 │
        ├─────┼───────────────┼────────────────────┤
        │6    │Semi-expanded  │112.5               │
        ├─────┼───────────────┼────────────────────┤
        │7    │Expanded       │125                 │
        ├─────┼───────────────┼────────────────────┤
        │8    │Extra-expanded │150                 │
        ├─────┼───────────────┼────────────────────┤
        │9    │Ultra-expanded │200                 │
        └─────┴───────────────┴────────────────────┘


═══ <hidden> FONTMETRICS Field - sXDeviceRes ═══

 sXDeviceRes (SHORT) 
    X-device resolution. 

    For bit-map fonts this is the resolution in the X direction of the intended 
    target device, measured in pels per inch. 

    For outline fonts this is the number of notional units in the X direction 
    of the Em square, measured in notional units per Em. (Notional units are 
    the units in which the outline is defined.) 


═══ <hidden> FONTMETRICS Field - sYDeviceRes ═══

 sYDeviceRes (SHORT) 
    Y-device resolution. 

    For bit-map fonts this is the resolution in the Y direction of the intended 
    target device, measured in pels per inch. 

    For outline fonts this is the number of notional units in the Y direction 
    of the Em square, measured in notional units per Em. (Notional units are 
    the units in which the outline is defined.) 


═══ <hidden> FONTMETRICS Field - sFirstChar ═══

 sFirstChar (SHORT) 
    First character. 

    The code point of the first character in the font. 


═══ <hidden> FONTMETRICS Field - sLastChar ═══

 sLastChar (SHORT) 
    Last character. 

    The code point of the last character in the font, expressed as an offset 
    from sFirstChar. 

    All code points between the first and last character specified must be 
    supported by the font. 


═══ <hidden> FONTMETRICS Field - sDefaultChar ═══

 sDefaultChar (SHORT) 
    Default character. 

    The code point that is used if a code point outside the range supported by 
    the font is used, expressed as an offset from sFirstChar. 


═══ <hidden> FONTMETRICS Field - sBreakChar ═══

 sBreakChar (SHORT) 
    Break character. 

    The code point that represents the "space" or "break" character for this 
    font, expressed as an offset from sFirstChar. For example, if the first 
    character is the space in code page 850, sFirstChar = 32, and sBreakChar = 
    0. 


═══ <hidden> FONTMETRICS Field - sNominalPointSize ═══

 sNominalPointSize (SHORT) 
    Nominal point size. 

    For a bit-map font, this field contains the height of the font. 

    For an outline font, this field contains the height intended by the font 
    designer. For example, some fonts are designed for text use in which case a 
    value of 120 (12 point) would probably be placed in this field, whereas 
    other fonts are designed for "display" use ("display" is typographer's 
    terminology for larger sizes). This is not the only size at which the font 
    can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FONTMETRICS Field - sMinimumPointSize ═══

 sMinimumPointSize (SHORT) 
    Minimum point size. 

    For a bit-map font, this field does not apply. For an outline font, this 
    field contains the minimum height intended by the font designer. Note that 
    this is not a restriction of the size at which the font can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FONTMETRICS Field - sMaximumPointSize ═══

 sMaximumPointSize (SHORT) 
    Maximum point size. 

    For a bit-map font, this field does not apply. 

    For an outline font, this field contains the maximum height intended by the 
    font designer. Note that this is not a restriction of the size at which the 
    font can be used. 

    Measured in decipoints (a decipoint is 1/720th of an inch). 


═══ <hidden> FONTMETRICS Field - fsType ═══

 fsType (USHORT) 
    Type indicators. 

    This field contains the following information: 

    FM_TYPE_FIXED                 Characters in the font have the same fixed 
                                  width. 

    FM_TYPE_LICENSED              Licensed (protected) font. 

    FM_TYPE_KERNING               Font contains kerning information. 

    FM_TYPE_64K                   Font is larger than 64KB (KB equals 1024 
                                  bytes) in size. If the following two bits are 
                                  false, the font is for single-byte code 
                                  pages. One of the bits may be set. 

    FM_TYPE_DBCS                  Font is for double-byte code pages. 

    FM_TYPE_MBCS                  Font is for mixed single- or double-byte code 
                                  pages. 

    FM_TYPE_FACETRUNC 
            Font szFacename has been truncated. 
    FM_TYPE_FAMTRUNC 
            Font szFamilyname has been truncated. 
    FM_TYPE_ATOMS 
            The System Atom table atom values in FamilyNameAtom and in 
            FaceNameAtom are valid. 


═══ <hidden> FONTMETRICS Field - fsDefn ═══

 fsDefn (USHORT) 
    Definition indicators. 

    Contains the following font definition data: 

    FM_DEFN_OUTLINE               Font is a vector (outline) font; otherwise, 
                                  it is a bit-map font. 

    FM_DEFN_GENERIC               Font is in a format that can be used by the 
                                  GPI; otherwise, it is a device font. 


═══ <hidden> FONTMETRICS Field - fsSelection ═══

 fsSelection (USHORT) 
    Selection indicators. 

    Contains information about the font patterns in the physical font. 

    Note:  The flags do not reflect simulations applied to the physical font. 

    Possible values are: 

    FM_SEL_ITALIC                 True indicates that this font is designed as 
                                  an italic font. 

    FM_SEL_UNDERSCORE             TRUE indicates that this font is designed 
                                  with underscores included in each character. 

    FM_SEL_NEGATIVE               TRUE indicates that this font is designed 
                                  with the background and foreground reversed. 

    FM_SEL_OUTLINE                TRUE indicates that this font is designed 
                                  with outline (hollow) characters. 

    FM_SEL_STRIKEOUT              TRUE indicates that this font is designed 
                                  with an overstrike through each character. 

    FM_SEL_BOLD                   TRUE indicates that this font is designed 
                                  with bold characters. 

    FM_SEL_ISO9241_TESTED         This flag indicates that the font has been 
                                  tested for compliance to ISO 9241. The 
                                  presence of this flag doesn't indicate 
                                  whether the font passed or failed, only that 
                                  it was tested. 

                                  Note:  While the fonts were primarily tested 
                                         for meeting the ISO standard, they 
                                         have also been designed to meet the 
                                         German standard DIN 66 234. Where the 
                                         two standards differ, the fonts have 
                                         been designed to meet the more 
                                         stringent requirement. 


═══ <hidden> FONTMETRICS Field - fsCapabilities ═══

 fsCapabilities (USHORT) 
    Font capabilities. 

    This attribute applies only to device fonts. 

    FM_CAP_NOMIX                  Characters may not be mixed with graphics. 

    QUALITY                       The most significant byte may contain the 
                                  following numeric value: 

                                  0        Undefined 
                                  1        DP quality 
                                  2        DP draft 
                                  3        Near Letter Quality 
                                  4        Letter Quality 


═══ <hidden> FONTMETRICS Field - lSubscriptXSize ═══

 lSubscriptXSize (LONG) 
    Subscript x-size. 

    The horizontal size recommended by the font designer for subscripts for 
    this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSubscriptYSize ═══

 lSubscriptYSize (LONG) 
    Subscript y-size. 

    The vertical size recommended by the font designer for subscripts for this 
    font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSubscriptXOffset ═══

 lSubscriptXOffset (LONG) 
    Subscript x-offset. 

    The baseline x-offset recommended by the font designer for subscripts for 
    this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSubscriptYOffset ═══

 lSubscriptYOffset (LONG) 
    Subscript y-offset. 

    The baseline y-offset recommended by the font designer for subscripts for 
    this font in world coordinate units. 

    Note:  Positive numbers indicate an offset below the baseline. 


═══ <hidden> FONTMETRICS Field - lSuperscriptXSize ═══

 lSuperscriptXSize (LONG) 
    Superscript x-size. 

    The horizontal size recommended by the font designer for superscripts for 
    this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSuperscriptYSize ═══

 lSuperscriptYSize (LONG) 
    Superscript y-size. 

    The vertical point size recommended by the font designer for superscripts 
    for this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSuperscriptXOffset ═══

 lSuperscriptXOffset (LONG) 
    Superscript x-offset. 

    The baseline x-offset recommended by the font designer for superscripts for 
    this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lSuperscriptYOffset ═══

 lSuperscriptYOffset (LONG) 
    Superscript y-offset. 

    The baseline y-offset recommended by the font designer for superscripts for 
    this font in world coordinate units. 


═══ <hidden> FONTMETRICS Field - lUnderscoreSize ═══

 lUnderscoreSize (LONG) 
    Underscore size. 

    The width (thickness) of the underscore stroke in world coordinate units. 
    This describes the actual underscore in the font if FM_SEL_UNDERSCORE is 
    also set. Otherwise it describes what the engine will simulate if 
    underscore is requested in GpiCreateLogFont. 


═══ <hidden> FONTMETRICS Field - lUnderscorePosition ═══

 lUnderscorePosition (LONG) 
    Underscore position. 

    The position of the underscore stroke from the baseline in world coordinate 
    units. This describes the actual underscore in the font if 
    FM_SEL_UNDERSCORE is also set. Otherwise it describes what the engine will 
    simulate if underscore is requested in GpiCreateLogFont. 

    Note:  Positive values indicate an offset below the baseline. 


═══ <hidden> FONTMETRICS Field - lStrikeoutSize ═══

 lStrikeoutSize (LONG) 
    Strikeout size. 

    The width of the strikeout stroke in world coordinate units. This describes 
    the actual underscore in the font if FM_SEL_STRIKEOUT is also set. 
    Otherwise it describes what the engine will simulate if overstrike is 
    requested in GpiCreateLogFont. 


═══ <hidden> FONTMETRICS Field - lStrikeoutPosition ═══

 lStrikeoutPosition (LONG) 
    Strikeout position. 

    The position of the strikeout stroke relative to the baseline in world 
    coordinate units. This describes the actual underscore in the font if 
    FM_SEL_STRIKEOUT is also set. Otherwise it describes what the engine will 
    simulate if overstrike is requested in GpiCreateLogFont. 


═══ <hidden> FONTMETRICS Field - sKerningPairs ═══

 sKerningPairs (SHORT) 
    Kerning pairs. 

    The number of kerning pairs in the kerning pair table. 


═══ <hidden> FONTMETRICS Field - sFamilyClass ═══

 sFamilyClass (SHORT) 
    Font family design classification. 

    This value contains a font class and its subclass. 


═══ <hidden> FONTMETRICS Field - lMatch ═══

 lMatch (LONG) 
    Matched font identity. 

    This uniquely identifies the font for a given device and device driver 
    combination. A positive match number signifies that the font is a generic 
    (engine) font while a negative number indicates a device font (a native or 
    downloadable font). This value should not be used to identify a font across 
    system boundaries. 


═══ <hidden> FONTMETRICS Field - FamilyNameAtom ═══

 FamilyNameAtom (LONG) 
    Font family name atom. 

    This value contains the atom identifier for the font family name in the 
    System Atom Table. 


═══ <hidden> FONTMETRICS Field - FaceNameAtom ═══

 FaceNameAtom (LONG) 
    Font facename atom. 

    This value contains the atom identifier for the font face name in the 
    System Atom Table. 


═══ <hidden> FONTMETRICS Field - panose ═══

 panose (PANOSE) 
    Panose font descriptor. 

    This is the Panose descriptor identifying the visual characteristics of the 
    font. 


═══ 1.25. GRADIENTL ═══

Direction-vector structure. 

typedef struct _GRADIENTL {
  LONG     x;  /*  X-component of direction. */
  LONG     y;  /*  Y-component of direction. */
} GRADIENTL;

typedef GRADIENTL *PGRADIENTL;


═══ <hidden> GRADIENTL Field - x ═══

 x (LONG) 
    X-component of direction. 


═══ <hidden> GRADIENTL Field - y ═══

 y (LONG) 
    Y-component of direction. 


═══ 1.26. HAB ═══

Anchor-block handle. 

typedef LHANDLE HAB;


═══ 1.27. HBITMAP ═══

Bit-map handle. 

typedef LHANDLE HBITMAP;


═══ 1.28. HCINFO ═══

Hardcopy-capabilities structure. 

typedef struct _HCINFO {
  CHAR     szFormname[32];  /*  Form name. */
  LONG     cx;              /*  Width (left-to-right) in millimeters. */
  LONG     cy;              /*  Height (top-to-bottom) in millimeters. */
  LONG     xLeftClip;       /*  Left-clip limit in millimeters. */
  LONG     yBottomClip;     /*  Bottom-clip limit in millimeters. */
  LONG     xRightClip;      /*  Right-clip limit in millimeters. */
  LONG     yTopClip;        /*  Top-clip limit in millimeters. */
  LONG     xPels;           /*  Number of pels between left-clip and right-clip limits. */
  LONG     yPels;           /*  Number of pels between bottom-clip and top-clip limits. */
  LONG     flAttributes;    /*  Attributes of the form identifier. */
} HCINFO;

typedef HCINFO *PHCINFO;


═══ <hidden> HCINFO Field - szFormname[32] ═══

 szFormname[32] (CHAR) 
    Form name. 


═══ <hidden> HCINFO Field - cx ═══

 cx (LONG) 
    Width (left-to-right) in millimeters. 


═══ <hidden> HCINFO Field - cy ═══

 cy (LONG) 
    Height (top-to-bottom) in millimeters. 


═══ <hidden> HCINFO Field - xLeftClip ═══

 xLeftClip (LONG) 
    Left-clip limit in millimeters. 


═══ <hidden> HCINFO Field - yBottomClip ═══

 yBottomClip (LONG) 
    Bottom-clip limit in millimeters. 


═══ <hidden> HCINFO Field - xRightClip ═══

 xRightClip (LONG) 
    Right-clip limit in millimeters. 


═══ <hidden> HCINFO Field - yTopClip ═══

 yTopClip (LONG) 
    Top-clip limit in millimeters. 


═══ <hidden> HCINFO Field - xPels ═══

 xPels (LONG) 
    Number of pels between left-clip and right-clip limits. 


═══ <hidden> HCINFO Field - yPels ═══

 yPels (LONG) 
    Number of pels between bottom-clip and top-clip limits. 


═══ <hidden> HCINFO Field - flAttributes ═══

 flAttributes (LONG) 
    Attributes of the form identifier. 

    HCAPS_SELECTABLE 
                             The form is installed on the printer as given by 
                             the printer properties dialog. It is available 
                             from an alternate form source without operator 
                             intervention. If the form does not have this bit 
                             set and is used (if the user selects it), a "forms 
                             mismatch" error is generated by the printer 
                             object. 

    HCAPS_CURRENT 
                             The form is the one currently selected by the 
                             DevOpenDC DEVOPENSTRUC pdriv field (the job 
                             properties). 


═══ 1.29. HDC ═══

Device-context handle. 

typedef LHANDLE HDC;


═══ 1.30. HMF ═══

Metafile handle. 

typedef LHANDLE HMF;


═══ 1.31. HMODULE ═══

Module handle. 

typedef LHANDLE HMODULE;


═══ 1.32. HPAL ═══

Palette handle. 

typedef LHANDLE HPAL;


═══ 1.33. HPS ═══

Presentation-space handle. 

typedef LHANDLE HPS;


═══ 1.34. HRGN ═══

Region handle. 

typedef LHANDLE HRGN;


═══ 1.35. IMAGEBUNDLE ═══

Image-attributes bundle structure. 

typedef struct _IMAGEBUNDLE {
  LONG       lColor;         /*  Image foreground color. */
  LONG       lBackColor;     /*  Image background color. */
  USHORT     usMixMode;      /*  Image foreground-mix mode. */
  USHORT     usBackMixMode;  /*  Image background-mix mode. */
} IMAGEBUNDLE;

typedef IMAGEBUNDLE *PIMAGEBUNDLE;


═══ <hidden> IMAGEBUNDLE Field - lColor ═══

 lColor (LONG) 
    Image foreground color. 


═══ <hidden> IMAGEBUNDLE Field - lBackColor ═══

 lBackColor (LONG) 
    Image background color. 


═══ <hidden> IMAGEBUNDLE Field - usMixMode ═══

 usMixMode (USHORT) 
    Image foreground-mix mode. 


═══ <hidden> IMAGEBUNDLE Field - usBackMixMode ═══

 usBackMixMode (USHORT) 
    Image background-mix mode. 


═══ 1.36. KERNINGPAIRS ═══

[Need description.] 

typedef struct _KERNINGPAIRS {
  SHORT     sFirstChar;      /*  [Need definition.] */
  SHORT     sSecondChar;     /*  [Need definition.] */
  LONG      lKerningAmount;  /*  [Need definition.] */
} KERNINGPAIRS;

typedef KERNINGPAIRS *PKERNINGPAIRS;


═══ <hidden> KERNINGPAIRS Field - sFirstChar ═══

 sFirstChar (SHORT) 
    [Need definition.] 


═══ <hidden> KERNINGPAIRS Field - sSecondChar ═══

 sSecondChar (SHORT) 
    [Need definition.] 


═══ <hidden> KERNINGPAIRS Field - lKerningAmount ═══

 lKerningAmount (LONG) 
    [Need definition.] 


═══ 1.37. LINEBUNDLE ═══

Line-attributes bundle structure. 

typedef struct _LINEBUNDLE {
  LONG       lColor;         /*  Line foreground color. */
  LONG       lBackColor;     /*  Line background color. */
  USHORT     usMixMode;      /*  Line foreground-mix mode. */
  USHORT     usBackMixMode;  /*  Line background-mix mode. */
  FIXED      fxWidth;        /*  Line width. */
  LONG       lGeomWidth;     /*  Geometric line width. */
  USHORT     usType;         /*  Line type. */
  USHORT     usEnd;          /*  Line end. */
  USHORT     usJoin;         /*  Line join. */
  USHORT     usReserved;     /*  Reserved. */
} LINEBUNDLE;

typedef LINEBUNDLE *PLINEBUNDLE;


═══ <hidden> LINEBUNDLE Field - lColor ═══

 lColor (LONG) 
    Line foreground color. 


═══ <hidden> LINEBUNDLE Field - lBackColor ═══

 lBackColor (LONG) 
    Line background color. 


═══ <hidden> LINEBUNDLE Field - usMixMode ═══

 usMixMode (USHORT) 
    Line foreground-mix mode. 


═══ <hidden> LINEBUNDLE Field - usBackMixMode ═══

 usBackMixMode (USHORT) 
    Line background-mix mode. 


═══ <hidden> LINEBUNDLE Field - fxWidth ═══

 fxWidth (FIXED) 
    Line width. 


═══ <hidden> LINEBUNDLE Field - lGeomWidth ═══

 lGeomWidth (LONG) 
    Geometric line width. 


═══ <hidden> LINEBUNDLE Field - usType ═══

 usType (USHORT) 
    Line type. 


═══ <hidden> LINEBUNDLE Field - usEnd ═══

 usEnd (USHORT) 
    Line end. 


═══ <hidden> LINEBUNDLE Field - usJoin ═══

 usJoin (USHORT) 
    Line join. 


═══ <hidden> LINEBUNDLE Field - usReserved ═══

 usReserved (USHORT) 
    Reserved. 


═══ 1.38. LONG ═══

Signed integer in the range -2 147 483 648 through 2 147 483 647. 

#define LONG long

Note:  Where this data type represents a graphic coordinate in world or model 
       space, its value is restricted to -134 217 728 through 134 217 727. 

A graphic coordinate in device or screen coordinates is restricted to -32 768 
through 32 767. 

The value of a graphic coordinate may be further restricted by any transforms 
currently in force, including the positioning of the origin of the window on 
the screen. In particular, coordinates in world or model space must not 
generate coordinate values after transformation (that is, in device or screen 
space) outside the range -32 768 through 32 767. 


═══ 1.39. MARKERBUNDLE ═══

Marker-attributes bundle structure. 

typedef struct _MARKERBUNDLE {
  LONG       lColor;         /*  Marker foreground color. */
  LONG       lBackColor;     /*  Marker background color. */
  USHORT     usMixMode;      /*  Marker foreground-mix mode. */
  USHORT     usBackMixMode;  /*  Marker background-mix mode. */
  USHORT     usSet;          /*  Marker set. */
  USHORT     usSymbol;       /*  Marker symbol. */
  SIZEF      sizfxCell;      /*  Marker cell. */
} MARKERBUNDLE;

typedef MARKERBUNDLE *PMARKERBUNDLE;


═══ <hidden> MARKERBUNDLE Field - lColor ═══

 lColor (LONG) 
    Marker foreground color. 


═══ <hidden> MARKERBUNDLE Field - lBackColor ═══

 lBackColor (LONG) 
    Marker background color. 


═══ <hidden> MARKERBUNDLE Field - usMixMode ═══

 usMixMode (USHORT) 
    Marker foreground-mix mode. 


═══ <hidden> MARKERBUNDLE Field - usBackMixMode ═══

 usBackMixMode (USHORT) 
    Marker background-mix mode. 


═══ <hidden> MARKERBUNDLE Field - usSet ═══

 usSet (USHORT) 
    Marker set. 


═══ <hidden> MARKERBUNDLE Field - usSymbol ═══

 usSymbol (USHORT) 
    Marker symbol. 


═══ <hidden> MARKERBUNDLE Field - sizfxCell ═══

 sizfxCell (SIZEF) 
    Marker cell. 


═══ 1.40. MATRIXLF ═══

Matrix-elements structure. 

typedef struct _MATRIXLF {
  FIXED     fxM11;  /*  First element of first row. */
  FIXED     fxM12;  /*  Second element of first row. */
  LONG      lM13;   /*  Third element of first row. */
  FIXED     fxM21;  /*  First element of second row. */
  FIXED     fxM22;  /*  Second element of second row. */
  LONG      lM23;   /*  Third element of second row. */
  LONG      lM31;   /*  First element of third row. */
  LONG      lM32;   /*  Second element of third row. */
  LONG      lM33;   /*  Third element of third row. */
} MATRIXLF;

typedef MATRIXLF *PMATRIXLF;


═══ <hidden> MATRIXLF Field - fxM11 ═══

 fxM11 (FIXED) 
    First element of first row. 


═══ <hidden> MATRIXLF Field - fxM12 ═══

 fxM12 (FIXED) 
    Second element of first row. 


═══ <hidden> MATRIXLF Field - lM13 ═══

 lM13 (LONG) 
    Third element of first row. 


═══ <hidden> MATRIXLF Field - fxM21 ═══

 fxM21 (FIXED) 
    First element of second row. 


═══ <hidden> MATRIXLF Field - fxM22 ═══

 fxM22 (FIXED) 
    Second element of second row. 


═══ <hidden> MATRIXLF Field - lM23 ═══

 lM23 (LONG) 
    Third element of second row. 


═══ <hidden> MATRIXLF Field - lM31 ═══

 lM31 (LONG) 
    First element of third row. 


═══ <hidden> MATRIXLF Field - lM32 ═══

 lM32 (LONG) 
    Second element of third row. 


═══ <hidden> MATRIXLF Field - lM33 ═══

 lM33 (LONG) 
    Third element of third row. 


═══ 1.41. MPARAM ═══

A 4-byte message-dependent parameter structure. 

typedef VOID *MPARAM;

Certain elements of information, placed into the parameters of a message, have 
data types that do not use all four bytes of this data type. The rules 
governing these cases are: 

 BOOL      The value is contained in the low word and the high word is 0. 
 SHORT     The value is contained in the low word and its sign is extended into 
           the high word. 
 USHORT    The value is contained in the low word and the high word is 0. 
 NULL      The entire four bytes are 0. 

 The structure of this data type depends on the message. For details, see the 
 description of the particular message. 


═══ 1.42. MRESULT ═══

A 4-byte message-dependent reply parameter structure. 

typedef VOID *MRESULT;

Certain elements of information, placed into the parameters of a message, have 
data types that do not use all four bytes of this data type. The rules 
governing these cases are: 

 BOOL      The value is contained in the low word and the high word is 0. 
 SHORT     The value is contained in the low word and its sign is extended into 
           the high word. 
 USHORT    The value is contained in the low word and the high word is 0. 
 NULL      The entire four bytes are 0. 

 The structure of this data type depends on the message. For details, see the 
 description of the particular message. 


═══ 1.43. PANOSE ═══

The Panose field in the font metrics will allow for quantitative descriptions 
of the visual properties of font faces. The PANOSE definition contains ten 
digits, each of which currently describes up to sixteen variations. 

typedef struct _PANOSE {
  BYTE     bFamilyType;       /*  Family kind. */
  BYTE     bSerifStyle;       /*  Serif style. */
  BYTE     bWeight;           /*  Weight. */
  BYTE     bProportion;       /*  Proportion. */
  BYTE     bContrast;         /*  Contrast. */
  BYTE     bStrokeVariation;  /*  Stroke Variation. */
  BYTE     bArmStyle;         /*  Arm Style. */
  BYTE     bLetterform;       /*  Letterform. */
  BYTE     bMidline;          /*  Midline. */
  BYTE     bXHeight;          /*  X-Height. */
  BYTE     fbPassedISO;       /*  Font passed ISO test. */
  BYTE     fbFailedISO;       /*  Font failed ISO test. */
} PANOSE;

typedef PANOSE *PPANOSE;


═══ <hidden> PANOSE Field - bFamilyType ═══

 bFamilyType (BYTE) 
    Family kind. 

    0         Any 
    1         No Fit 
    2         Text and Display 
    3         Script 
    4         Decorative 
    5         Pictorial 


═══ <hidden> PANOSE Field - bSerifStyle ═══

 bSerifStyle (BYTE) 
    Serif style. 

    0         Any 
    1         No Fit 
    2         Cove 
    3         Obtuse Cove 
    4         Square Cove 
    5         Obtuse Square Cove 
    6         Square 
    7         Thin 
    8         Bone 
    9         Exaggerated 
    10        Triangle 
    11        Normal Sans 
    12        Obtuse Sans 
    13        Perp Sans 
    14        Flared 
    15        Rounded 


═══ <hidden> PANOSE Field - bWeight ═══

 bWeight (BYTE) 
    Weight. 

    0         Any 
    1         No Fit 
    2         Very Light 
    3         Light 
    4         Thin 
    5         Book 
    6         Medium 
    7         Demi 
    8         Bold 
    9         Heavy 
    10        Black 
    11        Nord 


═══ <hidden> PANOSE Field - bProportion ═══

 bProportion (BYTE) 
    Proportion. 

    0         Any 
    1         No Fit 
    2         Old Style 
    3         Modern 
    4         Even Width 
    5         Expanded 
    6         Condensed 
    7         Very Expanded 
    8         Very Condensed 
    9         Monospaced 


═══ <hidden> PANOSE Field - bContrast ═══

 bContrast (BYTE) 
    Contrast. 

    0         Any 
    1         No Fit 
    2         None 
    3         Very Low 
    4         Low 
    5         Medium Low 
    6         Medium 
    7         Medium High 
    8         High 
    9         Very High 


═══ <hidden> PANOSE Field - bStrokeVariation ═══

 bStrokeVariation (BYTE) 
    Stroke Variation. 

    0         Any 
    1         No Fit 
    2         Gradual/Diagonal 
    3         Gradual/Transitional 
    4         Gradual/Vertical 
    5         Gradual/Horizontal 
    6         Rapid/Vertical 
    7         Rapid/Horizontal 
    8         Instant/Vertical 


═══ <hidden> PANOSE Field - bArmStyle ═══

 bArmStyle (BYTE) 
    Arm Style. 

    0         Any 
    1         No Fit 
    2         Straight Arms/Horizontal 
    3         Straight Arms/Wedge 
    4         Straight Arms/Vertical 
    5         Straight Arms/Single Serif 
    6         Straight Arms/Double Serif 
    7         Non-Straight Arms/Horizontal 
    8         Non-Straight Arms/Wedge 
    9         Non-Straight Arms/Vertical 
    10        Non-Straight Arms/Single Serif 
    11        Non-Straight Arms/Double Serif 


═══ <hidden> PANOSE Field - bLetterform ═══

 bLetterform (BYTE) 
    Letterform. 

    0         Any 
    1         No Fit 
    2         Normal/Contact 
    3         ONormal/Weighted 
    4         ONormal/Boxed 
    5         ONormal/Flattened 
    6         ONormal/Rounded 
    7         ONormal/Off Center 
    8         ONormal/Square 
    9         Oblique/Contact 
    10        Oblique/Weighted 
    11        Oblique/Boxed 
    12        Oblique/Flattened 
    13        Oblique/Rounded 
    14        Oblique/Off Center 
    15        Oblique/Square 


═══ <hidden> PANOSE Field - bMidline ═══

 bMidline (BYTE) 
    Midline. 

    0         Any 
    1         No Fit 
    2         Standard/Trimmed 
    3         Standard/Pointed 
    4         Standard/Serifed 
    5         High/Trimmed 
    6         High/Pointed 
    7         High/Serifed 
    8         Constant/Trimmed 
    9         Constant/Pointed 
    10        Constant/Serifed 
    11        Low/Trimmed 
    12        Low/Pointed 
    13        Low/Serifed 


═══ <hidden> PANOSE Field - bXHeight ═══

 bXHeight (BYTE) 
    X-Height. 

    0         Any 
    1         No Fit 
    2         Constant/Small 
    3         Constant/Standard 
    4         Constant/Large 
    5         Ducking/Small 
    6         Ducking/Standard 
    7         Ducking/Large 


═══ <hidden> PANOSE Field - fbPassedISO ═══

 fbPassedISO (BYTE) 
    Font passed ISO test. 

    The following flags indicate those displays and resolutions at which the 
    font complied with ISO 9241: 

    FM_ISO_9518_640 
    FM_ISO_9515_640 
    FM_ISO_9515_1024 
    FM_ISO_9517_640 
    FM_ISO_9517_1024 


═══ <hidden> PANOSE Field - fbFailedISO ═══

 fbFailedISO (BYTE) 
    Font failed ISO test. 

    The following flags indicate those displays and resolutions at which the 
    font did not comply with ISO 9241: 

    FM_ISO_9518_640 
    FM_ISO_9515_640 
    FM_ISO_9515_1024 
    FM_ISO_9517_640 
    FM_ISO_9517_1024 


═══ 1.44. PBUNDLE ═══

Points to a bundle data area. 

typedef PVOID PBUNDLE;


═══ 1.45. PCH ═══

Pointer to a character string. 

typedef unsigned char *PCH;


═══ 1.46. POLYGON ═══

Polygon structure. 

typedef struct _POLYGON {
  ULONG       ulPoints;  /*  Number of points in array. */
  PPOINTL     aPointl;   /*  Array of points. */
} POLYGON;

typedef POLYGON *PPOLYGON;


═══ <hidden> POLYGON Field - ulPoints ═══

 ulPoints (ULONG) 
    Number of points in array. 


═══ <hidden> POLYGON Field - aPointl ═══

 aPointl (PPOINTL) 
    Array of points. 


═══ 1.47. POINTL ═══

Point structure (long integers). 

typedef struct _POINTL {
  LONG     x;  /*  X-coordinate. */
  LONG     y;  /*  Y-coordinate. */
} POINTL;

typedef POINTL *PPOINTL;


═══ <hidden> POINTL Field - x ═══

 x (LONG) 
    X-coordinate. 


═══ <hidden> POINTL Field - y ═══

 y (LONG) 
    Y-coordinate. 


═══ 1.48. PCSZ ═══

Pointer to a constant null-terminated string. 

typedef const char *PCSZ;


═══ 1.49. PSZ ═══

Pointer to a null-terminated string. 

If you are using C++ **, you may need to use PCSZ. 

typedef unsigned char *PSZ;


═══ 1.50. PRQINFO3 ═══

Print-queue information structure. 

This structure is used at information levels 3 and 4. 

typedef struct _PRQINFO3 {
  PSZ           pszName;        /*  Queue name. */
  USHORT        uPriority;      /*  Queue priority. */
  USHORT        uStartTime;     /*  Minutes after midnight when queue becomes active. */
  USHORT        uUntilTime;     /*  Minutes after midnight. when queue ceases to be active. */
  USHORT        fsType;         /*  Queue type. */
  PSZ           pszSepFile;     /*  Separator-page file. */
  PSZ           pszPrProc;      /*  Default queue-processor. */
  PSZ           pszParms;       /*  Queue parameters. */
  PSZ           pszComment;     /*  Queue description. */
  USHORT        fsStatus;       /*  Queue status. */
  USHORT        cJobs;          /*  Number of jobs in queue. */
  PSZ           pszPrinters;    /*  Print devices connected to queue. */
  PSZ           pszDriverName;  /*  Default device driver. */
  PDRIVDATA     pDriverData;    /*  Default queue job properties. */
} PRQINFO3;

typedef PRQINFO3 *PPRQINFO3;


═══ <hidden> PRQINFO3 Field - pszName ═══

 pszName (PSZ) 
    Queue name. 

    The maximum length of the name in the network case is 256 (including one 
    byte for zero termination). 


═══ <hidden> PRQINFO3 Field - uPriority ═══

 uPriority (USHORT) 
    Queue priority. 

    The range is 1 through 9, with 1 being the highest queue priority. 

    The default job priority (DefJobPrio) is determined from: 
    DefJobPrio=100-(10* uPriority). 

    If a job is added with PRJ_NO_PRIORITY specified, DefJobPrio is used. If a 
    default priority higher than the default job priority is specified, the 
    default job priority is used. If a default priority lower than the default 
    is specified, the specified job priority is used. 

    PRQ_DEF_PRIORITY 
            Default priority 
    PRQ_MAX_PRIORITY 
            Highest priority 
    PRQ_MIN_PRIORITY 
            Minimum priority 
    PRQ_NO_PRIORITY 
            No priority. 


═══ <hidden> PRQINFO3 Field - uStartTime ═══

 uStartTime (USHORT) 
    Minutes after midnight when queue becomes active. 

    For example, the value 75 represents 1:15 a.m. 

    If uStartTime and uUntilTime are both 0, the print queue is always 
    available. 


═══ <hidden> PRQINFO3 Field - uUntilTime ═══

 uUntilTime (USHORT) 
    Minutes after midnight. when queue ceases to be active. 

    For example, the value 1200 represents 8 p.m. 

    If uUntilTime and uStartTime are both 0, the print queue is always 
    available. 


═══ <hidden> PRQINFO3 Field - fsType ═══

 fsType (USHORT) 
    Queue type. 

    PRQ3_TYPE_RAW 
            Data is always enqueued in the device specific format. 
    PRQ3_TYPE_BYPASS 
            Allows the spooler to bypass the queue processor and send data 
            directly to the Printer Driver. Setting this bit allows the spooler 
            to print jobs of type PM_Q_RAW while they are still being spooled. 
    PRQ3_TYPE_APPDEFAULT 
            This bit is set for the application default queue only. 


═══ <hidden> PRQINFO3 Field - pszSepFile ═══

 pszSepFile (PSZ) 
    Separator-page file. 

    The path and file name of a separator-page file on the target computer. 

    This file contains formatting information for the page or pages to be used 
    between print jobs. A relative path name is taken as relative to the 
    current spool directory. A NULL string indicates no separator page. 


═══ <hidden> PRQINFO3 Field - pszPrProc ═══

 pszPrProc (PSZ) 
    Default queue-processor. 


═══ <hidden> PRQINFO3 Field - pszParms ═══

 pszParms (PSZ) 
    Queue parameters. 

    This can be any text string or a NULL string. 


═══ <hidden> PRQINFO3 Field - pszComment ═══

 pszComment (PSZ) 
    Queue description. 

    A NULL string results in no comment. The maximum length is 48 characters 
    (including one byte for the null terminator). 


═══ <hidden> PRQINFO3 Field - fsStatus ═══

 fsStatus (USHORT) 
    Queue status. 

    PRQ3_PAUSED 
            Queue is paused (held). 
    PRQ3_PENDING 
            Queue is pending deletion. 


═══ <hidden> PRQINFO3 Field - cJobs ═══

 cJobs (USHORT) 
    Number of jobs in queue. 


═══ <hidden> PRQINFO3 Field - pszPrinters ═══

 pszPrinters (PSZ) 
    Print devices connected to queue. 

    This cannot be NULL. 


═══ <hidden> PRQINFO3 Field - pszDriverName ═══

 pszDriverName (PSZ) 
    Default device driver. 


═══ <hidden> PRQINFO3 Field - pDriverData ═══

 pDriverData (PDRIVDATA) 
    Default queue job properties. 

    Note:  An application can use pszDriverName, pDriverData, pszPrProc, and 
           pszParms to construct a valid DevOpenDC call based only on the queue 
           name. 


═══ 1.51. PVOID ═══

Pointer to a data type of undefined format. 

typedef VOID *PVOID;


═══ 1.52. RECTL ═══

Rectangle structure. 

typedef struct _RECTL {
  LONG     xLeft;    /*  X-coordinate of left-hand edge of rectangle. */
  LONG     yBottom;  /*  Y-coordinate of bottom edge of rectangle. */
  LONG     xRight;   /*  X-coordinate of right-hand edge of rectangle. */
  LONG     yTop;     /*  Y-coordinate of top edge of rectangle. */
} RECTL;

typedef RECTL *PRECTL;


═══ <hidden> RECTL Field - xLeft ═══

 xLeft (LONG) 
    X-coordinate of left-hand edge of rectangle. 


═══ <hidden> RECTL Field - yBottom ═══

 yBottom (LONG) 
    Y-coordinate of bottom edge of rectangle. 


═══ <hidden> RECTL Field - xRight ═══

 xRight (LONG) 
    X-coordinate of right-hand edge of rectangle. 


═══ <hidden> RECTL Field - yTop ═══

 yTop (LONG) 
    Y-coordinate of top edge of rectangle. 


═══ 1.53. RGNRECT ═══

Region-rectangle structure. 

typedef struct _RGNRECT {
  ULONG     ircStart;     /*  Rectangle number from which to start enumerating. */
  ULONG     crc;          /*  Number of rectangles that can be returned. */
  ULONG     crcReturned;  /*  Number of rectangles returned. */
  ULONG     ulDirection;  /*  Direction in which the returned rectangles are to be ordered. */
} RGNRECT;

typedef RGNRECT *PRGNRECT;


═══ <hidden> RGNRECT Field - ircStart ═══

 ircStart (ULONG) 
    Rectangle number from which to start enumerating. 

    Numbering starts from 1. 


═══ <hidden> RGNRECT Field - crc ═══

 crc (ULONG) 
    Number of rectangles that can be returned. 

    This must be 1 or greater. 


═══ <hidden> RGNRECT Field - crcReturned ═══

 crcReturned (ULONG) 
    Number of rectangles returned. 

    A value of less than crc indicates that there are no more rectangles to 
    enumerate. 


═══ <hidden> RGNRECT Field - ulDirection ═══

 ulDirection (ULONG) 
    Direction in which the returned rectangles are to be ordered. 

    This ordering uses the leading edge of a rectangle: 

    RECTDIR_LFRT_TOPBOT           Left-to-right, top-to-bottom 

    RECTDIR_RTLF_TOPBOT           Right-to-left, top-to-bottom 

    RECTDIR_LFRT_BOTTOP           Left-to-right, bottom-to-top 

    RECTDIR_RTLF_BOTTOP           Right-to-left, bottom-to-top 


═══ 1.54. RGB ═══

RGB color value. 

typedef struct _RGB {
  BYTE     bBlue;   /*  Blue component of the color definition. */
  BYTE     bGreen;  /*  Green component of the color definition. */
  BYTE     bRed;    /*  Red component of the color definition. */
} RGB;

typedef RGB *PRGB;


═══ <hidden> RGB Field - bBlue ═══

 bBlue (BYTE) 
    Blue component of the color definition. 


═══ <hidden> RGB Field - bGreen ═══

 bGreen (BYTE) 
    Green component of the color definition. 


═══ <hidden> RGB Field - bRed ═══

 bRed (BYTE) 
    Red component of the color definition. 


═══ 1.55. RGB2 ═══

RGB color value. 

typedef struct _RGB2 {
  BYTE     bBlue;      /*  Blue component of the color definition. */
  BYTE     bGreen;     /*  Green component of the color definition. */
  BYTE     bRed;       /*  Red component of the color definition. */
  BYTE     fcOptions;  /*  Entry options. */
} RGB2;

typedef RGB2 *PRGB2;


═══ <hidden> RGB2 Field - bBlue ═══

 bBlue (BYTE) 
    Blue component of the color definition. 


═══ <hidden> RGB2 Field - bGreen ═══

 bGreen (BYTE) 
    Green component of the color definition. 


═══ <hidden> RGB2 Field - bRed ═══

 bRed (BYTE) 
    Red component of the color definition. 


═══ <hidden> RGB2 Field - fcOptions ═══

 fcOptions (BYTE) 
    Entry options. 

    These can be ORed together if required: 

    PC_RESERVED         The color entry is reserved for animating color with 
                        the palette manager. 

    PC_EXPLICIT         The low-order word of the color table entry designates 
                        a physical palette slot. This allows an application to 
                        show the actual contents of the device palette as 
                        realized for other logical palettes. This does not 
                        prevent the color in the slot from being changed for 
                        any reason. 


═══ 1.56. SIZEF ═══

Size structure (FIXED values). 

typedef struct _SIZEF {
  FIXED     cx;  /*  Width. */
  FIXED     cy;  /*  Height. */
} SIZEF;

typedef SIZEF *PSIZEF;


═══ <hidden> SIZEF Field - cx ═══

 cx (FIXED) 
    Width. 


═══ <hidden> SIZEF Field - cy ═══

 cy (FIXED) 
    Height. 


═══ 1.57. SIZEL ═══

Size structure (LONG values). 

typedef struct _SIZEL {
  LONG     cx;  /*  Width. */
  LONG     cy;  /*  Height. */
} SIZEL;

typedef SIZEL *PSIZEL;


═══ <hidden> SIZEL Field - cx ═══

 cx (LONG) 
    Width. 


═══ <hidden> SIZEL Field - cy ═══

 cy (LONG) 
    Height. 


═══ 1.58. SHORT ═══

Signed integer in the range -32 768 through 32 767. 

#define SHORT short


═══ 1.59. STR8 ═══

String of 8 characters. 

typedef CHAR STR8[8];


═══ 1.60. ULONG ═══

Unsigned integer in the range 0 through 4 294 967 295. 

typedef unsigned long ULONG;


═══ 1.61. USHORT ═══

Unsigned integer in the range 0 through 65 535. 

typedef unsigned short USHORT;


═══ 2. Graphics Orders ═══

This section describes the format of the graphics orders. 

Graphics orders are used in the following circumstances: 

     Using GpiGetData or GpiPutData functions for bulk transfer of part or all 
      of graphics segment data (unless this is simply being copied without 
      being changed). 

     Editing segments with GpiQueryElement and GpiElement. 

     Generating metafiles (other than through the Presentation Manager API), 
      or examining their contents. The data part of Graphics Data structured 
      fields within the metafile (see "Metafile Data Format" in the 
      Presentation Manager Programming Reference) consists of graphics orders. 

 When primitive or attribute functions (plus certain other functions) are 
 specified at the programming interface, and the drawing mode (see 
 GpiSetDrawingMode) is set to drawandretain, graphics orders are constructed 
 and placed in the current graphics segment. One API call often causes a single 
 order to be generated. Sometimes, however, several orders are necessary: an 
 example of this is where a GpiPolyLine call is issued, which specifies more 
 strokes than there is room for, in a single order. 

 In either case, the order or orders generated by a single API call comprise a 
 single element, unless the application specifically starts an element using 
 the GpiBeginElement function. In this case the element consists of all of the 
 orders generated between this and the following GpiEndElement function. A 
 GpiQueryElement function returns the orders that comprise an element; the 
 application may edit these, and return them to the segment with GpiElement. 
 The Begin Element - End Element orders that surround a multi-order element in 
 the segment are never passed between the application and the system on 
 GpiQueryElement and GpiElement functions. 

 No double word or word alignment can be assumed for orders either within 
 segments or during editing. 


═══ 2.1. Introduction to Graphics Orders ═══

In the retain and draw-and-retain drawing modes, specific GPI functions 
(primitive-drawing and attribute-setting functions, plus some others) cause 
graphics orders to be stored in the current segment. A graphics order is a 
sequence of one or more bytes of data that describe a graphics function. There 
is typically a one-to-one correspondence between a GPI function and a graphics 
order. You do not need to understand the various formats and contents of the 
graphics orders, unless: 

     You are using GpiGetData or GpiPutData for bulk transfer of data that you 
      want to edit. 

     You are simply copying data from one segment to another. 

     You are using GpiElement to add data to a segment, or GpiQueryElement to 
      retrieve data from a segment. 

     You are examining the contents of a metafile. 

 Both the graphics orders and the metafile structure are described in the 
 Presentation Manager. This appendix describes the header file PMORD.H, which 
 has been provided to allow you to manipulate the graphics orders more easily. 


═══ 2.1.1. The Graphics-Orders Header File (PMORD.H) ═══

A set of helper constants, macros, and structures has been provided to help you 
decode and encode graphics orders. These items are defined in the header file 
PMORD.H. 

There are four types of graphics orders. The first byte of each order, 
regardless of the graphics-order type, is the order code itself, which either 
partially or completely describes what follows. Depending on the order type, 
the graphics order can contain further information. 

The four types of graphics order are: 

 1-Byte Order 
       The 1-byte order comprises a single byte: 

              BYTE 1 : order code.

 2-Byte Order 
       The 2-byte order consists of two bytes: 

              BYTE 1 : order code
              BYTE 2 : associated value.

 Long Order 
       The long order can comprise up to 257 bytes of information: 

              BYTE 1     : order code
              BYTE 2     : length of order (0 to 255)
              BYTE 3-257 : associated value bytes
                           depending on the order code.

       There is a special long order (Escape) where: 

              BYTE 3     : escape type
              BYTE 4     : escape identifier
              BYTE 5-257 : associated value bytes
                           depending on the escape
                           identifier.

 Very Long Order 
       The very long order can comprise up to 65537 bytes of information: 

              BYTE 1       : order code
              BYTE 2       : order qualifier
              BYTE 3       : length of order
                             (most significant byte)
              BYTE 4       : length of order
                             (least significant byte -
                              length of order is 0 to 65535)
              BYTE 5-65537 : associated value bytes
                             depending on the order
                             qualifier.

       There is a special very long order (Escape) where : 

              BYTE 5       : escape type
              BYTE 6       : escape identifier
              BYTE 7-65537 : associated value bytes
                             depending on the escape
                             identifier.


═══ 2.1.1.1. Decoding Graphics Orders ═══

The recommended way of decoding a buffer of graphics orders (in C language) is 
to use a pointer to address the first byte of the buffer, and then retrieve the 
graphics order it contains. To discover which of the four types of order you 
have, use the following macros: 

     BYTE_ORDER  (1-byte order) 

     SHORT_ORDER  (2-byte order) 

     LONG_ORDER  (long order) 

     VLONG_ORDER  (very long order). 
 These macros are defined in the header file PMORD.H. Each macro processes a 
 single byte of data and returns a Boolean value (zero or nonzero). A zero 
 value means that the order is not of that type. When you know the 
 graphics-order type, you can establish the length of the order, and add the 
 length to the pointer. You can then retrieve the next order in the buffer, and 
 repeat the process until all data has been retrieved. 

 You can decode the graphics-order data itself by providing a routine for each 
 of the order types, or a routine for each individual order: 

     For a 1-byte graphic order, the decoding routine should simply return a 
      length of 1. 

     For a 2-byte graphic order, the decoding routine can use the overlay 
      structure ORDER to decode the data. The routine should return a length of 
      2. 

     For a long order, the decoding routine can use the overlay structure 
      LORDER to decode the data. The length of the data is a variable value. 

     For a very long order, the decoding routine can use the overlay structure 
      VORDER to decode the data. The length of the data is a variable value. 

 The overlay structures ORDER, LORDER, and VORDER are defined in the header 
 file PMORD.H. 

 You can build graphics orders using the same structures and order types that 
 are used for decoding graphics orders. 


═══ 2.1.1.2. Naming Conventions ═══

The names of the graphics-order codes are in the form OCODE_Gxxx. The Gxxx 
abbreviation is the name of the individual order, and can be used for types, 
structures, and constants directly related to that order. In the header file, 
there is a comment on the same line as each of the orders that describes the 
order. For example, the Begin Area order (GBAR) is described in the header file 
as follows: 

#define OCODE_GBAR     0x68  /* Begin area    */
#define GBAR_BOUNDARY  0xC0

Note: 

In some structures, an S or an L is added to the name to differentiate between 
the short-coordinate form (16-bit) and the long-coordinate form (32-bit). For 
example, the Set Arc Parameters order (GSAP) is as follows: 

#define OCODE_GSAP     0x22
#define OCODE_GPSAP    0x62

   typedef struct _ORDERS_GSAP {
     SHORT  p;
     SHORT  q;
     SHORT  r;
     SHORT  s;
   } ORDERS_GSAP;

   typedef struct _ORDERL_GSAP {
     LONG   p;
     LONG   q;
     LONG   r;
     LONG   s;
   } ORDERL_GSAP;

In this example, the structures ORDERS_GSAP and ORDERL_GSAP are shared by GSAP 
(set arc parameters) and GPSAP (push and set arc parameters). As a rule, there 
is structure sharing between the set and push-and-set forms of graphics orders. 

There is structure-sharing between the current-position and the given-position 
forms of some orders. For example, the orders GCARC (arc at current position) 
and GARC (arc at given position) share a structure. 


═══ 2.2. Arc at a Given Position/Arc at Current Position ═══


═══ <hidden> Arc at a Given Position/Arc at Current Position - Syntax ═══

This order constructs an arc starting at a given position. 

Arc at a Given Position (GARC) 
X'C6' (LEN, P0, P1, P2) 

Arc at Current Position (GCARC) 
X'86' (LEN, P1, P2) 


═══ <hidden> GARC/GCARC Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GARC/GCARC Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of start point. 

    This parameter is only present in a Arc at a Given Position order. 


═══ <hidden> GARC/GCARC Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of intermediate point. 


═══ <hidden> GARC/GCARC Parameter - P2 ═══

 P2 (GPOINT) 
    Coordinate data of end point. 


═══ <hidden> Arc at a Given Position/Arc at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of start point. 

    This parameter is only present in a Arc at a Given Position order. 

 P1 (GPOINT) 
    Coordinate data of intermediate point. 

 P2 (GPOINT) 
    Coordinate data of end point. 


═══ <hidden> Arc at a Given Position/Arc at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.3. Begin Area ═══


═══ <hidden> Begin Area - Syntax ═══

This order indicates the start of a set of primitives that define an area 
boundary. 

Begin Area (GBAR) 
X'68' (FLAGS) 


═══ <hidden> GBAR Parameter - FLAGS ═══

 FLAGS 
    Internal flags. 

    RES1 (GBIT1) 
             Reserved for migration: 

             1       Only valid value. 

    BOUNDARY (GBIT1) 
             Boundary-line draw indicator: 

             0       Do not draw boundary lines 
             1       Draw boundary lines. 

    INSIDE (GBIT1) 
             Mode shading: 

             0       Alternate mode 
             1       Winding mode. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 


═══ <hidden> Begin Area - Parameters ═══

 FLAGS 
    Internal flags. 

    RES1 (GBIT1) 
             Reserved for migration: 

             1       Only valid value. 

    BOUNDARY (GBIT1) 
             Boundary-line draw indicator: 

             0       Do not draw boundary lines 
             1       Draw boundary lines. 

    INSIDE (GBIT1) 
             Mode shading: 

             0       Alternate mode 
             1       Winding mode. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 


═══ <hidden> Begin Area - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.4. Begin Element ═══


═══ <hidden> Begin Element - Syntax ═══

This order indicates the beginning of a set of primitives that define an 
element. 

Begin Element (GBEL) 
X'D2' (LEN, TYPE, DESCR) 


═══ <hidden> GBEL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GBEL Parameter - TYPE ═══

 TYPE (GLONG) 
    Element type code. 

    Possible values are described in the following list: 

    0x0000FD01       Line bundle 
    0x0000FD02       Character bundle 
    0x0000FD03       Marker bundle 
    0x0000FD04       Area bundle 
    0x0000FD05       Image bundle 
    0x00000007       Call segment 
    0x00000081       Polyline 
    0x00000085       Polyfillet 
    0x000000A4       Polyfillet sharp 
    0x000000A5       Polyspline 
    0x00000082       Polymarker 
    0x00000087       Full arc 
    0x00000091       Image 
    0x000000B1       Character string at current position 
    0x000000F1       Character string at given position 
    0x81xxxxxx-0xFFxxxxxx Indicates user defined elements 
    Other            Reserved values. 


═══ <hidden> GBEL Parameter - DESCR ═══

 DESCR (GUNDF) 
    Element description data. 

    This is optional. 


═══ <hidden> Begin Element - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 TYPE (GLONG) 
    Element type code. 

    Possible values are described in the following list: 

    0x0000FD01       Line bundle 
    0x0000FD02       Character bundle 
    0x0000FD03       Marker bundle 
    0x0000FD04       Area bundle 
    0x0000FD05       Image bundle 
    0x00000007       Call segment 
    0x00000081       Polyline 
    0x00000085       Polyfillet 
    0x000000A4       Polyfillet sharp 
    0x000000A5       Polyspline 
    0x00000082       Polymarker 
    0x00000087       Full arc 
    0x00000091       Image 
    0x000000B1       Character string at current position 
    0x000000F1       Character string at given position 
    0x81xxxxxx-0xFFxxxxxx Indicates user defined elements 
    Other            Reserved values. 

 DESCR (GUNDF) 
    Element description data. 

    This is optional. 


═══ <hidden> Begin Element - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.5. Begin Image at Given Position/Begin Image at Current Position ═══


═══ <hidden> Begin Image at Given Position/Begin Image at Current Position - Syntax ═══

These orders identify the start of an image definition at a given position or 
at the current position. 

Begin Image at Given Position (GBIMG) 
X'D1' (LEN, P0, FORMAT, RES, WIDTH, HEIGHT) 

Begin Image at Current Position (GCBIMG) 
X'91' (LEN, FORMAT, RES, WIDTH, HEIGHT) 


═══ <hidden> GBIMG/GCBIMG Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 


═══ <hidden> GBIMG/GCBIMG Parameter - P0 ═══

 P0 (GPOINT) 
    Point at which the image is to be placed. 

    This parameter is only present in a Begin Image at Given Position order. 


═══ <hidden> GBIMG/GCBIMG Parameter - FORMAT ═══

 FORMAT (GBIT8) 
    Format of the image data. 

    0x00      One bit in the data represents one image point on the usable 
              area. 


═══ <hidden> GBIMG/GCBIMG Parameter - RES ═══

 RES (GBIT8) 
    Reserved. 

    0x00      Only valid value. 


═══ <hidden> GBIMG/GCBIMG Parameter - WIDTH ═══

 WIDTH (GUSHORT370) 
    Width of the image data. 

    This is the width in pels. 

    0x00-0x07     Valid range of values. 


═══ <hidden> GBIMG/GCBIMG Parameter - HEIGHT ═══

 HEIGHT (GUSHORT370) 
    Height of the image data. 

    This is the height in pels. 


═══ <hidden> Begin Image at Given Position/Begin Image at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 

 P0 (GPOINT) 
    Point at which the image is to be placed. 

    This parameter is only present in a Begin Image at Given Position order. 

 FORMAT (GBIT8) 
    Format of the image data. 

    0x00      One bit in the data represents one image point on the usable 
              area. 

 RES (GBIT8) 
    Reserved. 

    0x00      Only valid value. 

 WIDTH (GUSHORT370) 
    Width of the image data. 

    This is the width in pels. 

    0x00-0x07     Valid range of values. 

 HEIGHT (GUSHORT370) 
    Height of the image data. 

    This is the height in pels. 


═══ <hidden> Begin Image at Given Position/Begin Image at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.6. Begin Path ═══


═══ <hidden> Begin Path - Syntax ═══

This order sets the drawing process into path state. 

Begin Path (GBPTH) 
X'D0' (LEN, RES, PTHID) 


═══ <hidden> GBPTH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 


═══ <hidden> GBPTH Parameter - RES ═══

 RES (GBIT16) 
    Reserved. 

    0x0000    Only valid value. 


═══ <hidden> GBPTH Parameter - PTHID ═══

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF   Valid path identifiers. 


═══ <hidden> Begin Path - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 

 RES (GBIT16) 
    Reserved. 

    0x0000    Only valid value. 

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF   Valid path identifiers. 


═══ <hidden> Begin Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.7. Bezier Curve at Given Position/Bezier Curve at Current Poition ═══


═══ <hidden> Bezier Curve at Given Position/Bezier Curve at Current Poition - Syntax ═══

This order generates a curve that starts at a given position. 

Bezier Curve at Given Position (GBEZ) 
X'E5' (LEN, P0, P1, P2, P3, P4, P5, P6, PN-2, PN-1, PN) 

Bezier Curve at Current Poition (GCBEZ) 
X'A5' (LEN, P1, P2, P3, P4, P5, P6, PN-2, PN-1, PN) 


═══ <hidden> GBEZ/GCBEZ Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GBEZ/GCBEZ Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of first curve start. 

    This parameter is only present in a Bezier Curve at Given Position order. 


═══ <hidden> GBEZ/GCBEZ Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of first curve, first control point. 


═══ <hidden> GBEZ/GCBEZ Parameter - P2 ═══

 P2 (GPOINT) 
    Coordinate data of first curve, second control point. 


═══ <hidden> GBEZ/GCBEZ Parameter - P3 ═══

 P3 (GPOINT) 
    Coordinate data of first curve end. 


═══ <hidden> GBEZ/GCBEZ Parameter - P4 ═══

 P4 (GPOINT) 
    Coordinate data of second curve, first control point 


═══ <hidden> GBEZ/GCBEZ Parameter - P5 ═══

 P5 (GPOINT) 
    Coordinate data of second curve, second control point 


═══ <hidden> GBEZ/GCBEZ Parameter - P6 ═══

 P6 (GPOINT) 
    Coordinate data of second curve end. 


═══ <hidden> GBEZ/GCBEZ Parameter - PN-2 ═══

 PN-2 (GPOINT) 
    Coordinate data of final curve, first control point 


═══ <hidden> GBEZ/GCBEZ Parameter - PN-1 ═══

 PN-1 (GPOINT) 
    Coordinate data of final curve, second control point 


═══ <hidden> GBEZ/GCBEZ Parameter - PN ═══

 PN (GPOINT) 
    Coordinate data of final curve end. 


═══ <hidden> Bezier Curve at Given Position/Bezier Curve at Current Poition - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of first curve start. 

    This parameter is only present in a Bezier Curve at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of first curve, first control point. 

 P2 (GPOINT) 
    Coordinate data of first curve, second control point. 

 P3 (GPOINT) 
    Coordinate data of first curve end. 

 P4 (GPOINT) 
    Coordinate data of second curve, first control point 

 P5 (GPOINT) 
    Coordinate data of second curve, second control point 

 P6 (GPOINT) 
    Coordinate data of second curve end. 

 PN-2 (GPOINT) 
    Coordinate data of final curve, first control point 

 PN-1 (GPOINT) 
    Coordinate data of final curve, second control point 

 PN (GPOINT) 
    Coordinate data of final curve end. 


═══ <hidden> Bezier Curve at Given Position/Bezier Curve at Current Poition - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.8. Bitblt ═══


═══ <hidden> Bitblt - Syntax ═══

This order copies a rectangle of a bit map into DOCS. 

Bitblt (GBBLT) 
X'D6' (LEN, FLAGS, MIX, BMID, TRANS, P1, P2, SOURCE1X, SOURCE1Y, SOURCE2X, 
SOURCE2Y) 


═══ <hidden> GBBLT Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GBBLT Parameter - FLAGS ═══

 FLAGS (GBIT16) 
    Reserved. 

    0x0000      Only valid value. 


═══ <hidden> GBBLT Parameter - MIX ═══

 MIX (GBIT16) 
    Mix mode. 

    Values are: 

    0x00CC      Source. 
    0x00C0      Source and pattern. 
    0x00CA      Source where pattern1 
    0x000C      Source where pattern0 
    0x00E2      Pattern where source1 
    0x00B8      Pattern where source0 
    Other       Reserved values. 


═══ <hidden> GBBLT Parameter - BMID ═══

 BMID (GHBITMAP) 
    Bit-map identifier. 


═══ <hidden> GBBLT Parameter - TRANS ═══

 TRANS (GBIT32) 
    Transfer mode. 

    Values are: 

    0x00000000      OR 
    0x01000000      AND 
    0x02000000      Ignore 
    Other           Reserved values. 


═══ <hidden> GBBLT Parameter - P1 ═══

 P1 (GPOINT) 
    Target rectangle bottom-left corner. 


═══ <hidden> GBBLT Parameter - P2 ═══

 P2 (GPOINT) 
    Target rectangle top-right corner. 


═══ <hidden> GBBLT Parameter - SOURCE1X ═══

 SOURCE1X (GLONG) 
    Source rectangle bottom-left corner, x-coordinate. 


═══ <hidden> GBBLT Parameter - SOURCE1Y ═══

 SOURCE1Y (GLONG) 
    Source rectangle bottom-left corner, y-coordinate. 


═══ <hidden> GBBLT Parameter - SOURCE2X ═══

 SOURCE2X (GLONG) 
    Source rectangle top-right corner, x-coordinate. 


═══ <hidden> GBBLT Parameter - SOURCE2Y ═══

 SOURCE2Y (GLONG) 
    Source rectangle top-right corner, y-coordinate. 


═══ <hidden> Bitblt - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS (GBIT16) 
    Reserved. 

    0x0000      Only valid value. 

 MIX (GBIT16) 
    Mix mode. 

    Values are: 

    0x00CC      Source. 
    0x00C0      Source and pattern. 
    0x00CA      Source where pattern1 
    0x000C      Source where pattern0 
    0x00E2      Pattern where source1 
    0x00B8      Pattern where source0 
    Other       Reserved values. 

 BMID (GHBITMAP) 
    Bit-map identifier. 

 TRANS (GBIT32) 
    Transfer mode. 

    Values are: 

    0x00000000      OR 
    0x01000000      AND 
    0x02000000      Ignore 
    Other           Reserved values. 

 P1 (GPOINT) 
    Target rectangle bottom-left corner. 

 P2 (GPOINT) 
    Target rectangle top-right corner. 

 SOURCE1X (GLONG) 
    Source rectangle bottom-left corner, x-coordinate. 

 SOURCE1Y (GLONG) 
    Source rectangle bottom-left corner, y-coordinate. 

 SOURCE2X (GLONG) 
    Source rectangle top-right corner, x-coordinate. 

 SOURCE2Y (GLONG) 
    Source rectangle top-right corner, y-coordinate. 


═══ <hidden> Bitblt - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.9. Box at Given Position/Box at Current Position ═══


═══ <hidden> Box at Given Position/Box at Current Position - Syntax ═══

This order defines a box with square or round corners, drawn with its first 
corner at a given position. 

Box at Given Position (GBOX) 
X'C0' (LEN, CONTROL, RES, P0, P1, HAXIS, VAXIS) 

Box at Current Position (GCBOX) 
X'80' (LEN, CONTROL, RES, P1, HAXIS, VAXIS) 


═══ <hidden> GBOX/GCBOX Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GBOX/GCBOX Parameter - CONTROL ═══

 CONTROL 
    Internal flags. 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    FILL (GBIT1) 
             Values: 

             0       No fill 
             1       Fill. 

    BOUNDARY (GBIT1) 
             Values: 

             0       No boundary 
             1       Boundary. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 


═══ <hidden> GBOX/GCBOX Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GBOX/GCBOX Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of box origin. 

    This parameter is only present in a Box at Given Position order. 


═══ <hidden> GBOX/GCBOX Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of box corner. 


═══ <hidden> GBOX/GCBOX Parameter - HAXIS ═══

 HAXIS (GROSOL) 
    Length of horizontal axis of ellipse. 


═══ <hidden> GBOX/GCBOX Parameter - VAXIS ═══

 VAXIS (GROSOL) 
    Length of vertical axis of ellipse. 


═══ <hidden> Box at Given Position/Box at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 CONTROL 
    Internal flags. 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    FILL (GBIT1) 
             Values: 

             0       No fill 
             1       Fill. 

    BOUNDARY (GBIT1) 
             Values: 

             0       No boundary 
             1       Boundary. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 P0 (GPOINT) 
    Coordinate data of box origin. 

    This parameter is only present in a Box at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of box corner. 

 HAXIS (GROSOL) 
    Length of horizontal axis of ellipse. 

 VAXIS (GROSOL) 
    Length of vertical axis of ellipse. 


═══ <hidden> Box at Given Position/Box at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.10. Call Segment ═══


═══ <hidden> Call Segment - Syntax ═══

This order calls one segment from another. 

Call Segment (GCALLS) 
X'07' (LEN, RES, SEGNAME) 


═══ <hidden> GCALLS Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 


═══ <hidden> GCALLS Parameter - RES ═══

 RES (GBIT16) 
    Reserved value, must be 0. 


═══ <hidden> GCALLS Parameter - SEGNAME ═══

 SEGNAME (GLONG) 
    Name of segment that is to be called. 

    The name cannot be 0. 


═══ <hidden> Call Segment - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06      Only valid value. 

 RES (GBIT16) 
    Reserved value, must be 0. 

 SEGNAME (GLONG) 
    Name of segment that is to be called. 

    The name cannot be 0. 


═══ <hidden> Call Segment - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.11. Character String at Given Position/Character String at Current Position ═══


═══ <hidden> Character String at Given Position/Character String at Current Position - Syntax ═══

These orders draw a character string at a given position or at the current 
position. 

Character String at Given Position (GCHST) 
X'C3' (LEN, P0, CP) 

Character String at Current Position (GCCHST) 
X'83' (LEN, CP) 


═══ <hidden> GCHST/GCCHST Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GCHST/GCCHST Parameter - P0 ═══

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String at Given Position 
    order. 


═══ <hidden> GCHST/GCCHST Parameter - CP ═══

 CP (GSTR) 
    Code points of each character in the string. 


═══ <hidden> Character String at Given Position/Character String at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String at Given Position 
    order. 

 CP (GSTR) 
    Code points of each character in the string. 


═══ <hidden> Character String at Given Position/Character String at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.12. Character String Extended at Given Position/Character String Extended at Current Position ═══


═══ <hidden> Character String Extended at Given Position/Character String Extended at Current Position - Syntax ═══

This order defines a character string to be drawn at a given position. 

Character String Extended at Given Position (GCHSTE) 
X'FEF0' (LEN1, P0, FLAGS, RES, P1, P2, LEN2, CP, PAD, VECT) 

Character String Extended at Current Position (GCCHSTE) 
X'FEB0' (LEN1, FLAGS, RES, P1, P2, LEN2, CP, PAD, VECT) 


═══ <hidden> GCHSTE/GCCHSTE Parameter - LEN1 ═══

 LEN1 (GLENGTH2) 
    Length of following data. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - P0 ═══

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String Extended at Given 
    Position order. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - FLAGS ═══

 FLAGS 
    Extra functions: 

    RECT (GBIT1) 
             Values: 

             0       Do not draw background rectangle 
             1       Draw background rectangle. 

    CLIP (GBIT1) 
             Values: 

             0       Do not clip to rectangle 
             1       Clip to rectangle. 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    LVCP (GBIT1) 
             Values: 

             0       Move current position 
             1       Leave current position. 

    RES2 (GBIT4) 
             Reserved value, must be 0. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of rectangle corner. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - P2 ═══

 P2 (GPOINT) 
    Coordinate data of rectangle corner. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - LEN2 ═══

 LEN2 (GLENGTH2) 
    Length of code-point data. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - CP ═══

 CP (GSTR) 
    Code-point data. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - PAD ═══

 PAD (GBIT8) 
    Pad byte. 

    Only needs to be included if CP is an odd number of bytes. 


═══ <hidden> GCHSTE/GCCHSTE Parameter - VECT ═══

 VECT (GROSOL) 
    IN (0) Vector of character increments. 

    VECT is a vector of n elements, where n is the number of code points 
    present in the CP parameter. 


═══ <hidden> Character String Extended at Given Position/Character String Extended at Current Position - Parameters ═══

 LEN1 (GLENGTH2) 
    Length of following data. 

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String Extended at Given 
    Position order. 

 FLAGS 
    Extra functions: 

    RECT (GBIT1) 
             Values: 

             0       Do not draw background rectangle 
             1       Draw background rectangle. 

    CLIP (GBIT1) 
             Values: 

             0       Do not clip to rectangle 
             1       Clip to rectangle. 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    LVCP (GBIT1) 
             Values: 

             0       Move current position 
             1       Leave current position. 

    RES2 (GBIT4) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 P1 (GPOINT) 
    Coordinate data of rectangle corner. 

 P2 (GPOINT) 
    Coordinate data of rectangle corner. 

 LEN2 (GLENGTH2) 
    Length of code-point data. 

 CP (GSTR) 
    Code-point data. 

 PAD (GBIT8) 
    Pad byte. 

    Only needs to be included if CP is an odd number of bytes. 

 VECT (GROSOL) 
    IN (0) Vector of character increments. 

    VECT is a vector of n elements, where n is the number of code points 
    present in the CP parameter. 


═══ <hidden> Character String Extended at Given Position/Character String Extended at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.13. Character String Move at Given Position/Character String Move at Current Position ═══


═══ <hidden> Character String Move at Given Position/Character String Move at Current Position - Syntax ═══

This order draws a character string starting from a given position and moves 
the current position to the end of the string. 

Character String Move at Given Position (GCHSTM) 
X'F1' (LEN, P0, CP) 

Character String Move at Current Position (GCCHSTM) 
X'B1' (LEN, CP) 


═══ <hidden> GCHSTM/GCCHSTM Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GCHSTM/GCCHSTM Parameter - P0 ═══

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String Move at Given Position 
    order. 


═══ <hidden> GCHSTM/GCCHSTM Parameter - CP ═══

 CP (GSTR) 
    Code points of each character in the string. 


═══ <hidden> Character String Move at Given Position/Character String Move at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Point at which the character string is to be placed. 

    This parameter is only present in a Character String Move at Given Position 
    order. 

 CP (GSTR) 
    Code points of each character in the string. 


═══ <hidden> Character String Move at Given Position/Character String Move at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.14. Close Figure ═══


═══ <hidden> Close Figure - Syntax ═══

This order delimits the end of a closed figure. 

Close Figure (GCLFIG) 
X'7D' (RES) 


═══ <hidden> GCLFIG Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Close Figure - Parameters ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Close Figure - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.15. Comment ═══


═══ <hidden> Comment - Syntax ═══

This order enables data to be stored within a segment. 

Comment (GCOMT) 
X'01' (LEN, DATA[LEN]) 


═══ <hidden> GCOMT Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GCOMT Parameter - DATA[LEN] ═══

 DATA[LEN] (GBIT8) 
    Comment data. 


═══ <hidden> Comment - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 DATA[LEN] (GBIT8) 
    Comment data. 


═══ <hidden> Comment - Remarks ═══

This order is treated as a no-operation. 


═══ <hidden> Comment - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.16. End Area ═══


═══ <hidden> End Area - Syntax ═══

This order indicates the end of a set of primitives that define an area 
boundary. 

End Area (GEAR) 
X'60' (LEN, DATA[LEN]) 


═══ <hidden> GEAR Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data.  It is normally 0. 


═══ <hidden> GEAR Parameter - DATA[LEN] ═══

 DATA[LEN] (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Area - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data.  It is normally 0. 

 DATA[LEN] (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Area - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.17. End Element ═══


═══ <hidden> End Element - Syntax ═══

This order identifies the end of a set of primitives that define an element. 

End Element (GEEL) 
X'49' (RES) 


═══ <hidden> GEEL Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Element - Parameters ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Element - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.18. End Image ═══


═══ <hidden> End Image - Syntax ═══

This order identifies the end of an image definition. 

End Image (GEIMG) 
X'93' (LEN, DATA[LEN]) 


═══ <hidden> GEIMG Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data.  It is normally 0. 


═══ <hidden> GEIMG Parameter - DATA[LEN] ═══

 DATA[LEN] (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Image - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data.  It is normally 0. 

 DATA[LEN] (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Image - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.19. End of Symbol Definition ═══


═══ <hidden> End of Symbol Definition - Syntax ═══

This order indicates the end of a set of orders defining a graphics symbol. 

End of Symbol Definition (GESD)
X'FF'


═══ <hidden> End of Symbol Definition - Remarks ═══

This order is only valid in the context of symbol definitions. 


═══ <hidden> End of Symbol Definition - Topics ═══

Select an item: 

Syntax
Remarks
Glossary


═══ 2.20. End Path ═══


═══ <hidden> End Path - Syntax ═══

This order ends the definition of a path. 

End Path (GEPTH) 
X'7F' (RES) 


═══ <hidden> GEPTH Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Path - Parameters ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.21. End Prolog ═══


═══ <hidden> End Prolog - Syntax ═══

This order indicates the end of the prolog of a segment. 

End Prolog (GEPROL) 
X'3E' (RES) 


═══ <hidden> GEPROL Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Prolog - Parameters ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> End Prolog - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.22. Escape ═══


═══ <hidden> Escape - Syntax ═══

This order provides facilities for registered and unregistered escape 
functions. 

Escape (GESCP) 
X'D5' (LEN, TYPE, RID, PARMS) 


═══ <hidden> GESCP Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GESCP Parameter - TYPE ═══

 TYPE (GBIT8) 
    Type identifier: 

    80         Registered value 
    Other      All other values are unregistered. 


═══ <hidden> GESCP Parameter - RID ═══

 RID (GBIT8) 
    Registered identifier: 

    01      Set pel. 
    02      BITBLT function. 
    03      Flood fill function. 
    04      Draw bits function. 


═══ <hidden> GESCP Parameter - PARMS ═══

 PARMS (GSTR) 
    Parameters of escape. 


═══ <hidden> Escape - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 TYPE (GBIT8) 
    Type identifier: 

    80         Registered value 
    Other      All other values are unregistered. 

 RID (GBIT8) 
    Registered identifier: 

    01      Set pel. 
    02      BITBLT function. 
    03      Flood fill function. 
    04      Draw bits function. 

 PARMS (GSTR) 
    Parameters of escape. 


═══ <hidden> Escape - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.23. Extended Escape ═══


═══ <hidden> Extended Escape - Syntax ═══

This order provides facilities for registered and unregistered escape 
functions. 

Extended Escape (GEESCP) 
X'FED5' (LEN, TYPE, RID, PARMS) 


═══ <hidden> GEESCP Parameter - LEN ═══

 LEN (GLENGTH2) 
    Length of following data. 


═══ <hidden> GEESCP Parameter - TYPE ═══

 TYPE (GBIT8) 
    Type identifier: 

    0x80       Registered value 
    Other      All other values are unregistered. 


═══ <hidden> GEESCP Parameter - RID ═══

 RID (GUCHAR) 
    Registered identifier. 

    No registered extended escapes are used by the OS/2* operating system. 


═══ <hidden> GEESCP Parameter - PARMS ═══

 PARMS (GSTR) 
    Parameters of escape. 


═══ <hidden> Extended Escape - Parameters ═══

 LEN (GLENGTH2) 
    Length of following data. 

 TYPE (GBIT8) 
    Type identifier: 

    0x80       Registered value 
    Other      All other values are unregistered. 

 RID (GUCHAR) 
    Registered identifier. 

    No registered extended escapes are used by the OS/2* operating system. 

 PARMS (GSTR) 
    Parameters of escape. 


═══ <hidden> Extended Escape - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.24. Fill Path ═══


═══ <hidden> Fill Path - Syntax ═══

This order fills the interior of the specified path. 

Fill Path (GFPTH) 
X'D7' (LEN, FLAGS, RES, PTHID) 


═══ <hidden> GFPTH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06    Only valid value. 


═══ <hidden> GFPTH Parameter - FLAGS ═══

 FLAGS 
    Extra functions: 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    INSIDE (GBIT1) 
             Values: 

             0       Alternate mode 
             1       Winding mode. 

    MOD (GBIT1) 
             Values: 

             0       Do not modify before filling 
             1       Modify path before filling. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 


═══ <hidden> GFPTH Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GFPTH Parameter - PTHID ═══

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF Valid path identifiers. 


═══ <hidden> Fill Path - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06    Only valid value. 

 FLAGS 
    Extra functions: 

    RES1 (GBIT1) 
             Reserved value, must be 0. 

    INSIDE (GBIT1) 
             Values: 

             0       Alternate mode 
             1       Winding mode. 

    MOD (GBIT1) 
             Values: 

             0       Do not modify before filling 
             1       Modify path before filling. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF Valid path identifiers. 


═══ <hidden> Fill Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.25. Fillet at Given Position/Fillet at Current Position ═══


═══ <hidden> Fillet at Given Position/Fillet at Current Position - Syntax ═══

These orders draw a curved line tangential to a specified set of straight 
lines, at the given position or at the current position. 

Fillet at Given Position (GFLT) 
X'C5' (LEN, P0, P1, P2, PN) 

Fillet at Current Position (GCFLT) 
X'85' (LEN, P1, P2, PN) 


═══ <hidden> GFLT/GCFLT Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GFLT/GCFLT Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Fillet at Given Position order. 


═══ <hidden> GFLT/GCFLT Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of first line end. 


═══ <hidden> GFLT/GCFLT Parameter - P2 ═══

 P2 (GPOINT) 
    Coordinate data of second line end. 


═══ <hidden> GFLT/GCFLT Parameter - PN ═══

 PN (GPOINT) 
    Coordinate data of final line end. 


═══ <hidden> Fillet at Given Position/Fillet at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Fillet at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of first line end. 

 P2 (GPOINT) 
    Coordinate data of second line end. 

 PN (GPOINT) 
    Coordinate data of final line end. 


═══ <hidden> Fillet at Given Position/Fillet at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.26. Full Arc at Given Position/Full Arc at Current Position ═══


═══ <hidden> Full Arc at Given Position/Full Arc at Current Position - Syntax ═══

This order constructs a full circle or an ellipse, with the center at a given 
position. 

Full Arc at Given Position (GFARC) 
X'C7' (LEN, P0, M) 

Full Arc at Current Position (GCFARC) 
X'87' (LEN, M) 


═══ <hidden> GFARC/GCFARC Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GFARC/GCFARC Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of the center of the circle/ellipse. 

    This parameter is only present in a Full Arc at Given Position order. 


═══ <hidden> GFARC/GCFARC Parameter - M ═══

 M (GROFUFS) 
    Multiplier. 


═══ <hidden> Full Arc at Given Position/Full Arc at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of the center of the circle/ellipse. 

    This parameter is only present in a Full Arc at Given Position order. 

 M (GROFUFS) 
    Multiplier. 


═══ <hidden> Full Arc at Given Position/Full Arc at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.27. Image Data ═══


═══ <hidden> Image Data - Syntax ═══

This order provides bit data for an image. 

Image Data (GIMD) 
X'92' (LEN, DATA[LEN]) 


═══ <hidden> GIMD Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GIMD Parameter - DATA[LEN] ═══

 DATA[LEN] (GBIT8) 
    Image data. 


═══ <hidden> Image Data - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 DATA[LEN] (GBIT8) 
    Image data. 


═══ <hidden> Image Data - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.28. Label ═══


═══ <hidden> Label - Syntax ═══

This order is used to label an element within a segment. 

Label (GLBL) 
X'D3' (LEN, LDATA) 


═══ <hidden> GLBL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 


═══ <hidden> GLBL Parameter - LDATA ═══

 LDATA (GLONG) 
    Label value. 


═══ <hidden> Label - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 

 LDATA (GLONG) 
    Label value. 


═══ <hidden> Label - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.29. Line at Given Position/Line at Current Position ═══


═══ <hidden> Line at Given Position/Line at Current Position - Syntax ═══

This order defines one or more connected straight lines, drawn from the given 
position. 

Line at Given Position (GLINE) 
X'C1' (LEN, P0, P1, PN) 

Line at Current Position (GCLINE) 
X'81' (LEN, P1, PN) 


═══ <hidden> GLINE/GCLINE Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GLINE/GCLINE Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Line at Given Position order. 


═══ <hidden> GLINE/GCLINE Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of first line end. 


═══ <hidden> GLINE/GCLINE Parameter - PN ═══

 PN (GPOINT) 
    Coordinate data of final line end. 


═══ <hidden> Line at Given Position/Line at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Line at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of first line end. 

 PN (GPOINT) 
    Coordinate data of final line end. 


═══ <hidden> Line at Given Position/Line at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.30. Marker at Given Position/Marker at Current Position ═══


═══ <hidden> Marker at Given Position/Marker at Current Position - Syntax ═══

This order draws the current marker symbol at one or more positions starting 
from a given position. 

Marker at Given Position (GMRK) 
X'C2' (LEN, P0, P1, PN) 

Marker at Current Position (GCMRK) 
X'82' (LEN, P1, PN) 


═══ <hidden> GMRK/GCMRK Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GMRK/GCMRK Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of first marker. 


═══ <hidden> GMRK/GCMRK Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of second marker. 


═══ <hidden> GMRK/GCMRK Parameter - PN ═══

 PN (GPOINT) 
    Coordinate data of final marker. 


═══ <hidden> Marker at Given Position/Marker at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of first marker. 

 P1 (GPOINT) 
    Coordinate data of second marker. 

 PN (GPOINT) 
    Coordinate data of final marker. 


═══ <hidden> Marker at Given Position/Marker at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.31. Modify Path ═══


═══ <hidden> Modify Path - Syntax ═══

This order modifies the path according to the value of the mode. 

Modify Path (GMPTH) 
X'D8' (LEN, MODE, RES, PTHID) 


═══ <hidden> GMPTH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06       Only valid value. 


═══ <hidden> GMPTH Parameter - MODE ═══

 MODE (GBIT8) 
    Mode of path modification: 

    0x06       Stroke the path 
    Other      All other values are reserved. 


═══ <hidden> GMPTH Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GMPTH Parameter - PTHID ═══

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF Valid path identifiers. 


═══ <hidden> Modify Path - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x06       Only valid value. 

 MODE (GBIT8) 
    Mode of path modification: 

    0x06       Stroke the path 
    Other      All other values are reserved. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 PTHID (GLONG) 
    Path identifier. 

    0x00000001-0xFFFFFFFF Valid path identifiers. 


═══ <hidden> Modify Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.32. No-Operation ═══


═══ <hidden> No-Operation - Syntax ═══

This order is a no-operation. 

No-Operation (GNOP1)
X'00'


═══ <hidden> No-Operation - Topics ═══

Select an item: 

Syntax
Glossary


═══ 2.33. Outline Path ═══


═══ <hidden> Outline Path - Syntax ═══

This order draws the outline of the specified path. 

Outline Path (GOPTH) 
X'D4' (LEN, FLAGS, RES, PTHID) 


═══ <hidden> GOPTH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GOPTH Parameter - FLAGS ═══

 FLAGS (GBIT8) 
    Function flags: 

    0x00    Only valid value. 


═══ <hidden> GOPTH Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GOPTH Parameter - PTHID ═══

 PTHID (GLONG) 
    Path identifier. 

    1       Only valid value. 


═══ <hidden> Outline Path - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS (GBIT8) 
    Function flags: 

    0x00    Only valid value. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 PTHID (GLONG) 
    Path identifier. 

    1       Only valid value. 


═══ <hidden> Outline Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.34. Partial Arc at Given Position/Partial Arc at Current Position ═══


═══ <hidden> Partial Arc at Given Position/Partial Arc at Current Position - Syntax ═══

This order draws a line from a given position to the start of an arc, and then 
draws the arc. 

Partial Arc at Given Position (GPARC) 
X'E3' (LEN, P0, P1, M, START, SWEEP) 

Partial Arc at Current Position (GCPARC) 
X'A3' (LEN, P1, M, START, SWEEP) 


═══ <hidden> GPARC/GCPARC Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GPARC/GCPARC Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of start of line. 

    This parameter is only present in a Partial Arc at Given Position order. 


═══ <hidden> GPARC/GCPARC Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of center of arc. 


═══ <hidden> GPARC/GCPARC Parameter - M ═══

 M (GROFUFS) 
    Multiplier. 


═══ <hidden> GPARC/GCPARC Parameter - START ═══

 START (GROF) 
    Start angle. 


═══ <hidden> GPARC/GCPARC Parameter - SWEEP ═══

 SWEEP (GROF) 
    Sweep angle. 


═══ <hidden> Partial Arc at Given Position/Partial Arc at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of start of line. 

    This parameter is only present in a Partial Arc at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of center of arc. 

 M (GROFUFS) 
    Multiplier. 

 START (GROF) 
    Start angle. 

 SWEEP (GROF) 
    Sweep angle. 


═══ <hidden> Partial Arc at Given Position/Partial Arc at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.35. Polygons ═══


═══ <hidden> Polygons - Syntax ═══

This order defines a set of polygons, which are optionally filled. 

Polygons (GPOLYS) 
X'F3' (LEN, FLAGS, COUNT, POLYS) 


═══ <hidden> GPOLYS Parameter - LEN ═══

 LEN (GLENGTH2) 
    Length of following data. 


═══ <hidden> GPOLYS Parameter - FLAGS ═══

 FLAGS 
    Internal flags. 

    INSIDE (GBIT1) 
             Mode shading: 

             0       Alternate mode. 
             1       Winding mode. 

    MODEL (GBIT1) 
             Drawing model: 

             0       The fill is inclusive of bottom right. 
             1       The fill is exclusive of bottom right. 

    RES2 (GBIT6) 
             Reserved value, must be 0. 


═══ <hidden> GPOLYS Parameter - COUNT ═══

 COUNT (GUSHORT) 
    Number of polygons. 


═══ <hidden> GPOLYS Parameter - POLYS ═══

 POLYS (GPOLYS) 
    Array of polygons. 


═══ <hidden> Polygons - Parameters ═══

 LEN (GLENGTH2) 
    Length of following data. 

 FLAGS 
    Internal flags. 

    INSIDE (GBIT1) 
             Mode shading: 

             0       Alternate mode. 
             1       Winding mode. 

    MODEL (GBIT1) 
             Drawing model: 

             0       The fill is inclusive of bottom right. 
             1       The fill is exclusive of bottom right. 

    RES2 (GBIT6) 
             Reserved value, must be 0. 

 COUNT (GUSHORT) 
    Number of polygons. 

 POLYS (GPOLYS) 
    Array of polygons. 


═══ <hidden> Polygons - Remarks ═══

This order draws a set of polygons. For the first polygon the current position 
is the first point. For all subsequent polygons all points which define the 
polygon are given explicitly.  The polygons are automatically closed if 
necessary. 

The current position is set to the last point specified. 


═══ <hidden> Polygons - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.36. Pop ═══


═══ <hidden> Pop - Syntax ═══

This order enables data to be popped from the Segment Call Stack. 

Pop (GPOP) 
X'3F' (RES) 


═══ <hidden> GPOP Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Pop - Parameters ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Pop - Remarks ═══

The data is placed into an attribute or Drawing Process Control. 


═══ <hidden> Pop - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.37. Relative Line at Given Position/Relative Line at Current Position ═══


═══ <hidden> Relative Line at Given Position/Relative Line at Current Position - Syntax ═══

These orders define one or more connected straight lines, at the given position 
or at the current position. 

Relative Line at Given Position (GRLINE) 
X'E1' (LEN, P0, OFF0, OFF1, OFFN) 

Relative Line at Current Position (GCRLINE) 
X'A1' (LEN, OFF0, OFF1, OFFN) 


═══ <hidden> GRLINE/GCRLINE Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GRLINE/GCRLINE Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Relative Line at Given Position order. 


═══ <hidden> GRLINE/GCRLINE Parameter - OFF0 ═══

 OFF0 (GDELPOINT) 
    Offset data for first point. 

    This offset is to the first line end, relative to its start point. 


═══ <hidden> GRLINE/GCRLINE Parameter - OFF1 ═══

 OFF1 (GDELPOINT) 
    Offset data for second point. 

    This offset is to the second line end, relative to the first line end. 


═══ <hidden> GRLINE/GCRLINE Parameter - OFFN ═══

 OFFN (GDELPOINT) 
    Offset data for final point. 

    This offset is to the nth line end, relative to the n-1th line end. 


═══ <hidden> Relative Line at Given Position/Relative Line at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of line start. 

    This parameter is only present in a Relative Line at Given Position order. 

 OFF0 (GDELPOINT) 
    Offset data for first point. 

    This offset is to the first line end, relative to its start point. 

 OFF1 (GDELPOINT) 
    Offset data for second point. 

    This offset is to the second line end, relative to the first line end. 

 OFFN (GDELPOINT) 
    Offset data for final point. 

    This offset is to the nth line end, relative to the n-1th line end. 


═══ <hidden> Relative Line at Given Position/Relative Line at Current Position - Remarks ═══

The end point of each line is given as an offset from the start of the line, 
rather than as absolute coordinates. 


═══ <hidden> Relative Line at Given Position/Relative Line at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.38. Segment Characteristics ═══


═══ <hidden> Segment Characteristics - Syntax ═══

This order provides the facility to set architected or user-defined 
characteristics for a segment. 

Segment Characteristics (GSGCH) 
X'04' (LEN, CBIT8, PARMS) 


═══ <hidden> GSGCH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSGCH Parameter - CBIT8 ═══

 CBIT8 (GUCHAR) 
    Identification code for characteristics: 

    0x00-0x7F      Reserved for architected characteristics. 
    0x80-0xFF      Reserved for user-defined characteristics. 


═══ <hidden> GSGCH Parameter - PARMS ═══

 PARMS (GSTR) 
    Parameters of characteristics. 


═══ <hidden> Segment Characteristics - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 CBIT8 (GUCHAR) 
    Identification code for characteristics: 

    0x00-0x7F      Reserved for architected characteristics. 
    0x80-0xFF      Reserved for user-defined characteristics. 

 PARMS (GSTR) 
    Parameters of characteristics. 


═══ <hidden> Segment Characteristics - Remarks ═══

The order is only valid in a root-segment prolog. 


═══ <hidden> Segment Characteristics - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.39. Set Arc Parameters/Push and Set Arc Parameters ═══


═══ <hidden> Set Arc Parameters/Push and Set Arc Parameters - Syntax ═══

These orders set, or push and set, the values of the current arc parameters. 

Set Arc Parameters (GSAP) 
X'22' (LEN, P, Q, R, S) 

Push and Set Arc Parameters (GPSAP) 
X'62' (LEN, P, Q, R, S) 


═══ <hidden> GSAP/GPSAP Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSAP/GPSAP Parameter - P ═══

 P (GROSOL) 
    P-parameter of arc transform. 


═══ <hidden> GSAP/GPSAP Parameter - Q ═══

 Q (GROSOL) 
    Q-parameter of arc transform. 


═══ <hidden> GSAP/GPSAP Parameter - R ═══

 R (GROSOL) 
    R-parameter of arc transform. 


═══ <hidden> GSAP/GPSAP Parameter - S ═══

 S (GROSOL) 
    S-parameter of arc transform. 


═══ <hidden> Set Arc Parameters/Push and Set Arc Parameters - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P (GROSOL) 
    P-parameter of arc transform. 

 Q (GROSOL) 
    Q-parameter of arc transform. 

 R (GROSOL) 
    R-parameter of arc transform. 

 S (GROSOL) 
    S-parameter of arc transform. 


═══ <hidden> Set Arc Parameters/Push and Set Arc Parameters - Remarks ═══

The values of the current arc parameters are pushed on to the Segment Call 
stack by the Push and Set order only. Both orders then set the current arc 
parameters to the values specified in the order. 

The value of these parameters determines the shape of subsequent orders drawn 
using Arc at a Given Position/Arc at Current Position or Full Arc at Given 
Position/Full Arc at Current Position or Partial Arc at Given Position/Partial 
Arc at Current Position. 


═══ <hidden> Set Arc Parameters/Push and Set Arc Parameters - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.40. Set Background Color/Push and Set Background Color ═══


═══ <hidden> Set Background Color/Push and Set Background Color - Syntax ═══

These orders set, or push and set, the value of the current background color 
attribute. 

Set Background Color (GSBCOL) 
X'25' (LEN, COLOR) 

Push and Set Background Color (GPSBCOL) 
X'65' (LEN, COLOR) 


═══ <hidden> GSBCOL/GPSBCOL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 


═══ <hidden> GSBCOL/GPSBCOL Parameter - COLOR ═══

 COLOR (GBIT16) 
    Color-table index: Except for the special values, the values 0x0000 through 
    0xnnnn are allowed color indexes; that is, as many values as are allowed by 
    the size of the LCT. 

    Special Values 

    0x0000 
            Drawing default 
    0x0007 
            White 
    0x0008 
            Black 
    0xFF00 
            Drawing default 
    0xFF0x 
            Color indexes 0x000n, where n is in the range 1 through 7. 
    0xFF08 
            Color index 0 (reset color). 


═══ <hidden> Set Background Color/Push and Set Background Color - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 

 COLOR (GBIT16) 
    Color-table index: Except for the special values, the values 0x0000 through 
    0xnnnn are allowed color indexes; that is, as many values as are allowed by 
    the size of the LCT. 

    Special Values 

    0x0000 
            Drawing default 
    0x0007 
            White 
    0x0008 
            Black 
    0xFF00 
            Drawing default 
    0xFF0x 
            Color indexes 0x000n, where n is in the range 1 through 7. 
    0xFF08 
            Color index 0 (reset color). 


═══ <hidden> Set Background Color/Push and Set Background Color - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.41. Set Background Indexed Color/Push and Set Background Indexed Color ═══


═══ <hidden> Set Background Indexed Color/Push and Set Background Indexed Color - Syntax ═══

These orders set, or push and set, the value of the current background color 
attribute. 

Set Background Indexed Color (GSBICOL) 
X'A7' (LEN, FLAGS, INDEX) 

Push and Set Background Indexed Color (GPSBICOL) 
X'E7' (LEN, FLAGS, INDEX) 


═══ <hidden> GSBICOL/GPSBICOL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 


═══ <hidden> GSBICOL/GPSBICOL Parameter - FLAGS ═══

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Use specified INDEX 
             1       Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0       Use index directly 
             1       Special value. 

    RES (GBIT6) 
             Reserved value, must be 0. 


═══ <hidden> GSBICOL/GPSBICOL Parameter - INDEX ═══

 INDEX (GINDEX3) 
    Value for color index. 

    The value is a direct index into the current color table or a special 
    value. The special values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Background Indexed Color/Push and Set Background Indexed Color - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Use specified INDEX 
             1       Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0       Use index directly 
             1       Special value. 

    RES (GBIT6) 
             Reserved value, must be 0. 

 INDEX (GINDEX3) 
    Value for color index. 

    The value is a direct index into the current color table or a special 
    value. The special values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Background Indexed Color/Push and Set Background Indexed Color - Remarks ═══

The value of the current background color attribute is pushed on to the stack 
by the Push and Set order only. Both orders then set the current background 
color attribute to the value specified in the order. 


═══ <hidden> Set Background Indexed Color/Push and Set Background Indexed Color - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.42. Set Background Mix/Push and Set Background Mix ═══


═══ <hidden> Set Background Mix/Push and Set Background Mix - Syntax ═══

These orders set, or push and set, the value of the current background mix 
attribute. 

Set Background Mix (GSBMX) 
X'0D' (MODE) 

Push and Set Background Mix (GPSBMX) 
X'4D' (MODE) 


═══ <hidden> GSBMX/GPSBMX Parameter - MODE ═══

 MODE (GBIT8) 
    Mix-mode value: 

    0x00 
            Drawing default 
    0x01 
            OR 
    0x02 
            Overpaint 
    0x03 
            Reserved 
    0x04 
            Exclusive-OR 
    0x05 
            Leave Alone 
    0x06 
            AND 
    0x07 
            Subtract 
    0x08 
            Source AND (inverse destination) 
    0x09 
            All zeros 
    0x0A 
            Inverse (source OR destination) 
    0x0B 
            Inverse (source XOR destination) 
    0x0C 
            Inverse destination 
    0x0D 
            Source OR (inverse destination) 
    0x0E 
            Inverse source 
    0x0F 
            (Inverse source) OR destination 
    0x10 
            Inverse (source AND destination) 
    0x11 
            All ones. 


═══ <hidden> Set Background Mix/Push and Set Background Mix - Parameters ═══

 MODE (GBIT8) 
    Mix-mode value: 

    0x00 
            Drawing default 
    0x01 
            OR 
    0x02 
            Overpaint 
    0x03 
            Reserved 
    0x04 
            Exclusive-OR 
    0x05 
            Leave Alone 
    0x06 
            AND 
    0x07 
            Subtract 
    0x08 
            Source AND (inverse destination) 
    0x09 
            All zeros 
    0x0A 
            Inverse (source OR destination) 
    0x0B 
            Inverse (source XOR destination) 
    0x0C 
            Inverse destination 
    0x0D 
            Source OR (inverse destination) 
    0x0E 
            Inverse source 
    0x0F 
            (Inverse source) OR destination 
    0x10 
            Inverse (source AND destination) 
    0x11 
            All ones. 


═══ <hidden> Set Background Mix/Push and Set Background Mix - Remarks ═══

The value of the current background mix attribute is pushed on to the Segment 
Call stack by the Push and Set order only. Both orders then set the current 
background mix attribute to the value specified in the order. 


═══ <hidden> Set Background Mix/Push and Set Background Mix - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.43. Set Character Angle/Push and Set Character Angle ═══


═══ <hidden> Set Character Angle/Push and Set Character Angle - Syntax ═══

These orders set, or push and set, the value of the current character angle 
attribute. 

Set Character Angle (GSCA) 
X'34' (LEN, AX, AY) 

Push and Set Character Angle (GPSCA) 
X'74' (LEN, AX, AY) 


═══ <hidden> GSCA/GPSCA Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCA/GPSCA Parameter - AX ═══

 AX (GROSOL) 
    X coordinate of point. 

    This point defines the angle of the character string. 


═══ <hidden> GSCA/GPSCA Parameter - AY ═══

 AY (GROSOL) 
    Y coordinate of point. 

    This point defines the angle of the character string. 


═══ <hidden> Set Character Angle/Push and Set Character Angle - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 AX (GROSOL) 
    X coordinate of point. 

    This point defines the angle of the character string. 

 AY (GROSOL) 
    Y coordinate of point. 

    This point defines the angle of the character string. 


═══ <hidden> Set Character Angle/Push and Set Character Angle - Remarks ═══

The value of the current character angle attribute is pushed on to the Segment 
Call Stack by the Push and Set order only. Both orders then set the value of 
the current character angle to the value specified in the order. 


═══ <hidden> Set Character Angle/Push and Set Character Angle - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.44. Set Character Break Extra/Push and Set Character Break Extra ═══


═══ <hidden> Set Character Break Extra/Push and Set Character Break Extra - Syntax ═══

These orders set, or push and set, the value of the current character break 
extra attribute. 

Set Character Break Extra (GSCBE) 
X'05' (LEN, FLAGS, RES2, INC) 

Push and Set Character Break Extra (GPSCBE) 
X'45' (LEN, FLAGS, RES2, INC) 


═══ <hidden> GSCBE/GPSCBE Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCBE/GPSCBE Parameter - FLAGS ═══

 FLAGS 
    Values as follows: 

    DEFAULT (GBIT1) 
             Values as follows: 

             B"0"       Set to specified value. 
             B"1"       Set to drawing default. 

    RES1 (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSCBE/GPSCBE Parameter - RES2 ═══

 RES2 (GUNDF1) 
    Reserved value, must be 0. 


═══ <hidden> GSCBE/GPSCBE Parameter - INC ═══

 INC (GROF) 
    Increment. 


═══ <hidden> Set Character Break Extra/Push and Set Character Break Extra - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS 
    Values as follows: 

    DEFAULT (GBIT1) 
             Values as follows: 

             B"0"       Set to specified value. 
             B"1"       Set to drawing default. 

    RES1 (GBIT7) 
             Reserved value, must be 0. 

 RES2 (GUNDF1) 
    Reserved value, must be 0. 

 INC (GROF) 
    Increment. 


═══ <hidden> Set Character Break Extra/Push and Set Character Break Extra - Remarks ═══

The value of the current character break extra attribute is pushed on to the 
Segment Call Stack by the Push and Set order only. Both orders then set the 
value of the current character break extra attribute to the value specified in 
the order. 


═══ <hidden> Set Character Break Extra/Push and Set Character Break Extra - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.45. Set Character Cell/Push and Set Character Cell ═══


═══ <hidden> Set Character Cell/Push and Set Character Cell - Syntax ═══

These orders set, or push and set, the value of the current character cell-size 
attribute. 

Set Character Cell (GSCC) 
X'33' (LEN, CELLX, CELLY, CELLXF, CELLYF, FLAGS, RES) 

Push and Set Character Cell (GPSCC) 
X'03' (LEN, CELLX, CELLY, CELLXF, CELLYF, FLAGS, RES) 


═══ <hidden> GSCC/GPSCC Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCC/GPSCC Parameter - CELLX ═══

 CELLX (GROSOL) 
    X part of character cell-size attribute. 


═══ <hidden> GSCC/GPSCC Parameter - CELLY ═══

 CELLY (GROSOL) 
    Y part of character cell-size attribute. 


═══ <hidden> GSCC/GPSCC Parameter - CELLXF ═══

 CELLXF (GUSHORT) 
    Fractional X part of character cell-size attribute. 

    This parameter is optional. 


═══ <hidden> GSCC/GPSCC Parameter - CELLYF ═══

 CELLYF (GUSHORT) 
    Fractional Y part of character cell-size attribute. 

    This parameter must be present if CELLXF parameter is present. 


═══ <hidden> GSCC/GPSCC Parameter - FLAGS ═══

 FLAGS 
    Internal flags. 

    This parameter is optional. 

    NOTDEFLT (GBIT1) 
             Values: 

             0       A cell size of zero sets drawing default 
             1       A cell size of zero sets to zero. 

    RES (GBIT7) 
             Reserved. 

             0000000 Only valid value. 


═══ <hidden> GSCC/GPSCC Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 

    This parameter must be present if FLAGS parameter is present. 


═══ <hidden> Set Character Cell/Push and Set Character Cell - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 CELLX (GROSOL) 
    X part of character cell-size attribute. 

 CELLY (GROSOL) 
    Y part of character cell-size attribute. 

 CELLXF (GUSHORT) 
    Fractional X part of character cell-size attribute. 

    This parameter is optional. 

 CELLYF (GUSHORT) 
    Fractional Y part of character cell-size attribute. 

    This parameter must be present if CELLXF parameter is present. 

 FLAGS 
    Internal flags. 

    This parameter is optional. 

    NOTDEFLT (GBIT1) 
             Values: 

             0       A cell size of zero sets drawing default 
             1       A cell size of zero sets to zero. 

    RES (GBIT7) 
             Reserved. 

             0000000 Only valid value. 

 RES (GBIT8) 
    Reserved value, must be 0. 

    This parameter must be present if FLAGS parameter is present. 


═══ <hidden> Set Character Cell/Push and Set Character Cell - Remarks ═══

The value of the current character cell-size attribute is pushed on to the 
Segment Call Stack by the Push and Set order only. Both orders then set the 
value of the current character cell-size attribute to the value in the order. 


═══ <hidden> Set Character Cell/Push and Set Character Cell - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.46. Set Character Direction/Push and Set Character Direction ═══


═══ <hidden> Set Character Direction/Push and Set Character Direction - Syntax ═══

These orders set, or push and set, the value of the current character direction 
attribute. 

Set Character Direction (GSCD) 
X'3A' (DIRECTION) 

Push and Set Character Direction (GPSCD) 
X'7A' (DIRECTION) 


═══ <hidden> GSCD/GPSCD Parameter - DIRECTION ═══

 DIRECTION (GBIT8) 
    Value for character direction: 

    All other values are reserved. 

    0x00       Drawing default 
    0x01       Left to right 
    0x02       Top to bottom 
    0x03       Right to left 
    0x04       Bottom to top. 


═══ <hidden> Set Character Direction/Push and Set Character Direction - Parameters ═══

 DIRECTION (GBIT8) 
    Value for character direction: 

    All other values are reserved. 

    0x00       Drawing default 
    0x01       Left to right 
    0x02       Top to bottom 
    0x03       Right to left 
    0x04       Bottom to top. 


═══ <hidden> Set Character Direction/Push and Set Character Direction - Remarks ═══

The value of the current character direction attribute is pushed on to the 
Segment Call Stack by the Push and Set order only. Both orders then set the 
value of the current character direction attribute to the value in the order. 


═══ <hidden> Set Character Direction/Push and Set Character Direction - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.47. Set Character Extra/Push and Set Character Extra ═══


═══ <hidden> Set Character Extra/Push and Set Character Extra - Syntax ═══

These orders set, or push and set, the value of the current character extra 
attribute. 

Set Character Extra (GSCE) 
X'17' (LEN, FLAGS, RES2, INC) 

Push and Set Character Extra (GPSCE) 
X'57' (LEN, FLAGS, RES2, INC) 


═══ <hidden> GSCE/GPSCE Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCE/GPSCE Parameter - FLAGS ═══

 FLAGS 
    Values as follows: 

    DEFAULT (GBIT1) 
             Values as follows: 

             B"0"      Set to specified value. 
             B"1"      Set to drawing default. 

    RES1 (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSCE/GPSCE Parameter - RES2 ═══

 RES2 (GUNDF1) 
    Reserved value, must be 0. 


═══ <hidden> GSCE/GPSCE Parameter - INC ═══

 INC (GROF) 
    Increment. 


═══ <hidden> Set Character Extra/Push and Set Character Extra - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS 
    Values as follows: 

    DEFAULT (GBIT1) 
             Values as follows: 

             B"0"      Set to specified value. 
             B"1"      Set to drawing default. 

    RES1 (GBIT7) 
             Reserved value, must be 0. 

 RES2 (GUNDF1) 
    Reserved value, must be 0. 

 INC (GROF) 
    Increment. 


═══ <hidden> Set Character Extra/Push and Set Character Extra - Remarks ═══

The value of the current character extra attribute is pushed on to the Segment 
Call Stack by the Push and Set order only. Both orders set the value of the 
current character extra attribute to the value specified in the order. 


═══ <hidden> Set Character Extra/Push and Set Character Extra - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.48. Set Character Precision/Push and Set Character Precision ═══


═══ <hidden> Set Character Precision/Push and Set Character Precision - Syntax ═══

These orders set, or push and set, the value of the current character precision 
attribute. 

Set Character Precision (GSCR) 
X'39' (PREC) 

Push and Set Character Precision (GPSCR) 
X'79' (PREC) 


═══ <hidden> GSCR/GPSCR Parameter - PREC ═══

 PREC (GBIT8) 
    Value for character-precision attribute: 

    All other values are reserved. 

    0x00       Drawing default 
    0x01       String precision 
    0x02       Character precision 
    0x03       Stroke precision 


═══ <hidden> Set Character Precision/Push and Set Character Precision - Parameters ═══

 PREC (GBIT8) 
    Value for character-precision attribute: 

    All other values are reserved. 

    0x00       Drawing default 
    0x01       String precision 
    0x02       Character precision 
    0x03       Stroke precision 


═══ <hidden> Set Character Precision/Push and Set Character Precision - Remarks ═══

The value of the current character precision attribute is pushed on to the 
Segment Call Stack by the Push and Set order only. Both orders then set the 
value of the current character precision attribute to the value in the order. 


═══ <hidden> Set Character Precision/Push and Set Character Precision - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.49. Set Character Set/Push and Set Character Set ═══


═══ <hidden> Set Character Set/Push and Set Character Set - Syntax ═══

These orders set, or push and set, the value of the current character-set 
attribute. 

Set Character Set (GSCS) 
X'38' (LCID) 

Push and Set Character Set (GPSCS) 
X'78' (LCID) 


═══ <hidden> GSCS/GPSCS Parameter - LCID ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the character set: 

    0x00          Drawing default 
    0x01-0xFE     Lcid for the symbol set 
    0xFF          Special character set. 


═══ <hidden> Set Character Set/Push and Set Character Set - Parameters ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the character set: 

    0x00          Drawing default 
    0x01-0xFE     Lcid for the symbol set 
    0xFF          Special character set. 


═══ <hidden> Set Character Set/Push and Set Character Set - Remarks ═══

The value of the current character-set attribute is pushed on to the Segment 
Call Stack by the Push and Set order only. Both orders then set the value of 
the current character-set attribute to the value in the order. 


═══ <hidden> Set Character Set/Push and Set Character Set - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.50. Set Character Shear/Push and Set Character Shear ═══


═══ <hidden> Set Character Shear/Push and Set Character Shear - Syntax ═══

These orders set, or push and set, the value of the current character shear 
attribute. 

Set Character Shear (GSCH) 
X'35' (LEN, HX, HY) 

Push and Set Character Shear (GPSCH) 
X'75' (LEN, HX, HY) 


═══ <hidden> GSCH/GPSCH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCH/GPSCH Parameter - HX ═══

 HX (GROSOL) 
    Dividend of shear ratio. 


═══ <hidden> GSCH/GPSCH Parameter - HY ═══

 HY (GROSOL) 
    Divisor of shear ratio. 


═══ <hidden> Set Character Shear/Push and Set Character Shear - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 HX (GROSOL) 
    Dividend of shear ratio. 

 HY (GROSOL) 
    Divisor of shear ratio. 


═══ <hidden> Set Character Shear/Push and Set Character Shear - Remarks ═══

When HX and HY are both 0, the drawing default is set. The value of the current 
character shear attribute is pushed on to the Segment Call Stack by the Push 
and Set order only. Both orders then set the value of the current character 
shear attribute to the value in the order. 


═══ <hidden> Set Character Shear/Push and Set Character Shear - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.51. Set Clip Path ═══


═══ <hidden> Set Clip Path - Syntax ═══

This order sets the current clip path. 

Set Clip Path (GSCPTH) 
X'B4' (LEN, FLAGS, RES, PTHID) 


═══ <hidden> GSCPTH Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCPTH Parameter - FLAGS ═══

 FLAGS 
    Extra functions: 

    RES (GBIT1) 
             Reserved value, must be 0. 

    FILL (GBIT1) 
             Values: 

             0       Alternate mode 
             1       Winding mode. 

    INTER (GBIT1) 
             Values: 

             0       Set to specified path 
             1       Set to intersection of specified and current clip path. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 


═══ <hidden> GSCPTH Parameter - RES ═══

 RES (GBIT8) 
    Reserved. 

    0x00    Only valid value. 


═══ <hidden> GSCPTH Parameter - PTHID ═══

 PTHID (GLONG) 
    Path identifier. 

    0x00000000              No clipping. 
    0x00000001-0xFFFFFFFF   Path identifier. 


═══ <hidden> Set Clip Path - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS 
    Extra functions: 

    RES (GBIT1) 
             Reserved value, must be 0. 

    FILL (GBIT1) 
             Values: 

             0       Alternate mode 
             1       Winding mode. 

    INTER (GBIT1) 
             Values: 

             0       Set to specified path 
             1       Set to intersection of specified and current clip path. 

    RES2 (GBIT5) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved. 

    0x00    Only valid value. 

 PTHID (GLONG) 
    Path identifier. 

    0x00000000              No clipping. 
    0x00000001-0xFFFFFFFF   Path identifier. 


═══ <hidden> Set Clip Path - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.52. Set Color/Push and Set Color ═══


═══ <hidden> Set Color/Push and Set Color - Syntax ═══

These orders set, or push and set, the value of the current color attribute. 

Set Color (GSCOL) 
X'0A' (COL) 

Push and Set Color (GPSCOL) 
X'4A' (COL) 


═══ <hidden> GSCOL/GPSCOL Parameter - COL ═══

 COL (GBIT8) 
    Value for color attribute: 

    0x00-0x08     These one-byte values are converted to two-byte values by 
                  preceding the value with 0xFF. The resultant is then treated 
                  as a two-byte value as defined by the Set Extended Color/Push 
                  and Set Extended Color order. 
    Other         Reserved values. 


═══ <hidden> Set Color/Push and Set Color - Parameters ═══

 COL (GBIT8) 
    Value for color attribute: 

    0x00-0x08     These one-byte values are converted to two-byte values by 
                  preceding the value with 0xFF. The resultant is then treated 
                  as a two-byte value as defined by the Set Extended Color/Push 
                  and Set Extended Color order. 
    Other         Reserved values. 


═══ <hidden> Set Color/Push and Set Color - Remarks ═══

The value of the current color attribute is pushed on to the Segment Call Stack 
by the Push and Set order only. Both orders then set the value of the current 
color attribute to the value in the order. 


═══ <hidden> Set Color/Push and Set Color - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.53. Set Current Position/Push and Set Current Position ═══


═══ <hidden> Set Current Position/Push and Set Current Position - Syntax ═══

These orders set, or push and set, the value of the current position. 

Set Current Position (GSCP) 
X'21' (LEN, P) 

Push and Set Current Position (GPSCP) 
X'61' (LEN, P) 


═══ <hidden> GSCP/GPSCP Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCP/GPSCP Parameter - P ═══

 P (GPOINT) 
    Coordinate data. 


═══ <hidden> Set Current Position/Push and Set Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P (GPOINT) 
    Coordinate data. 


═══ <hidden> Set Current Position/Push and Set Current Position - Remarks ═══

The value of the current position is pushed on to the Segment Call Stack by the 
Push and Set order only. Both orders then set the value of the current position 
to the value in the order. 


═══ <hidden> Set Current Position/Push and Set Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.54. Set Extended Color/Push and Set Extended Color ═══


═══ <hidden> Set Extended Color/Push and Set Extended Color - Syntax ═══

These orders set, or push and set, the value of the current color attribute. 

Set Extended Color (GSECOL) 
X'26' (LEN, COLOR) 

Push and Set Extended Color (GPSECOL) 
X'66' (LEN, COLOR) 


═══ <hidden> GSECOL/GPSECOL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 


═══ <hidden> GSECOL/GPSECOL Parameter - COLOR ═══

 COLOR (GBIT16) 
    Color-table index. Except for the special values, the values 0x0000 through 
    0xnnnn are allowed color indexes; that is, as many values as are allowed by 
    the size of the LCT. 

 Special Values 

    0x0000 
            Drawing default 
    0x0007 
            White 
    0x0008 
            Black 
    0xFF00 
            Drawing default 
    0xFF0n 
            Color indexes 0x000n, where n is in the range 1 through 7. 
    0xFF08 
            Color index 0 (reset color). 


═══ <hidden> Set Extended Color/Push and Set Extended Color - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 

 COLOR (GBIT16) 
    Color-table index. Except for the special values, the values 0x0000 through 
    0xnnnn are allowed color indexes; that is, as many values as are allowed by 
    the size of the LCT. 

 Special Values 

    0x0000 
            Drawing default 
    0x0007 
            White 
    0x0008 
            Black 
    0xFF00 
            Drawing default 
    0xFF0n 
            Color indexes 0x000n, where n is in the range 1 through 7. 
    0xFF08 
            Color index 0 (reset color). 


═══ <hidden> Set Extended Color/Push and Set Extended Color - Remarks ═══

The value of the current extended color attribute is pushed on to the Segment 
Call Stack by the Push and Set order only. Both orders then set the value of 
the current extended color attribute to the value in the order. 


═══ <hidden> Set Extended Color/Push and Set Extended Color - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.55. Set Fractional Line Width/Push and Set Fractional Line Width ═══


═══ <hidden> Set Fractional Line Width/Push and Set Fractional Line Width - Syntax ═══

These orders set, or push and set, the value of the current line-width 
attribute. 

Set Fractional Line Width (GSFLW) 
X'11' (LEN, LINEWIDTH) 

Push and Set Fractional Line Width (GPSFLW) 
X'51' (LEN, LINEWIDTH) 


═══ <hidden> GSFLW/GPSFLW Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 


═══ <hidden> GSFLW/GPSFLW Parameter - LINEWIDTH ═══

 LINEWIDTH (GROUFS) 
    Value for the line-width attribute. 

    The nonzero value is an integral and fractional multiplier of the normal 
    line width: 

    0x0000            Drawing default 
    0x0001-0xFFFF     Multiplier of normal line width. 


═══ <hidden> Set Fractional Line Width/Push and Set Fractional Line Width - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x02    Only valid value. 

 LINEWIDTH (GROUFS) 
    Value for the line-width attribute. 

    The nonzero value is an integral and fractional multiplier of the normal 
    line width: 

    0x0000            Drawing default 
    0x0001-0xFFFF     Multiplier of normal line width. 


═══ <hidden> Set Fractional Line Width/Push and Set Fractional Line Width - Remarks ═══

The value of the current line-width attribute is pushed on to the Segment Call 
Stack by the Push and Set order only. Both orders then set the value of the 
current line-width attribute to the value in the order. 


═══ <hidden> Set Fractional Line Width/Push and Set Fractional Line Width - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.56. Set Indexed Color/Push and Set Indexed Color ═══


═══ <hidden> Set Indexed Color/Push and Set Indexed Color - Syntax ═══

These orders set, or push and set, the value of the current color attribute. 

Set Indexed Color (GSICOL) 
X'A6' (LEN, FLAGS, INDEX) 

Push and Set Indexed Color (GPSICOL) 
X'E6' (LEN, FLAGS, INDEX) 


═══ <hidden> GSICOL/GPSICOL Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 


═══ <hidden> GSICOL/GPSICOL Parameter - FLAGS ═══

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Use specified index 
             1       Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0       Use index directly 
             1       Special value. 

    RES (GBIT6) 
             Reserved value, must be 0. 


═══ <hidden> GSICOL/GPSICOL Parameter - INDEX ═══

 INDEX (GINDEX3) 
    Value for color index. 

    The value is a direct index into the current color table or a special 
    value. 

    The table can be the standard table, or one loaded by the user. The special 
    values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Indexed Color/Push and Set Indexed Color - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

    0x04    Only valid value. 

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Use specified index 
             1       Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0       Use index directly 
             1       Special value. 

    RES (GBIT6) 
             Reserved value, must be 0. 

 INDEX (GINDEX3) 
    Value for color index. 

    The value is a direct index into the current color table or a special 
    value. 

    The table can be the standard table, or one loaded by the user. The special 
    values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Indexed Color/Push and Set Indexed Color - Remarks ═══

The value of the current color attribute is pushed on to the Segment Call Stack 
by the Push and Set order only. Both orders then set the value of the current 
color attribute to the value in the order. 


═══ <hidden> Set Indexed Color/Push and Set Indexed Color - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.57. Set Individual Attribute/Push and Set Individual Attribute ═══


═══ <hidden> Set Individual Attribute/Push and Set Individual Attribute - Syntax ═══

These orders set, or push and set, the value of the color, background color, 
mix, or background mix attribute for the line character, marker, pattern, or 
image primitive type. 

Set Individual Attribute (GSIA) 
X'14' (LEN, ATYPE, PTYPE, FLAG1, VAL) 

Push and Set Individual Attribute (GPSIA) 
X'54' (LEN, ATYPE, PTYPE, FLAG1, VAL) 


═══ <hidden> GSIA/GPSIA Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSIA/GPSIA Parameter - ATYPE ═══

 ATYPE (GBIT8) 
    Attribute type: 

    0x1        Color 
    0x2        Background color 
    0x3        Mix 
    0x4        Background Mix 
    Other      All other values are reserved. 


═══ <hidden> GSIA/GPSIA Parameter - PTYPE ═══

 PTYPE (GBIT8) 
    Primitive type: 

    0x1 
            Line 
    0x2 
            Character 
    0x3 
            Marker 
    0x4 
            Pattern 
    0x5 
            Image 
    Other 
            All other values are reserved. 


═══ <hidden> GSIA/GPSIA Parameter - FLAG1 ═══

 FLAG1 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0 
                     Use specified value 
             1 
                     Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0 
                     Use value directly 
             1 
                     Special Value. 

    RES (GBIT6) 
             Reserved value, must be 0. 


═══ <hidden> GSIA/GPSIA Parameter - VAL ═══

 VAL (GINDATT) 
    Color index value. 

    For colors, the value is a direct index into the current color table or a 
    special value. 

    The table can be the standard table, or one loaded by the user. The special 
    values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Individual Attribute/Push and Set Individual Attribute - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 ATYPE (GBIT8) 
    Attribute type: 

    0x1        Color 
    0x2        Background color 
    0x3        Mix 
    0x4        Background Mix 
    Other      All other values are reserved. 

 PTYPE (GBIT8) 
    Primitive type: 

    0x1 
            Line 
    0x2 
            Character 
    0x3 
            Marker 
    0x4 
            Pattern 
    0x5 
            Image 
    Other 
            All other values are reserved. 

 FLAG1 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0 
                     Use specified value 
             1 
                     Use drawing default color. 

    SPEC (GBIT1) 
             Options: 

             0 
                     Use value directly 
             1 
                     Special Value. 

    RES (GBIT6) 
             Reserved value, must be 0. 

 VAL (GINDATT) 
    Color index value. 

    For colors, the value is a direct index into the current color table or a 
    special value. 

    The table can be the standard table, or one loaded by the user. The special 
    values are: 

    1 
            Black 
    2 
            White 
    4 
            All ones 
    5 
            All zeros. 


═══ <hidden> Set Individual Attribute/Push and Set Individual Attribute - Remarks ═══

The value of the current attribute is pushed on to the Segment Call Stack by 
the Push and Set order only. Both orders then set the value of the individual 
attribute to the value in the order. 


═══ <hidden> Set Individual Attribute/Push and Set Individual Attribute - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.58. Set Line End/Push and Set Line End ═══


═══ <hidden> Set Line End/Push and Set Line End - Syntax ═══

These orders set, or push and set, the value of the current line-end attribute. 

Set Line End (GSLE) 
X'1A' (LINEEND) 

Push and Set Line End (GPSLE) 
X'5A' (LINEEND) 


═══ <hidden> GSLE/GPSLE Parameter - LINEEND ═══

 LINEEND (GBIT8) 
    Value for the line-end attribute: 

    0x00       Drawing default 
    0x01       Flat 
    0x02       Square 
    0x03       Round 
    Other      Reserved values. 


═══ <hidden> Set Line End/Push and Set Line End - Parameters ═══

 LINEEND (GBIT8) 
    Value for the line-end attribute: 

    0x00       Drawing default 
    0x01       Flat 
    0x02       Square 
    0x03       Round 
    Other      Reserved values. 


═══ <hidden> Set Line End/Push and Set Line End - Remarks ═══

The value of the current line-end attribute is pushed on to the Segment Call 
Stack by the Push and Set order only. Both orders then set the value of the 
current line-end attribute to the value in the order. 


═══ <hidden> Set Line End/Push and Set Line End - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.59. Set Line Join/Push and Set Line Join ═══


═══ <hidden> Set Line Join/Push and Set Line Join - Syntax ═══

These orders set the value of the current line-join attribute. 

Set Line Join (GSLJ) 
X'1B' (LINEJOIN) 

Push and Set Line Join (GPSLJ) 
X'5B' (LINEJOIN) 


═══ <hidden> GSLJ/GPSLJ Parameter - LINEJOIN ═══

 LINEJOIN (GBIT8) 
    Value for line-join attribute: 

    0x00       Drawing default 
    0x01       Bevel 
    0x02       Round 
    0x03       Miter 
    Other      Reserved values. 


═══ <hidden> Set Line Join/Push and Set Line Join - Parameters ═══

 LINEJOIN (GBIT8) 
    Value for line-join attribute: 

    0x00       Drawing default 
    0x01       Bevel 
    0x02       Round 
    0x03       Miter 
    Other      Reserved values. 


═══ <hidden> Set Line Join/Push and Set Line Join - Remarks ═══

The value of the current line-join attribute is pushed on to the Segment Call 
stack by the Push and Set order only. Both orders then set the value of the 
current line-join attribute to the value in the order. 


═══ <hidden> Set Line Join/Push and Set Line Join - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.60. Set Line Type/Push and Set Line Type ═══


═══ <hidden> Set Line Type/Push and Set Line Type - Syntax ═══

These orders set, or push and set, the value of the current line-type 
attribute. 

Set Line Type (GSLT) 
X'18' (LINETYPE) 

Push and Set Line Type (GPSLT) 
X'58' (LINETYPE) 


═══ <hidden> GSLT/GPSLT Parameter - LINETYPE ═══

 LINETYPE (GBIT8) 
    Value for line-type attribute. 

    The value is an index into a notational line-type table: 

    0x00       Drawing default 
    0x01       Dotted line 
    0x02       Short dashed line 
    0x03       Dash-dot line 
    0x04       Double dotted line 
    0x05       Long dashed line 
    0x06       Dash-double-dot line 
    0x07       Solid line 
    0x08       Invisible line 
    Other      Reserved values. 


═══ <hidden> Set Line Type/Push and Set Line Type - Parameters ═══

 LINETYPE (GBIT8) 
    Value for line-type attribute. 

    The value is an index into a notational line-type table: 

    0x00       Drawing default 
    0x01       Dotted line 
    0x02       Short dashed line 
    0x03       Dash-dot line 
    0x04       Double dotted line 
    0x05       Long dashed line 
    0x06       Dash-double-dot line 
    0x07       Solid line 
    0x08       Invisible line 
    Other      Reserved values. 


═══ <hidden> Set Line Type/Push and Set Line Type - Remarks ═══

The value of the current line-type attribute is pushed on to the Segment Call 
Stack by the Push and Set order only. Both orders then set the value of the 
current line-type attribute to the value in the order. 


═══ <hidden> Set Line Type/Push and Set Line Type - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.61. Set Line Width/Push and Set Line Width ═══


═══ <hidden> Set Line Width/Push and Set Line Width - Syntax ═══

These orders set, or push and set, the value of the current line-width 
attribute to the value specified in the order. 

Set Line Width (GSLW) 
X'19' (LINEWIDTH) 

Push and Set Line Width (GPSLW) 
X'59' (LINEWIDTH) 


═══ <hidden> GSLW/GPSLW Parameter - LINEWIDTH ═══

 LINEWIDTH (GBIT8) 
    Value for line-width attribute: 

    0x00          Drawing default 
    0x01-0xFF     Integral multiplier of normal line width. 


═══ <hidden> Set Line Width/Push and Set Line Width - Parameters ═══

 LINEWIDTH (GBIT8) 
    Value for line-width attribute: 

    0x00          Drawing default 
    0x01-0xFF     Integral multiplier of normal line width. 


═══ <hidden> Set Line Width/Push and Set Line Width - Remarks ═══

The value of the current line-width attribute is pushed on to the Segment Call 
stack by the Push and Set order only. Both orders then set the value of the 
current line-width attribute to the value in the order. 


═══ <hidden> Set Line Width/Push and Set Line Width - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.62. Set Marker Cell/Push and Set Marker Cell ═══


═══ <hidden> Set Marker Cell/Push and Set Marker Cell - Syntax ═══

These orders set, or push and set, the value of the current marker cell-size 
attribute. 

Set Marker Cell (GSMC) 
X'37' (LEN, CELLX, CELLY, FLAGS, RES) 

Push and Set Marker Cell (GPSMC) 
X'77' (LEN, CELLX, CELLY, FLAGS, RES) 


═══ <hidden> GSMC/GPSMC Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSMC/GPSMC Parameter - CELLX ═══

 CELLX (GROSOL) 
    X part of marker cell-size attribute. 


═══ <hidden> GSMC/GPSMC Parameter - CELLY ═══

 CELLY (GROSOL) 
    Y part of marker cell-size attribute. 


═══ <hidden> GSMC/GPSMC Parameter - FLAGS ═══

 FLAGS 
    This is an optional extension. 

    Values: 

    NOTDEFLT (GBIT1) 
             Options: 

             0       A cell size of zero sets drawing default 
             1       A cell size of zero sets to zero. 

    RES (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSMC/GPSMC Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Set Marker Cell/Push and Set Marker Cell - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 CELLX (GROSOL) 
    X part of marker cell-size attribute. 

 CELLY (GROSOL) 
    Y part of marker cell-size attribute. 

 FLAGS 
    This is an optional extension. 

    Values: 

    NOTDEFLT (GBIT1) 
             Options: 

             0       A cell size of zero sets drawing default 
             1       A cell size of zero sets to zero. 

    RES (GBIT7) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> Set Marker Cell/Push and Set Marker Cell - Remarks ═══

The value of the current marker cell-size attribute is pushed on to the Segment 
Call stack by the Push and Set order only. Both orders then set the value of 
the current marker cell-size attribute to the value in the order. 


═══ <hidden> Set Marker Cell/Push and Set Marker Cell - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.63. Set Marker Precision/Push and Set Marker Precision ═══


═══ <hidden> Set Marker Precision/Push and Set Marker Precision - Syntax ═══

These orders set, or push and set, the value of the current marker-precision 
attribute. 

Set Marker Precision (GSMP) 
X'3B' (PREC) 

Push and Set Marker Precision (GPSMP) 
X'7B' (PREC) 


═══ <hidden> GSMP/GPSMP Parameter - PREC ═══

 PREC (GBIT8) 
    Value for marker-precision attribute: 

    0x00       Drawing default 
    0x01       String precision 
    0x02       Character precision 
    0x03       Stroke precision 
    Other      Reserved values. 


═══ <hidden> Set Marker Precision/Push and Set Marker Precision - Parameters ═══

 PREC (GBIT8) 
    Value for marker-precision attribute: 

    0x00       Drawing default 
    0x01       String precision 
    0x02       Character precision 
    0x03       Stroke precision 
    Other      Reserved values. 


═══ <hidden> Set Marker Precision/Push and Set Marker Precision - Remarks ═══

The value of the current marker-precision attribute is pushed on to the Segment 
Call stack by the Push and Set order only. Both orders then set the value of 
the current-marker precision attribute to the value in the order. 


═══ <hidden> Set Marker Precision/Push and Set Marker Precision - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.64. Set Marker Set/Push and Set Marker Set ═══


═══ <hidden> Set Marker Set/Push and Set Marker Set - Syntax ═══

These orders set, or push and set, the value of the current marker symbol-set 
attribute. 

Set Marker Set (GSMS) 
X'3C' (LCID) 

Push and Set Marker Set (GPSMS) 
X'7C' (LCID) 


═══ <hidden> GSMS/GPSMS Parameter - LCID ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the marker set: 

    0x00          Drawing default 
    0x01-0xFE     LCID for the coded font 
    0xFF          Special marker set. 


═══ <hidden> Set Marker Set/Push and Set Marker Set - Parameters ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the marker set: 

    0x00          Drawing default 
    0x01-0xFE     LCID for the coded font 
    0xFF          Special marker set. 


═══ <hidden> Set Marker Set/Push and Set Marker Set - Remarks ═══

The value of the current marker symbol-set attribute is pushed on to the 
Segment Call stack by the Push and Set order only. Both orders then set the 
value of the current marker symbol-set attribute to the value in the order. 


═══ <hidden> Set Marker Set/Push and Set Marker Set - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.65. Set Marker Symbol/Push and Set Marker Symbol ═══


═══ <hidden> Set Marker Symbol/Push and Set Marker Symbol - Syntax ═══

These orders set, or push and set, the value of the current marker symbol 
attribute. 

Set Marker Symbol (GSMT) 
X'29' (N) 

Push and Set Marker Symbol (GPSMT) 
X'69' (N) 


═══ <hidden> GSMT/GPSMT Parameter - N ═══

 N (GBIT8) 
    Value of marker symbol code point. Special marker set 

    When this is selected (lcid = 0xFF), the values are: 

    0x00 
            Drawing default 
    0x01 
            Cross 
    0x02 
            Plus 
    0x03 
            Diamond 
    0x04 
            Square 
    0x05 
            6-point star 
    0x06 
            8-point star 
    0x07 
            Filled diamond 
    0x08 
            Filled square 
    0x09 
            Dot 
    0x0A 
            Small circle 
    0x40 
            Blank 
    Other 
            Reserved values. 
 Marker set 

            Values are as follows for any other set: 
    0x00 
            Drawing default 
    0x01-0xFF 
            These are the code points into the current marker set. 


═══ <hidden> Set Marker Symbol/Push and Set Marker Symbol - Parameters ═══

 N (GBIT8) 
    Value of marker symbol code point. Special marker set 

    When this is selected (lcid = 0xFF), the values are: 

    0x00 
            Drawing default 
    0x01 
            Cross 
    0x02 
            Plus 
    0x03 
            Diamond 
    0x04 
            Square 
    0x05 
            6-point star 
    0x06 
            8-point star 
    0x07 
            Filled diamond 
    0x08 
            Filled square 
    0x09 
            Dot 
    0x0A 
            Small circle 
    0x40 
            Blank 
    Other 
            Reserved values. 
 Marker set 

            Values are as follows for any other set: 
    0x00 
            Drawing default 
    0x01-0xFF 
            These are the code points into the current marker set. 


═══ <hidden> Set Marker Symbol/Push and Set Marker Symbol - Remarks ═══

The value of the current marker symbol attribute is pushed on to the Segment 
Call Stack by the Push and Set order only. Both orders then set the value of 
the current marker symbol attribute to the value in the order. 


═══ <hidden> Set Marker Symbol/Push and Set Marker Symbol - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.66. Set Mix/Push and Set Mix ═══


═══ <hidden> Set Mix/Push and Set Mix - Syntax ═══

These orders set, or push and set, the value of the current mix attribute. 

Set Mix (GSMX) 
X'0C' (MODE) 

Push and Set Mix (GPSMX) 
X'4C' (MODE) 


═══ <hidden> GSMX/GPSMX Parameter - MODE ═══

 MODE (GBIT8) 
    Mix-mode value: 

    0x00       Drawing default 
    0x01       OR 
    0x02       Overpaint 
    0x03       Reserved 
    0x04       Exclusive-OR 
    0x05       Leave alone 
    0x06       AND 
    0x07       Subtract 
    0x08       Source AND (inverse destination) 
    0x09       All zeros 
    0x0A       Inverse (source OR destination) 
    0x0B       Inverse (source XOR destination) 
    0x0C       Inverse destination 
    0x0D       Source OR (inverse destination) 
    0x0E       Inverse source 
    0x0F       (Inverse source) OR destination 
    0x10       Inverse (source AND destination) 
    0x11       All ones. 
    Other      Reserved values. 


═══ <hidden> Set Mix/Push and Set Mix - Parameters ═══

 MODE (GBIT8) 
    Mix-mode value: 

    0x00       Drawing default 
    0x01       OR 
    0x02       Overpaint 
    0x03       Reserved 
    0x04       Exclusive-OR 
    0x05       Leave alone 
    0x06       AND 
    0x07       Subtract 
    0x08       Source AND (inverse destination) 
    0x09       All zeros 
    0x0A       Inverse (source OR destination) 
    0x0B       Inverse (source XOR destination) 
    0x0C       Inverse destination 
    0x0D       Source OR (inverse destination) 
    0x0E       Inverse source 
    0x0F       (Inverse source) OR destination 
    0x10       Inverse (source AND destination) 
    0x11       All ones. 
    Other      Reserved values. 


═══ <hidden> Set Mix/Push and Set Mix - Remarks ═══

The value of the current mix attribute is pushed on to the Segment Call stack 
by the Push and Set order only. Both orders then set the value of the current 
mix attribute to the value in the order. 


═══ <hidden> Set Mix/Push and Set Mix - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.67. Set Model Transform/Push and Set Model Transform ═══


═══ <hidden> Set Model Transform/Push and Set Model Transform - Syntax ═══

These orders set, or push and set, values in the current model transform. 

Set Model Transform (GSTM) 
X'24' (LEN, RES, FLAGS, MASK, MX[LEN]) 

Push and Set Model Transform (GPSTM) 
X'64' (LEN, RES, FLAGS, MASK, MX[LEN]) 


═══ <hidden> GSTM/GPSTM Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSTM/GPSTM Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GSTM/GPSTM Parameter - FLAGS ═══

 FLAGS 
    Values: 

    RES (GBIT6) 
             Reserved value, must be 0. 

    CM (GBIT2) 
             Matrix control bits: 

             B"00"      Unity matrix 
             B"01"      Concatenate after 
             B"10"      Concatenate before 
             B"11"      Overwrite. 


═══ <hidden> GSTM/GPSTM Parameter - MASK ═══

 MASK (GBIT16) 
    Load mask. 


═══ <hidden> GSTM/GPSTM Parameter - MX[LEN] ═══

 MX[LEN] (GROSOL) 
    Matrix values. 

    The matrix size is based on the number of bits set in MASK. 


═══ <hidden> Set Model Transform/Push and Set Model Transform - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 FLAGS 
    Values: 

    RES (GBIT6) 
             Reserved value, must be 0. 

    CM (GBIT2) 
             Matrix control bits: 

             B"00"      Unity matrix 
             B"01"      Concatenate after 
             B"10"      Concatenate before 
             B"11"      Overwrite. 

 MASK (GBIT16) 
    Load mask. 

 MX[LEN] (GROSOL) 
    Matrix values. 

    The matrix size is based on the number of bits set in MASK. 


═══ <hidden> Set Model Transform/Push and Set Model Transform - Remarks ═══

The value of the current model transform is pushed on to the Segment Call stack 
by the Push and Set order only. Both orders then set values in the current 
model transform as specified in the order. 


═══ <hidden> Set Model Transform/Push and Set Model Transform - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.68. Set Pattern Reference Point/Push and Set Pattern Reference Point ═══


═══ <hidden> Set Pattern Reference Point/Push and Set Pattern Reference Point - Syntax ═══

These orders set, or push and set, the value of the current pattern 
reference-point attribute. 

Set Pattern Reference Point (GSPRP) 
X'A0' (LEN, FLAGS, RES, PREF) 

Push and Set Pattern Reference Point (GPSPRP) 
X'E0' (LEN, FLAGS, RES, PREF) 


═══ <hidden> GSPRP/GPSPRP Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSPRP/GPSPRP Parameter - FLAGS ═══

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Set to specified value 
             1       Set to the drawing default. 

    RES (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSPRP/GPSPRP Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GSPRP/GPSPRP Parameter - PREF ═══

 PREF (GPOINT) 
    Coordinate data of the pattern-reference point. 


═══ <hidden> Set Pattern Reference Point/Push and Set Pattern Reference Point - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS 
    Values: 

    DEFAULT (GBIT1) 
             Options: 

             0       Set to specified value 
             1       Set to the drawing default. 

    RES (GBIT7) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 PREF (GPOINT) 
    Coordinate data of the pattern-reference point. 


═══ <hidden> Set Pattern Reference Point/Push and Set Pattern Reference Point - Remarks ═══

The value of the current pattern reference-point attribute is pushed on to the 
Segment Call stack by the Push and Set order only. Both orders then set the 
value of the current reference-point attribute to the value in the order. 


═══ <hidden> Set Pattern Reference Point/Push and Set Pattern Reference Point - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.69. Set Pattern Set/Push and Set Pattern Set ═══


═══ <hidden> Set Pattern Set/Push and Set Pattern Set - Syntax ═══

These orders set, or push and set, the value of the current pattern symbol-set 
attribute. 

Set Pattern Set (GSPS) 
X'08' (LCID) 

Push and Set Pattern Set (GPSPS) 
X'48' (LCID) 


═══ <hidden> GSPS/GPSPS Parameter - LCID ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the pattern set: 

    0x00          Drawing default 
    0x01-0xFE     LCID for the symbol set 
    0xFF          Special pattern set. 


═══ <hidden> Set Pattern Set/Push and Set Pattern Set - Parameters ═══

 LCID (GUCHAR) 
    Local identifier (LCID) for the pattern set: 

    0x00          Drawing default 
    0x01-0xFE     LCID for the symbol set 
    0xFF          Special pattern set. 


═══ <hidden> Set Pattern Set/Push and Set Pattern Set - Remarks ═══

The value of the current pattern symbol-set attribute is pushed on to the 
Segment Call stack by the Push and Set order only. Both orders then set the 
value of the current pattern symbol-set attribute to the value in the order. 


═══ <hidden> Set Pattern Set/Push and Set Pattern Set - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.70. Set Pattern Symbol/Push and Set Pattern Symbol ═══


═══ <hidden> Set Pattern Symbol/Push and Set Pattern Symbol - Syntax ═══

These orders set, or push and set, the value of the current pattern-symbol 
attribute. 

Set Pattern Symbol (GSPT) 
X'28' (PATT) 

Push and Set Pattern Symbol (GPSPT) 
X'09' (PATT) 


═══ <hidden> GSPT/GPSPT Parameter - PATT ═══

 PATT (GBIT8) 
    Value for pattern-symbol attribute. 

    Special pattern set 

    When this is selected (lcid = 0xFF), the values are: 

    0x00 
            Drawing default 
    0x01-0x08 
            Density one through density eight (decreasing) 
    0x09 
            Vertical lines 
    0x0A 
            Horizontal lines 
    0x0B 
            Diagonal lines 1 (bottom-left to top-right) 
    0x0C 
            Diagonal lines 2 (bottom-left to top-right) 
    0x0D 
            Diagonal lines 1 (top-left to bottom-right) 
    0x0E 
            Diagonal lines 2 (top-left to bottom-right) 
    0x0F 
            No shading 
    0x10 
            Solid shading 
    0x40 
            Blank. 
    Other 
            Reserved values. 


 Pattern set 

            Values are as follows for any other set: 
    0x00 
            Drawing default 
    0x01-0xFF 
            These are the code points into the current pattern set. 


═══ <hidden> Set Pattern Symbol/Push and Set Pattern Symbol - Parameters ═══

 PATT (GBIT8) 
    Value for pattern-symbol attribute. 

    Special pattern set 

    When this is selected (lcid = 0xFF), the values are: 

    0x00 
            Drawing default 
    0x01-0x08 
            Density one through density eight (decreasing) 
    0x09 
            Vertical lines 
    0x0A 
            Horizontal lines 
    0x0B 
            Diagonal lines 1 (bottom-left to top-right) 
    0x0C 
            Diagonal lines 2 (bottom-left to top-right) 
    0x0D 
            Diagonal lines 1 (top-left to bottom-right) 
    0x0E 
            Diagonal lines 2 (top-left to bottom-right) 
    0x0F 
            No shading 
    0x10 
            Solid shading 
    0x40 
            Blank. 
    Other 
            Reserved values. 


 Pattern set 

            Values are as follows for any other set: 
    0x00 
            Drawing default 
    0x01-0xFF 
            These are the code points into the current pattern set. 


═══ <hidden> Set Pattern Symbol/Push and Set Pattern Symbol - Remarks ═══

The value of the current pattern-symbol attribute is pushed on to the Segment 
Call stack by the Push and Set order only. Both orders then set the value of 
the current pattern-symbol attribute to the value in the order. 


═══ <hidden> Set Pattern Symbol/Push and Set Pattern Symbol - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.71. Set Pick Identifier/Push and Set Pick Identifier ═══


═══ <hidden> Set Pick Identifier/Push and Set Pick Identifier - Syntax ═══

These orders set, or push and set, the value of the current pick identifier. 

Set Pick Identifier (GSPIK) 
X'43' (LEN, PKID) 

Push and Set Pick Identifier (GPSPIK) 
X'23' (LEN, PKID) 


═══ <hidden> GSPIK/GPSPIK Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSPIK/GPSPIK Parameter - PKID ═══

 PKID (GLONG) 
    Pick identifier. 


═══ <hidden> Set Pick Identifier/Push and Set Pick Identifier - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 PKID (GLONG) 
    Pick identifier. 


═══ <hidden> Set Pick Identifier/Push and Set Pick Identifier - Remarks ═══

The value of the current pick identifier is pushed on to the Segment Call stack 
by the Push and Set order only. Both orders then set the value of the current 
pick identifier to the value in the order. 


═══ <hidden> Set Pick Identifier/Push and Set Pick Identifier - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.72. Set Segment Boundary ═══


═══ <hidden> Set Segment Boundary - Syntax ═══

This order defines the maximum extent of the boundaries of the associated root 
segment.  It is valid only in a root segment prolog. 

Set Segment Boundary (GSSB) 
X'32' (LEN, RES, MASK, BB[LEN]) 


═══ <hidden> GSSB Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSSB Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GSSB Parameter - MASK ═══

 MASK 
    Values: 

    RES1 (GBIT2) 
             Reserved value, must be 0. 

    XL (GBIT1) 
             X left limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    XR (GBIT1) 
             X right limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    YB (GBIT1) 
             Y bottom limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    YT (GBIT1) 
             Y top limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    RES2 (GBIT2) 
             Reserved value, must be 0. 


═══ <hidden> GSSB Parameter - BB[LEN] ═══

 BB[LEN] (GROSOL) 
    Boundary values. 


═══ <hidden> Set Segment Boundary - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 MASK 
    Values: 

    RES1 (GBIT2) 
             Reserved value, must be 0. 

    XL (GBIT1) 
             X left limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    XR (GBIT1) 
             X right limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    YB (GBIT1) 
             Y bottom limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    YT (GBIT1) 
             Y top limit. 

             0       Not included in list of BB values 
             1       Is included in list of BB values. 

    RES2 (GBIT2) 
             Reserved value, must be 0. 

 BB[LEN] (GROSOL) 
    Boundary values. 


═══ <hidden> Set Segment Boundary - Remarks ═══

The order is only valid in a root-segment prolog. 


═══ <hidden> Set Segment Boundary - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.73. Set Stroke Line Width/Push and Set Stroke Line Width ═══


═══ <hidden> Set Stroke Line Width/Push and Set Stroke Line Width - Syntax ═══

These orders set the current stroke line-width attribute. 

Set Stroke Line Width (GSSLW) 
X'15' (LEN, FLAGS, RES, STRWIDTH) 

Push and Set Stroke Line Width (GPSSLW) 
X'55' (LEN, FLAGS, RES, STRWIDTH) 


═══ <hidden> GSSLW/GPSSLW Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSSLW/GPSSLW Parameter - FLAGS ═══

 FLAGS 

    DEFLT (GBIT1) 
             Values: 

             0       Set to value 
             1       Set to drawing default. 

    RES (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSSLW/GPSSLW Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GSSLW/GPSSLW Parameter - STRWIDTH ═══

 STRWIDTH (GROSOL) 
    Value for stroke width. 


═══ <hidden> Set Stroke Line Width/Push and Set Stroke Line Width - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAGS 

    DEFLT (GBIT1) 
             Values: 

             0       Set to value 
             1       Set to drawing default. 

    RES (GBIT7) 
             Reserved value, must be 0. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 STRWIDTH (GROSOL) 
    Value for stroke width. 


═══ <hidden> Set Stroke Line Width/Push and Set Stroke Line Width - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.74. Set Text Alignment/Push and Set Text Alignment ═══


═══ <hidden> Set Text Alignment/Push and Set Text Alignment - Syntax ═══

These orders set, or push and set, the value of the current text alignment 
attribute. 

Set Text Alignment (GSCSA) 
X'10' (LEN, HORIZ, VERT) 

Push and Set Text Alignment (GPSCSA) 
X'50' (LEN, HORIZ, VERT) 


═══ <hidden> GSCSA/GPSCSA Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSCSA/GPSCSA Parameter - HORIZ ═══

 HORIZ (GUCHAR) 
    Horizontal alignment as follows: 

    0x00       Drawing default. 

    0x01       Normal alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Left alignment. 
               Top to bottom                 Center alignment. 
               Right to left                 Right alignment. 
               Bottom to top                 Center alignment. 

    0x02       Left alignment. The string is aligned on the left edge of its 
               leftmost character. 

    0x03       Center alignment. The string is aligned on the arithmetic mean 
               of left and right. 

    0x04       Right alignment. The string is aligned on the right edge of its 
               rightmost character. 

    0xFF       Standard alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Left alignment. 
               Top to bottom                 Left alignment. 
               Right to left                 Right alignment. 
               Bottom to top                 Left alignment. 


═══ <hidden> GSCSA/GPSCSA Parameter - VERT ═══

 VERT (GUCHAR) 
    Vertical alignment as follows: 

    0x00       Drawing default. 

    0x01       Normal alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Base alignment. 
               Top to bottom                 Top alignment. 
               Right to left                 Base alignment. 
               Bottom to top                 Bottom alignment. 

    0x02       Top Alignment. The string is aligned on the top edge of its 
               topmost character. 

    0x03       Reserved. 

    0x04       Half alignment. The string is aligned on the arithmetic mean of 
               top and bottom. 

    0x05       Base alignment. The string is aligned on the base of its bottom 
               character. 

    0x06       Bottom Alignment. The string is aligned on the bottom edge of 
               its bottom character. 

    0xFF       Standard alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Bottom alignment. 
               Top to bottom                 Top alignment. 
               Right to left                 Bottom alignment. 
               Bottom to top                 Bottom alignment. 


═══ <hidden> Set Text Alignment/Push and Set Text Alignment - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 HORIZ (GUCHAR) 
    Horizontal alignment as follows: 

    0x00       Drawing default. 

    0x01       Normal alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Left alignment. 
               Top to bottom                 Center alignment. 
               Right to left                 Right alignment. 
               Bottom to top                 Center alignment. 

    0x02       Left alignment. The string is aligned on the left edge of its 
               leftmost character. 

    0x03       Center alignment. The string is aligned on the arithmetic mean 
               of left and right. 

    0x04       Right alignment. The string is aligned on the right edge of its 
               rightmost character. 

    0xFF       Standard alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Left alignment. 
               Top to bottom                 Left alignment. 
               Right to left                 Right alignment. 
               Bottom to top                 Left alignment. 

 VERT (GUCHAR) 
    Vertical alignment as follows: 

    0x00       Drawing default. 

    0x01       Normal alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Base alignment. 
               Top to bottom                 Top alignment. 
               Right to left                 Base alignment. 
               Bottom to top                 Bottom alignment. 

    0x02       Top Alignment. The string is aligned on the top edge of its 
               topmost character. 

    0x03       Reserved. 

    0x04       Half alignment. The string is aligned on the arithmetic mean of 
               top and bottom. 

    0x05       Base alignment. The string is aligned on the base of its bottom 
               character. 

    0x06       Bottom Alignment. The string is aligned on the bottom edge of 
               its bottom character. 

    0xFF       Standard alignment. The alignment assumed depends on the current 
               character direction: 

               Left to right                 Bottom alignment. 
               Top to bottom                 Top alignment. 
               Right to left                 Bottom alignment. 
               Bottom to top                 Bottom alignment. 


═══ <hidden> Set Text Alignment/Push and Set Text Alignment - Remarks ═══

The value of the current text alignment attribute is pushed on to the Segment 
Call stack by the Push and Set order only. Both orders set the value of the 
current text alignment attribute to the value specified in the order. 


═══ <hidden> Set Text Alignment/Push and Set Text Alignment - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.75. Set Viewing Transform ═══


═══ <hidden> Set Viewing Transform - Syntax ═══

This order sets the current viewing transform. 

Set Viewing Transform (GSTV) 
X'31' (LEN, RES, FLAGS, MASK, MX[LEN]) 


═══ <hidden> GSTV Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSTV Parameter - RES ═══

 RES (GBIT8) 
    Reserved value, must be 0. 


═══ <hidden> GSTV Parameter - FLAGS ═══

 FLAGS 
    Values: 

    RES1 (GBIT5) 
             Reserved value, must be 0. 

    CONTROL (GBIT1) 
             Values: 

             0       Concatenate before drawing default 
             1       Concatenate before the current viewing transform. 

    RES2 (GBIT2) 
             Reserved value, must be 0. 


═══ <hidden> GSTV Parameter - MASK ═══

 MASK (GBIT16) 
    Load mask. 


═══ <hidden> GSTV Parameter - MX[LEN] ═══

 MX[LEN] (GROSOL) 
    Matrix values. 


═══ <hidden> Set Viewing Transform - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 RES (GBIT8) 
    Reserved value, must be 0. 

 FLAGS 
    Values: 

    RES1 (GBIT5) 
             Reserved value, must be 0. 

    CONTROL (GBIT1) 
             Values: 

             0       Concatenate before drawing default 
             1       Concatenate before the current viewing transform. 

    RES2 (GBIT2) 
             Reserved value, must be 0. 

 MASK (GBIT16) 
    Load mask. 

 MX[LEN] (GROSOL) 
    Matrix values. 


═══ <hidden> Set Viewing Transform - Topics ═══

Select an item: 

Syntax
Parameters
Glossary


═══ 2.76. Set Viewing Window/Push and Set Viewing Window ═══


═══ <hidden> Set Viewing Window/Push and Set Viewing Window - Syntax ═══

These orders set, or push and set, the current viewing window. 

Set Viewing Window (GSVW) 
X'27' (LEN, FLAG, MASK, WW[LEN]) 

Push and Set Viewing Window (GPSVW) 
X'67' (LEN, FLAG, MASK, WW[LEN]) 


═══ <hidden> GSVW/GPSVW Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSVW/GPSVW Parameter - FLAG ═══

 FLAG 
    Values: 

    REPLACE (GBIT1) 
             Values: 

             0       Intersect with current window 
             1       Replace current with new window. 

    RES (GBIT7) 
             Reserved value, must be 0. 


═══ <hidden> GSVW/GPSVW Parameter - MASK ═══

 MASK 
    Values: 

    RES1 (GBIT2) 
             Reserved value, must be 0. 

    XL (GBIT1) 
             X left limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    XR (GBIT1) 
             X right limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    YB (GBIT1) 
             Y bottom limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    YT (GBIT1) 
             Y top limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    RES2 (GBIT2) 
             Reserved value, must be 0. 


═══ <hidden> GSVW/GPSVW Parameter - WW[LEN] ═══

 WW[LEN] (GROSOL) 
    Window values. 


═══ <hidden> Set Viewing Window/Push and Set Viewing Window - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 FLAG 
    Values: 

    REPLACE (GBIT1) 
             Values: 

             0       Intersect with current window 
             1       Replace current with new window. 

    RES (GBIT7) 
             Reserved value, must be 0. 

 MASK 
    Values: 

    RES1 (GBIT2) 
             Reserved value, must be 0. 

    XL (GBIT1) 
             X left limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    XR (GBIT1) 
             X right limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    YB (GBIT1) 
             Y bottom limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    YT (GBIT1) 
             Y top limit. 

             0       Not included in list of WW values 
             1       Is included in list of WW values 

    RES2 (GBIT2) 
             Reserved value, must be 0. 

 WW[LEN] (GROSOL) 
    Window values. 


═══ <hidden> Set Viewing Window/Push and Set Viewing Window - Remarks ═══

The value of the current viewing window is pushed on to the Segment Call stack 
by the Push and Set order only. Both orders then set the current viewing window 
using the values in the order. 


═══ <hidden> Set Viewing Window/Push and Set Viewing Window - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 2.77. Sharp Fillet at Given Position/Sharp Fillet at Current Position ═══


═══ <hidden> Sharp Fillet at Given Position/Sharp Fillet at Current Position - Syntax ═══

This order generates a curve that starts at a given position, and uses points 
P1 and P2, together with the sharpness specification S1. 

Sharp Fillet at Given Position (GSFLT) 
X'E4' (LEN, P0, P1, P2, P3, P4, PN-1, PN, S1, S2, SN/2) 

Sharp Fillet at Current Position (GCSFLT) 
X'A4' (LEN, P1, P2, P3, P4, PN-1, PN, S1, S2, SN/2) 


═══ <hidden> GSFLT/GCSFLT Parameter - LEN ═══

 LEN (GLENGTH1) 
    Length of following data. 


═══ <hidden> GSFLT/GCSFLT Parameter - P0 ═══

 P0 (GPOINT) 
    Coordinate data of first curve start. 

    This parameter is only present in a Sharp Fillet at Given Position order. 


═══ <hidden> GSFLT/GCSFLT Parameter - P1 ═══

 P1 (GPOINT) 
    Coordinate data of first curve control point. 


═══ <hidden> GSFLT/GCSFLT Parameter - P2 ═══

 P2 (GPOINT) 
    Coordinate data of first curve end. 


═══ <hidden> GSFLT/GCSFLT Parameter - P3 ═══

 P3 (GPOINT) 
    Coordinate data of second curve control point. 


═══ <hidden> GSFLT/GCSFLT Parameter - P4 ═══

 P4 (GPOINT) 
    Coordinate data of second curve end. 


═══ <hidden> GSFLT/GCSFLT Parameter - PN-1 ═══

 PN-1 (GPOINT) 
    Coordinate data of last curve control point. 


═══ <hidden> GSFLT/GCSFLT Parameter - PN ═══

 PN (GPOINT) 
    Coordinate data of last curve end. 


═══ <hidden> GSFLT/GCSFLT Parameter - S1 ═══

 S1 (GROF) 
    Sharpness specification of first curve. 


═══ <hidden> GSFLT/GCSFLT Parameter - S2 ═══

 S2 (GROF) 
    Sharpness specification of second curve. 


═══ <hidden> GSFLT/GCSFLT Parameter - SN/2 ═══

 SN/2 (GROF) 
    Sharpness specification of last curve. 


═══ <hidden> Sharp Fillet at Given Position/Sharp Fillet at Current Position - Parameters ═══

 LEN (GLENGTH1) 
    Length of following data. 

 P0 (GPOINT) 
    Coordinate data of first curve start. 

    This parameter is only present in a Sharp Fillet at Given Position order. 

 P1 (GPOINT) 
    Coordinate data of first curve control point. 

 P2 (GPOINT) 
    Coordinate data of first curve end. 

 P3 (GPOINT) 
    Coordinate data of second curve control point. 

 P4 (GPOINT) 
    Coordinate data of second curve end. 

 PN-1 (GPOINT) 
    Coordinate data of last curve control point. 

 PN (GPOINT) 
    Coordinate data of last curve end. 

 S1 (GROF) 
    Sharpness specification of first curve. 

 S2 (GROF) 
    Sharpness specification of second curve. 

 SN/2 (GROF) 
    Sharpness specification of last curve. 


═══ <hidden> Sharp Fillet at Given Position/Sharp Fillet at Current Position - Remarks ═══

Further points are used in groups of two to form a polycurve. 


═══ <hidden> Sharp Fillet at Given Position/Sharp Fillet at Current Position - Topics ═══

Select an item: 

Syntax
Parameters
Remarks
Glossary


═══ 3. Graphics Orders Data Types ═══

All data types are in Intel** format, unless noted otherwise. 


═══ 3.1. GBIT1 ═══

1-bit field. 


═══ 3.2. GBIT2 ═══

2-bit field. 


═══ 3.3. GBIT4 ═══

4-bit field. 


═══ 3.4. GBIT5 ═══

5-bit field. 


═══ 3.5. GBIT6 ═══

6-bit field. 


═══ 3.6. GBIT7 ═══

7-bit field. 


═══ 3.7. GBIT8 ═══

8-bit field. 


═══ 3.8. GBIT16 ═══

16-bit field. 


═══ 3.9. GBIT32 ═══

32-bit field. 


═══ 3.10. GCHAR ═══

Signed 1-byte integer value. 


═══ 3.11. GDELPOINT ═══

Offset point structure. 


  GCHAR     dx;  /*  x coordinate offset. */
  GCHAR     dy;  /*  y coordinate offset. */


═══ <hidden> GDELPOINT Field - dx ═══

 dx (GCHAR) 
    x coordinate offset. 


═══ <hidden> GDELPOINT Field - dy ═══

 dy (GCHAR) 
    y coordinate offset. 


═══ 3.12. GFIXED ═══

Signed integer fraction (16:16). (This can be treated as a GLONG where the 
value has been multiplied by 65536.) 


═══ 3.13. GFIXEDS ═══

Signed integer fraction (8:8), which can be treated as a GSHORT data type, 
where the value has been multiplied by 256. 


  GCHAR      Integer;   /*  Integral component. */
  GUCHAR     Fraction;  /*  Fractional component. */


═══ <hidden> GFIXEDS Field - Integer ═══

 Integer (GCHAR) 
    Integral component. 


═══ <hidden> GFIXEDS Field - Fraction ═══

 Fraction (GUCHAR) 
    Fractional component. 


═══ 3.14. GHBITMAP ═══

Bit-map handle, which is the same as GULONG. 


═══ 3.15. GINDATT ═══

Individual attribute value.  For the attribute types color and background 
color, this is the same as GINDEX3. For the attribute types mix and background 
color, this is the same as GUCHAR. 


═══ 3.16. GINDEX3 ═══

Unsigned 3-byte integer value. 


═══ 3.17. GLENGTH1 ═══

1-byte length. 


═══ 3.18. GLENGTH2 ═══

2-byte length, in S/370 format; that is, the high-order byte precedes the 
low-order byte in storage. 


═══ 3.19. GLONG ═══

Signed 4-byte integer value. 


═══ 3.20. GPOINT ═══

Point structure. 


  GROSOL     x;  /*  x coordinate. */
  GROSOL     y;  /*  y coordinate. */


═══ <hidden> GPOINT Field - x ═══

 x (GROSOL) 
    x coordinate. 


═══ <hidden> GPOINT Field - y ═══

 y (GROSOL) 
    y coordinate. 


═══ 3.21. GPOINTB ═══

Point in bit-map structure. 


  GLONG     x;  /*  x coordinate. */
  GLONG     y;  /*  y coordinate. */


═══ <hidden> GPOINTB Field - x ═══

 x (GLONG) 
    x coordinate. 


═══ <hidden> GPOINTB Field - y ═══

 y (GLONG) 
    y coordinate. 


═══ 3.22. GPOLYS ═══

Array of Polygons. Each element of the array is a 16 bit count of the number of 
vertices, followed by the vertex coordinates. 


═══ 3.23. GREAL ═══

Real (single precision floating point). 

This data type is in Intel format. 


═══ 3.24. GROF ═══

Number representation which is the same as the GFIXED data type. 


═══ 3.25. GROFUFS ═══

Number representation which is either GFIXED, GUFIXEDS or GREAL data type, 
depending on the presentation-space format. 


═══ 3.26. GROUFS ═══

Number representation which is either the GUFIXEDS or GREAL data type, 
depending on the presentation-space format. 


═══ 3.27. GROL ═══

Number representation, which is the same as the GLONG data type. 


═══ 3.28. GROSOL ═══

Number representation which is either the GSHORT or the GLONG data type, 
depending on the presentation-space format; see PS_FORMAT in the flOptions 
parameter of the GpiCreatePS function. 


═══ 3.29. GROUL ═══

Number representation, which is the same as the GULONG data type. 


═══ 3.30. GSHORT ═══

Signed 2-byte integer value. 


═══ 3.31. GSHORT370 ═══

Signed 2-byte integer value, in S/370 format (that is, the high-order byte 
precedes the low-order byte in storage). 


═══ 3.32. GSTR ═══

String with an explicit length count. 


═══ 3.33. GUCHAR ═══

Unsigned 1-byte integer value. 


═══ 3.34. GUFIXEDS ═══

Unsigned integer fraction (8:8) which can be treated as a GUSHORT data type, 
where the value has been multiplied by 256. 


═══ 3.35. GULONG ═══

Unsigned 4-byte integer value. 


═══ 3.36. GULONG370 ═══

Unsigned 4-byte integer value, in S/370 format (that is, the high-order byte 
first, the low-order byte last in storage). 


═══ 3.37. GUNDF ═══

Undefined string of 8-bit bytes. 


═══ 3.38. GUNDF1 ═══

Undefined 8-bit byte. 


═══ 3.39. GUSHORT ═══

Unsigned 2-byte integer value. 


═══ 3.40. GUSHORT370 ═══

Unsigned 2-byte integer value, in S/370 format; that is, the high-order byte 
precedes the low-order byte in storage. 


═══ 4. Errors ═══

Error codes are furnished numerically and alphabetically. 

For a listing of error codes by number, see Error Number and Name. 

For a listing of error codes and their explanations, see Error Name and 
Explanation. 


═══ 4.1. Error Number and Name ═══

This section lists PM errors returned by WinGetLastError in order of their 
error numbers. For explanations of these errors, see Error Name and 
Explanation. 

 Error Number   Error Constant 
 0x0000         PMERR_OK 
 0x0000         PMERR_OK 
 0x0000         PMERR_OK 
 0x0836         NERR_NetNotStarted 
 0x0845         NERR_RedirectedPath 
 0x084B         NERR_BufTooSmall 
 0x085E         NERR_InvalidAPI 
 0x0866         NERR_QNotFound 
 0x0867         NERR_JobNotFound 
 0x0868         NERR_DestNotFound 
 0x0869         NERR_DestExists 
 0x086A         NERR_QExists 
 0x086B         NERR_QNoRoom 
 0x086C         NERR_JobNoRoom 
 0x086D         NERR_DestNoRoom 
 0x086E         NERR_DestIdle 
 0x086F         NERR_DestInvalidOp 
 0x0871         NERR_SpoolerNotLoaded 
 0x0872         NERR_DestInvalidState 
 0x0874         NERR_JobInvalidState 
 0x0875         NERR_SpoolNoMemory 
 0x0876         NERR_DriverNotFound 
 0x0877         NERR_DataTypeInvalid 
 0x0878         NERR_ProcNotFound 
 0x0925         NERR_BadDev 
 0x0927         NERR_CommDevInUse 
 0x092F         NERR_InvalidComputer 
 0x0961         NERR_OpenFiles 
 0x0965         NERR_LocalDrive 
 0x1001         PMERR_INVALID_HWND 
 0x1001         HMERR_NO_FRAME_WND_IN_CHAIN 
 0x1002         PMERR_INVALID_HMQ 
 0x1002         HMERR_INVALID_ASSOC_APP_WND 
 0x1003         PMERR_PARAMETER_OUT_OF_RANGE 
 0x1003         HMERR_INVALID_ASSOC_HELP_INST 
 0x1004         PMERR_WINDOW_LOCK_UNDERFLOW 
 0x1004         HMERR_INVALID_DESTROY_HELP_INST 
 0x1005         PMERR_WINDOW_LOCK_OVERFLOW 
 0x1005         HMERR_NO_HELP_INST_IN_CHAIN 
 0x1006         PMERR_BAD_WINDOW_LOCK_COUNT 
 0x1006         HMERR_INVALID_HELP_INSTANCE_HDL 
 0x1007         PMERR_WINDOW_NOT_LOCKED 
 0x1007         HMERR_INVALID_QUERY_APP_WND 
 0x1008         PMERR_INVALID_SELECTOR 
 0x1008         HMERR_HELP_INST_CALLED_INVALID 
 0x1009         PMERR_CALL_FROM_WRONG_THREAD 
 0x1009         HMERR_HELPTABLE_UNDEFINE 
 0x100A         PMERR_RESOURCE_NOT_FOUND 
 0x100A         HMERR_HELP_INSTANCE_UNDEFINE 
 0x100B         PMERR_INVALID_STRING_PARM 
 0x100B         HMERR_HELPITEM_NOT_FOUND 
 0x100C         PMERR_INVALID_HHEAP 
 0x100C         HMERR_INVALID_HELPSUBITEM_SIZE 
 0x100D         PMERR_INVALID_HEAP_POINTER 
 0x100D         HMERR_HELPSUBITEM_NOT_FOUND 
 0x100E         PMERR_INVALID_HEAP_SIZE_PARM 
 0x100F         PMERR_INVALID_HEAP_SIZE 
 0x1010         PMERR_INVALID_HEAP_SIZE_WORD 
 0x1011         PMERR_HEAP_OUT_OF_MEMORY 
 0x1012         PMERR_HEAP_MAX_SIZE_REACHED 
 0x1013         PMERR_INVALID_HATOMTBL 
 0x1014         PMERR_INVALID_ATOM 
 0x1015         PMERR_INVALID_ATOM_NAME 
 0x1016         PMERR_INVALID_INTEGER_ATOM 
 0x1017         PMERR_ATOM_NAME_NOT_FOUND 
 0x1018         PMERR_QUEUE_TOO_LARGE 
 0x1019         PMERR_INVALID_FLAG 
 0x101A         PMERR_INVALID_HACCEL 
 0x101B         PMERR_INVALID_HPTR 
 0x101C         PMERR_INVALID_HENUM 
 0x101D         PMERR_INVALID_SRC_CODEPAGE 
 0x101E         PMERR_INVALID_DST_CODEPAGE 
 0x101F         PMERR_UNKNOWN_COMPONENT_ID 
 0x1020         PMERR_UNKNOWN_ERROR_CODE 
 0x1021         PMERR_SEVERITY_LEVELS 
 0x1034         PMERR_INVALID_RESOURCE_FORMAT 
 0x1035         WINDBG_WINDOW_UNLOCK_WAIT 
 0x1036         PMERR_NO_MSG_QUEUE 
 0x1037         PMERR_CANNOT_SET_FOCUS 
 0x1038         PMERR_QUEUE_FULL 
 0x1039         PMERR_LIBRARY_LOAD_FAILED 
 0x103A         PMERR_PROCEDURE_LOAD_FAILED 
 0x103B         PMERR_LIBRARY_DELETE_FAILED 
 0x103C         PMERR_PROCEDURE_DELETE_FAILED 
 0x103D         PMERR_ARRAY_TOO_LARGE 
 0x103E         PMERR_ARRAY_TOO_SMALL 
 0x103F         PMERR_DATATYPE_ENTRY_BAD_INDEX 
 0x1040         PMERR_DATATYPE_ENTRY_CTL_BAD 
 0x1041         PMERR_DATATYPE_ENTRY_CTL_MISS 
 0x1042         PMERR_DATATYPE_ENTRY_INVALID 
 0x1043         PMERR_DATATYPE_ENTRY_NOT_NUM 
 0x1044         PMERR_DATATYPE_ENTRY_NOT_OFF 
 0x1045         PMERR_DATATYPE_INVALID 
 0x1046         PMERR_DATATYPE_NOT_UNIQUE 
 0x1047         PMERR_DATATYPE_TOO_LONG 
 0x1048         PMERR_DATATYPE_TOO_SMALL 
 0x1049         PMERR_DIRECTION_INVALID 
 0x104A         PMERR_INVALID_HAB 
 0x104D         PMERR_INVALID_HSTRUCT 
 0x104E         PMERR_LENGTH_TOO_SMALL 
 0x104F         PMERR_MSGID_TOO_SMALL 
 0x1050         PMERR_NO_HANDLE_ALLOC 
 0x1051         PMERR_NOT_IN_A_PM_SESSION 
 0x1052         PMERR_MSG_QUEUE_ALREADY_EXISTS 
 0x1055         PMERR_OLD_RESOURCE 
 0x1056         PMERR_WPDSERVER_IS_ACTIVE 
 0x1057         PMERR_WPDSERVER_NOT_STARTED 
 0x1058         PMERR_SOMDD_IS_ACTIVE 
 0x1059         PMERR_SOMDD_NOT_STARTED 
 0x1101         PMERR_INVALID_PIB 
 0x1102         PMERR_INSUFF_SPACE_TO_ADD 
 0x1103         PMERR_INVALID_GROUP_HANDLE 
 0x1104         PMERR_DUPLICATE_TITLE 
 0x1105         PMERR_INVALID_TITLE 
 0x1106         PMERR_INVALID_TARGET_HANDLE 
 0x1107         PMERR_HANDLE_NOT_IN_GROUP 
 0x1108         PMERR_INVALID_PATH_STATEMENT 
 0x1109         PMERR_NO_PROGRAM_FOUND 
 0x110A         PMERR_INVALID_BUFFER_SIZE 
 0x110B         PMERR_BUFFER_TOO_SMALL 
 0x110C         PMERR_PL_INITIALISATION_FAIL 
 0x110D         PMERR_CANT_DESTROY_SYS_GROUP 
 0x110E         PMERR_INVALID_TYPE_CHANGE 
 0x110F         PMERR_INVALID_PROGRAM_HANDLE 
 0x1110         PMERR_NOT_CURRENT_PL_VERSION 
 0x1111         PMERR_INVALID_CIRCULAR_REF 
 0x1112         PMERR_MEMORY_ALLOCATION_ERR 
 0x1113         PMERR_MEMORY_DEALLOCATION_ERR 
 0x1114         PMERR_TASK_HEADER_TOO_BIG 
 0x1115         PMERR_INVALID_INI_FILE_HANDLE 
 0x1116         PMERR_MEMORY_SHARE 
 0x1117         PMERR_OPEN_QUEUE 
 0x1118         PMERR_CREATE_QUEUE 
 0x1119         PMERR_WRITE_QUEUE 
 0x111A         PMERR_READ_QUEUE 
 0x111B         PMERR_CALL_NOT_EXECUTED 
 0x111C         PMERR_UNKNOWN_APIPKT 
 0x111D         PMERR_INITHREAD_EXISTS 
 0x111E         PMERR_CREATE_THREAD 
 0x111F         PMERR_NO_HK_PROFILE_INSTALLED 
 0x1120         PMERR_INVALID_DIRECTORY 
 0x1121         PMERR_WILDCARD_IN_FILENAME 
 0x1122         PMERR_FILENAME_BUFFER_FULL 
 0x1123         PMERR_FILENAME_TOO_LONG 
 0x1124         PMERR_INI_FILE_IS_SYS_OR_USER 
 0x1125         PMERR_BROADCAST_PLMSG 
 0x1126         PMERR_190_INIT_DONE 
 0x1127         PMERR_HMOD_FOR_PMSHAPI 
 0x1128         PMERR_SET_HK_PROFILE 
 0x1129         PMERR_API_NOT_ALLOWED 
 0x112A         PMERR_INI_STILL_OPEN 
 0x112B         PMERR_PROGDETAILS_NOT_IN_INI 
 0x112C         PMERR_PIBSTRUCT_NOT_IN_INI 
 0x112D         PMERR_INVALID_DISKPROGDETAILS 
 0x112E         PMERR_PROGDETAILS_READ_FAILURE 
 0x112F         PMERR_PROGDETAILS_WRITE_FAILURE 
 0x1130         PMERR_PROGDETAILS_QSIZE_FAILURE 
 0x1131         PMERR_INVALID_PROGDETAILS 
 0x1132         PMERR_SHEPROFILEHOOK_NOT_FOUND 
 0x1133         PMERR_190PLCONVERTED 
 0x1134         PMERR_FAILED_TO_CONVERT_INI_PL 
 0x1135         PMERR_PMSHAPI_NOT_INITIALISED 
 0x1136         PMERR_INVALID_SHELL_API_HOOK_ID 
 0x1200         PMERR_DOS_ERROR 
 0x1201         PMERR_NO_SPACE 
 0x1202         PMERR_INVALID_SWITCH_HANDLE 
 0x1203         PMERR_NO_HANDLE 
 0x1204         PMERR_INVALID_PROCESS_ID 
 0x1205         PMERR_NOT_SHELL 
 0x1206         PMERR_INVALID_WINDOW 
 0x1207         PMERR_INVALID_POST_MSG 
 0x1208         PMERR_INVALID_PARAMETERS 
 0x1208         PMERR_INVALID_PARAMETERS
 0x1209         PMERR_INVALID_PROGRAM_TYPE 
 0x120A         PMERR_NOT_EXTENDED_FOCUS 
 0x120B         PMERR_INVALID_SESSION_ID 
 0x120C         PMERR_SMG_INVALID_ICON_FILE 
 0x120D         PMERR_SMG_ICON_NOT_CREATED 
 0x120E         PMERR_SHL_DEBUG 
 0x1301         PMERR_OPENING_INI_FILE 
 0x1302         PMERR_INI_FILE_CORRUPT 
 0x1303         PMERR_INVALID_PARM 
 0x1304         PMERR_NOT_IN_IDX 
 0x1305         PMERR_NO_ENTRIES_IN_GROUP 
 0x1306         PMERR_INI_WRITE_FAIL 
 0x1307         PMERR_IDX_FULL 
 0x1308         PMERR_INI_PROTECTED 
 0x1309         PMERR_MEMORY_ALLOC 
 0x130A         PMERR_INI_INIT_ALREADY_DONE 
 0x130B         PMERR_INVALID_INTEGER 
 0x130C         PMERR_INVALID_ASCIIZ 
 0x130D         PMERR_CAN_NOT_CALL_SPOOLER 
 0x130D         PMERR_VALIDATION_REJECTED 
 0x1401         PMERR_WARNING_WINDOW_NOT_KILLED 
 0x1402         PMERR_ERROR_INVALID_WINDOW 
 0x1403         PMERR_ALREADY_INITIALIZED 
 0x1405         PMERR_MSG_PROG_NO_MOU 
 0x1406         PMERR_MSG_PROG_NON_RECOV 
 0x1407         PMERR_WINCONV_INVALID_PATH 
 0x1408         PMERR_PI_NOT_INITIALISED 
 0x1409         PMERR_PL_NOT_INITIALISED 
 0x140A         PMERR_NO_TASK_MANAGER 
 0x140B         PMERR_SAVE_NOT_IN_PROGRESS 
 0x140C         PMERR_NO_STACK_SPACE 
 0x140D         PMERR_INVALID_COLR_FIELD 
 0x140E         PMERR_INVALID_COLR_VALUE 
 0x140F         PMERR_COLR_WRITE 
 0x1501         PMERR_TARGET_FILE_EXISTS 
 0x1502         PMERR_SOURCE_SAME_AS_TARGET 
 0x1503         PMERR_SOURCE_FILE_NOT_FOUND 
 0x1504         PMERR_INVALID_NEW_PATH 
 0x1505         PMERR_TARGET_FILE_NOT_FOUND 
 0x1506         PMERR_INVALID_DRIVE_NUMBER 
 0x1507         PMERR_NAME_TOO_LONG 
 0x1508         PMERR_NOT_ENOUGH_ROOM_ON_DISK 
 0x1509         PMERR_NOT_ENOUGH_MEM 
 0x150B         PMERR_LOG_DRV_DOES_NOT_EXIST 
 0x150C         PMERR_INVALID_DRIVE 
 0x150D         PMERR_ACCESS_DENIED 
 0x150E         PMERR_NO_FIRST_SLASH 
 0x150F         PMERR_READ_ONLY_FILE 
 0x151F         PMERR_GROUP_PROTECTED 
 0x152F         PMERR_INVALID_PROGRAM_CATEGORY 
 0x1530         PMERR_INVALID_APPL 
 0x1531         PMERR_CANNOT_START 
 0x1532         PMERR_STARTED_IN_BACKGROUND 
 0x1533         PMERR_INVALID_HAPP 
 0x1534         PMERR_CANNOT_STOP 
 0x1601         PMERR_INTERNAL_ERROR_1 
 0x1602         PMERR_INTERNAL_ERROR_2 
 0x1603         PMERR_INTERNAL_ERROR_3 
 0x1604         PMERR_INTERNAL_ERROR_4 
 0x1605         PMERR_INTERNAL_ERROR_5 
 0x1606         PMERR_INTERNAL_ERROR_6 
 0x1607         PMERR_INTERNAL_ERROR_7 
 0x1608         PMERR_INTERNAL_ERROR_8 
 0x1609         PMERR_INTERNAL_ERROR_9 
 0x160A         PMERR_INTERNAL_ERROR_10 
 0x160B         PMERR_INTERNAL_ERROR_11 
 0x160C         PMERR_INTERNAL_ERROR_12 
 0x160D         PMERR_INTERNAL_ERROR_13 
 0x160E         PMERR_INTERNAL_ERROR_14 
 0x160F         PMERR_INTERNAL_ERROR_15 
 0x1610         PMERR_INTERNAL_ERROR_16 
 0x1611         PMERR_INTERNAL_ERROR_17 
 0x1612         PMERR_INTERNAL_ERROR_18 
 0x1613         PMERR_INTERNAL_ERROR_19 
 0x1614         PMERR_INTERNAL_ERROR_20 
 0x1615         PMERR_INTERNAL_ERROR_21 
 0x1616         PMERR_INTERNAL_ERROR_22 
 0x1617         PMERR_INTERNAL_ERROR_23 
 0x1618         PMERR_INTERNAL_ERROR_24 
 0x1619         PMERR_INTERNAL_ERROR_25 
 0x161A         PMERR_INTERNAL_ERROR_26 
 0x161B         PMERR_INTERNAL_ERROR_27 
 0x161C         PMERR_INTERNAL_ERROR_28 
 0x161D         PMERR_INTERNAL_ERROR_29 
 0x1630         PMERR_INVALID_FREE_MESSAGE_ID 
 0x1641         PMERR_FUNCTION_NOT_SUPPORTED 
 0x1642         PMERR_INVALID_ARRAY_COUNT 
 0x1643         PMERR_INVALID_LENGTH 
 0x1644         PMERR_INVALID_BUNDLE_TYPE 
 0x1645         PMERR_INVALID_PARAMETER 
 0x1646         PMERR_INVALID_NUMBER_OF_PARMS 
 0x1647         PMERR_GREATER_THAN_64K 
 0x1648         PMERR_INVALID_PARAMETER_TYPE 
 0x1649         PMERR_NEGATIVE_STRCOND_DIM 
 0x164A         PMERR_INVALID_NUMBER_OF_TYPES 
 0x164B         PMERR_INCORRECT_HSTRUCT 
 0x164C         PMERR_INVALID_ARRAY_SIZE 
 0x164D         PMERR_INVALID_CONTROL_DATATYPE 
 0x164E         PMERR_INCOMPLETE_CONTROL_SEQU 
 0x164F         PMERR_INVALID_DATATYPE 
 0x1650         PMERR_INCORRECT_DATATYPE 
 0x1651         PMERR_NOT_SELF_DESCRIBING_DTYP 
 0x1652         PMERR_INVALID_CTRL_SEQ_INDEX 
 0x1653         PMERR_INVALID_TYPE_FOR_LENGTH 
 0x1654         PMERR_INVALID_TYPE_FOR_OFFSET 
 0x1655         PMERR_INVALID_TYPE_FOR_MPARAM 
 0x1656         PMERR_INVALID_MESSAGE_ID 
 0x1657         PMERR_C_LENGTH_TOO_SMALL 
 0x1658         PMERR_APPL_STRUCTURE_TOO_SMALL 
 0x1659         PMERR_INVALID_ERRORINFO_HANDLE 
 0x165A         PMERR_INVALID_CHARACTER_INDEX 
 0x1700         WPERR_PROTECTED_CLASS 
 0x1701         WPERR_INVALID_CLASS 
 0x1702         WPERR_INVALID_SUPERCLASS 
 0x1703         WPERR_NO_MEMORY 
 0x1704         WPERR_SEMAPHORE_ERROR 
 0x1705         WPERR_BUFFER_TOO_SMALL 
 0x1706         WPERR_CLSLOADMOD_FAILED 
 0x1707         WPERR_CLSPROCADDR_FAILED 
 0x1708         WPERR_OBJWORD_LOCATION 
 0x1709         WPERR_INVALID_OBJECT 
 0x170A         WPERR_MEMORY_CLEANUP 
 0x170B         WPERR_INVALID_MODULE 
 0x170C         WPERR_INVALID_OLDCLASS 
 0x170D         WPERR_INVALID_NEWCLASS 
 0x170E         WPERR_NOT_IMMEDIATE_CHILD 
 0x170F         WPERR_NOT_WORKPLACE_CLASS 
 0x1710         WPERR_CANT_REPLACE_METACLS 
 0x1711         WPERR_INI_FILE_WRITE 
 0x1712         WPERR_INVALID_FOLDER 
 0x1713         WPERR_BUFFER_OVERFLOW 
 0x1714         WPERR_OBJECT_NOT_FOUND 
 0x1715         WPERR_INVALID_HFIND 
 0x1716         WPERR_INVALID_COUNT 
 0x1717         WPERR_INVALID_BUFFER 
 0x1718         WPERR_ALREADY_EXISTS 
 0x1719         WPERR_INVALID_FLAGS 
 0x1720         WPERR_INVALID_OBJECTID 
 0x1721         WPERR_INVALID_TARGET_OBJECT 
 0x1F00         PMERR_NOT_DRAGGING 
 0x2001         PMERR_ALREADY_IN_AREA 
 0x2001         HMERR_INDEX_NOT_FOUND 
 0x2002         PMERR_ALREADY_IN_ELEMENT 
 0x2002         HMERR_CONTENT_NOT_FOUND 
 0x2003         PMERR_ALREADY_IN_PATH 
 0x2003         HMERR_OPEN_LIB_FILE 
 0x2004         PMERR_ALREADY_IN_SEG 
 0x2004         HMERR_READ_LIB_FILE 
 0x2005         PMERR_AREA_INCOMPLETE 
 0x2005         HMERR_CLOSE_LIB_FILE 
 0x2006         PMERR_BASE_ERROR 
 0x2006         HMERR_INVALID_LIB_FILE 
 0x2007         PMERR_BITBLT_LENGTH_EXCEEDED 
 0x2007         HMERR_NO_MEMORY 
 0x2008         PMERR_BITMAP_IN_USE 
 0x2008         HMERR_ALLOCATE_SEGMENT 
 0x2009         PMERR_BITMAP_IS_SELECTED 
 0x2009         HMERR_FREE_MEMORY 
 0x200A         PMERR_BITMAP_NOT_FOUND 
 0x200B         PMERR_BITMAP_NOT_SELECTED 
 0x200C         PMERR_BOUNDS_OVERFLOW 
 0x200D         PMERR_CALLED_SEG_IS_CHAINED 
 0x200E         PMERR_CALLED_SEG_IS_CURRENT 
 0x200F         PMERR_CALLED_SEG_NOT_FOUND 
 0x2010         PMERR_CANNOT_DELETE_ALL_DATA 
 0x2010         HMERR_PANEL_NOT_FOUND 
 0x2011         PMERR_CANNOT_REPLACE_ELEMENT_0 
 0x2011         HMERR_DATABASE_NOT_OPEN 
 0x2012         PMERR_COL_TABLE_NOT_REALIZABLE 
 0x2013         PMERR_COL_TABLE_NOT_REALIZED 
 0x2013         HMERR_LOAD_DLL 
 0x2014         PMERR_COORDINATE_OVERFLOW 
 0x2015         PMERR_CORR_FORMAT_MISMATCH 
 0x2016         PMERR_DATA_TOO_LONG 
 0x2017         PMERR_DC_IS_ASSOCIATED 
 0x2018         PMERR_DESC_STRING_TRUNCATED 
 0x2019         PMERR_DEVICE_DRIVER_ERROR_1 
 0x201A         PMERR_DEVICE_DRIVER_ERROR_2 
 0x201B         PMERR_DEVICE_DRIVER_ERROR_3 
 0x201C         PMERR_DEVICE_DRIVER_ERROR_4 
 0x201D         PMERR_DEVICE_DRIVER_ERROR_5 
 0x201E         PMERR_DEVICE_DRIVER_ERROR_6 
 0x201F         PMERR_DEVICE_DRIVER_ERROR_7 
 0x2020         PMERR_DEVICE_DRIVER_ERROR_8 
 0x2021         PMERR_DEVICE_DRIVER_ERROR_9 
 0x2022         PMERR_DEVICE_DRIVER_ERROR_10 
 0x2023         PMERR_DEV_FUNC_NOT_INSTALLED 
 0x2024         PMERR_DOSOPEN_FAILURE 
 0x2025         PMERR_DOSREAD_FAILURE 
 0x2026         PMERR_DRIVER_NOT_FOUND 
 0x2027         PMERR_DUP_SEG 
 0x2028         PMERR_DYNAMIC_SEG_SEQ_ERROR 
 0x2029         PMERR_DYNAMIC_SEG_ZERO_INV 
 0x202A         PMERR_ELEMENT_INCOMPLETE 
 0x202B         PMERR_ESC_CODE_NOT_SUPPORTED 
 0x202C         PMERR_EXCEEDS_MAX_SEG_LENGTH 
 0x202D         PMERR_FONT_AND_MODE_MISMATCH 
 0x202E         PMERR_FONT_FILE_NOT_LOADED 
 0x202F         PMERR_FONT_NOT_LOADED 
 0x2030         PMERR_FONT_TOO_BIG 
 0x2031         PMERR_HARDWARE_INIT_FAILURE 
 0x2032         PMERR_HBITMAP_BUSY 
 0x2033         PMERR_HDC_BUSY 
 0x2034         PMERR_HRGN_BUSY 
 0x2035         PMERR_HUGE_FONTS_NOT_SUPPORTED 
 0x2036         PMERR_ID_HAS_NO_BITMAP 
 0x2037         PMERR_IMAGE_INCOMPLETE 
 0x2038         PMERR_INCOMPAT_COLOR_FORMAT 
 0x2039         PMERR_INCOMPAT_COLOR_OPTIONS 
 0x203A         PMERR_INCOMPATIBLE_BITMAP 
 0x203B         PMERR_INCOMPATIBLE_METAFILE 
 0x203C         PMERR_INCORRECT_DC_TYPE 
 0x203D         PMERR_INSUFFICIENT_DISK_SPACE 
 0x203E         PMERR_INSUFFICIENT_MEMORY 
 0x203F         PMERR_INV_ANGLE_PARM 
 0x2040         PMERR_INV_ARC_CONTROL 
 0x2041         PMERR_INV_AREA_CONTROL 
 0x2042         PMERR_INV_ARC_POINTS 
 0x2043         PMERR_INV_ATTR_MODE 
 0x2044         PMERR_INV_BACKGROUND_COL_ATTR 
 0x2045         PMERR_INV_BACKGROUND_MIX_ATTR 
 0x2046         PMERR_INV_BITBLT_MIX 
 0x2047         PMERR_INV_BITBLT_STYLE 
 0x2048         PMERR_INV_BITMAP_DIMENSION 
 0x2049         PMERR_INV_BOX_CONTROL 
 0x204A         PMERR_INV_BOX_ROUNDING_PARM 
 0x204B         PMERR_INV_CHAR_ANGLE_ATTR 
 0x204C         PMERR_INV_CHAR_DIRECTION_ATTR 
 0x204D         PMERR_INV_CHAR_MODE_ATTR 
 0x204E         PMERR_INV_CHAR_POS_OPTIONS 
 0x204F         PMERR_INV_CHAR_SET_ATTR 
 0x2050         PMERR_INV_CHAR_SHEAR_ATTR 
 0x2051         PMERR_INV_CLIP_PATH_OPTIONS 
 0x2052         PMERR_INV_CODEPAGE 
 0x2053         PMERR_INV_COLOR_ATTR 
 0x2054         PMERR_INV_COLOR_DATA 
 0x2055         PMERR_INV_COLOR_FORMAT 
 0x2056         PMERR_INV_COLOR_INDEX 
 0x2057         PMERR_INV_COLOR_OPTIONS 
 0x2058         PMERR_INV_COLOR_START_INDEX 
 0x2059         PMERR_INV_COORD_OFFSET 
 0x205A         PMERR_INV_COORD_SPACE 
 0x205B         PMERR_INV_COORDINATE 
 0x205C         PMERR_INV_CORRELATE_DEPTH 
 0x205D         PMERR_INV_CORRELATE_TYPE 
 0x205E         PMERR_INV_CURSOR_BITMAP 
 0x205F         PMERR_INV_DC_DATA 
 0x2060         PMERR_INV_DC_TYPE 
 0x2061         PMERR_INV_DEVICE_NAME 
 0x2062         PMERR_INV_DEV_MODES_OPTIONS 
 0x2063         PMERR_INV_DRAW_CONTROL 
 0x2064         PMERR_INV_DRAW_VALUE 
 0x2065         PMERR_INV_DRAWING_MODE 
 0x2066         PMERR_INV_DRIVER_DATA 
 0x2067         PMERR_INV_DRIVER_NAME 
 0x2068         PMERR_INV_DRAW_BORDER_OPTION 
 0x2069         PMERR_INV_EDIT_MODE 
 0x206A         PMERR_INV_ELEMENT_OFFSET 
 0x206B         PMERR_INV_ELEMENT_POINTER 
 0x206C         PMERR_INV_END_PATH_OPTIONS 
 0x206D         PMERR_INV_ESC_CODE 
 0x206E         PMERR_INV_ESCAPE_DATA 
 0x206F         PMERR_INV_EXTENDED_LCID 
 0x2070         PMERR_INV_FILL_PATH_OPTIONS 
 0x2071         PMERR_INV_FIRST_CHAR 
 0x2072         PMERR_INV_FONT_ATTRS 
 0x2073         PMERR_INV_FONT_FILE_DATA 
 0x2074         PMERR_INV_FOR_THIS_DC_TYPE 
 0x2075         PMERR_INV_FORMAT_CONTROL 
 0x2076         PMERR_INV_FORMS_CODE 
 0x2077         PMERR_INV_FONTDEF 
 0x2078         PMERR_INV_GEOM_LINE_WIDTH_ATTR 
 0x2079         PMERR_INV_GETDATA_CONTROL 
 0x207A         PMERR_INV_GRAPHICS_FIELD 
 0x207B         PMERR_INV_HBITMAP 
 0x207C         PMERR_INV_HDC 
 0x207D         PMERR_INV_HJOURNAL 
 0x207E         PMERR_INV_HMF 
 0x207F         PMERR_INV_HPS 
 0x2080         PMERR_INV_HRGN 
 0x2081         PMERR_INV_ID 
 0x2082         PMERR_INV_IMAGE_DATA_LENGTH 
 0x2083         PMERR_INV_IMAGE_DIMENSION 
 0x2084         PMERR_INV_IMAGE_FORMAT 
 0x2085         PMERR_INV_IN_AREA 
 0x2086         PMERR_INV_IN_CALLED_SEG 
 0x2087         PMERR_INV_IN_CURRENT_EDIT_MODE 
 0x2088         PMERR_INV_IN_DRAW_MODE 
 0x2089         PMERR_INV_IN_ELEMENT 
 0x208A         PMERR_INV_IN_IMAGE 
 0x208B         PMERR_INV_IN_PATH 
 0x208C         PMERR_INV_IN_RETAIN_MODE 
 0x208D         PMERR_INV_IN_SEG 
 0x208E         PMERR_INV_IN_VECTOR_SYMBOL 
 0x208F         PMERR_INV_INFO_TABLE 
 0x2090         PMERR_INV_JOURNAL_OPTION 
 0x2091         PMERR_INV_KERNING_FLAGS 
 0x2092         PMERR_INV_LENGTH_OR_COUNT 
 0x2093         PMERR_INV_LINE_END_ATTR 
 0x2094         PMERR_INV_LINE_JOIN_ATTR 
 0x2095         PMERR_INV_LINE_TYPE_ATTR 
 0x2096         PMERR_INV_LINE_WIDTH_ATTR 
 0x2097         PMERR_INV_LOGICAL_ADDRESS 
 0x2098         PMERR_INV_MARKER_BOX_ATTR 
 0x2099         PMERR_INV_MARKER_SET_ATTR 
 0x209A         PMERR_INV_MARKER_SYMBOL_ATTR 
 0x209B         PMERR_INV_MATRIX_ELEMENT 
 0x209C         PMERR_INV_MAX_HITS 
 0x209D         PMERR_INV_METAFILE 
 0x209E         PMERR_INV_METAFILE_LENGTH 
 0x209F         PMERR_INV_METAFILE_OFFSET 
 0x20A0         PMERR_INV_MICROPS_DRAW_CONTROL 
 0x20A1         PMERR_INV_MICROPS_FUNCTION 
 0x20A2         PMERR_INV_MICROPS_ORDER 
 0x20A3         PMERR_INV_MIX_ATTR 
 0x20A4         PMERR_INV_MODE_FOR_OPEN_DYN 
 0x20A5         PMERR_INV_MODE_FOR_REOPEN_SEG 
 0x20A6         PMERR_INV_MODIFY_PATH_MODE 
 0x20A7         PMERR_INV_MULTIPLIER 
 0x20A8         PMERR_INV_NESTED_FIGURES 
 0x20A9         PMERR_INV_OR_INCOMPAT_OPTIONS 
 0x20AA         PMERR_INV_ORDER_LENGTH 
 0x20AB         PMERR_INV_ORDERING_PARM 
 0x20AC         PMERR_INV_OUTSIDE_DRAW_MODE 
 0x20AD         PMERR_INV_PAGE_VIEWPORT 
 0x20AE         PMERR_INV_PATH_ID 
 0x20AF         PMERR_INV_PATH_MODE 
 0x20B0         PMERR_INV_PATTERN_ATTR 
 0x20B1         PMERR_INV_PATTERN_REF_PT_ATTR 
 0x20B2         PMERR_INV_PATTERN_SET_ATTR 
 0x20B3         PMERR_INV_PATTERN_SET_FONT 
 0x20B4         PMERR_INV_PICK_APERTURE_OPTION 
 0x20B5         PMERR_INV_PICK_APERTURE_POSN 
 0x20B6         PMERR_INV_PICK_APERTURE_SIZE 
 0x20B7         PMERR_INV_PICK_NUMBER 
 0x20B8         PMERR_INV_PLAY_METAFILE_OPTION 
 0x20B9         PMERR_INV_PRIMITIVE_TYPE 
 0x20BA         PMERR_INV_PS_SIZE 
 0x20BB         PMERR_INV_PUTDATA_FORMAT 
 0x20BC         PMERR_INV_QUERY_ELEMENT_NO 
 0x20BD         PMERR_INV_RECT 
 0x20BE         PMERR_INV_REGION_CONTROL 
 0x20BF         PMERR_INV_REGION_MIX_MODE 
 0x20C0         PMERR_INV_REPLACE_MODE_FUNC 
 0x20C1         PMERR_INV_RESERVED_FIELD 
 0x20C2         PMERR_INV_RESET_OPTIONS 
 0x20C3         PMERR_INV_RGBCOLOR 
 0x20C4         PMERR_INV_SCAN_START 
 0x20C5         PMERR_INV_SEG_ATTR 
 0x20C6         PMERR_INV_SEG_ATTR_VALUE 
 0x20C7         PMERR_INV_SEG_CH_LENGTH 
 0x20C8         PMERR_INV_SEG_NAME 
 0x20C9         PMERR_INV_SEG_OFFSET 
 0x20CA         PMERR_INV_SETID 
 0x20CB         PMERR_INV_SETID_TYPE 
 0x20CC         PMERR_INV_SET_VIEWPORT_OPTION 
 0x20CD         PMERR_INV_SHARPNESS_PARM 
 0x20CE         PMERR_INV_SOURCE_OFFSET 
 0x20CF         PMERR_INV_STOP_DRAW_VALUE 
 0x20D0         PMERR_INV_TRANSFORM_TYPE 
 0x20D1         PMERR_INV_USAGE_PARM 
 0x20D2         PMERR_INV_VIEWING_LIMITS 
 0x20D3         PMERR_JFILE_BUSY 
 0x20D4         PMERR_JNL_FUNC_DATA_TOO_LONG 
 0x20D5         PMERR_KERNING_NOT_SUPPORTED 
 0x20D6         PMERR_LABEL_NOT_FOUND 
 0x20D7         PMERR_MATRIX_OVERFLOW 
 0x20D8         PMERR_METAFILE_INTERNAL_ERROR 
 0x20D9         PMERR_METAFILE_IN_USE 
 0x20DA         PMERR_METAFILE_LIMIT_EXCEEDED 
 0x20DB         PMERR_NAME_STACK_FULL 
 0x20DC         PMERR_NOT_CREATED_BY_DEVOPENDC 
 0x20DD         PMERR_NOT_IN_AREA 
 0x20DE         PMERR_NOT_IN_DRAW_MODE 
 0x20DF         PMERR_NOT_IN_ELEMENT 
 0x20E0         PMERR_NOT_IN_IMAGE 
 0x20E1         PMERR_NOT_IN_PATH 
 0x20E2         PMERR_NOT_IN_RETAIN_MODE 
 0x20E3         PMERR_NOT_IN_SEG 
 0x20E4         PMERR_NO_BITMAP_SELECTED 
 0x20E5         PMERR_NO_CURRENT_ELEMENT 
 0x20E6         PMERR_NO_CURRENT_SEG 
 0x20E7         PMERR_NO_METAFILE_RECORD_HANDLE 
 0x20E8         PMERR_ORDER_TOO_BIG 
 0x20E9         PMERR_OTHER_SET_ID_REFS 
 0x20EA         PMERR_OVERRAN_SEG 
 0x20EB         PMERR_OWN_SET_ID_REFS 
 0x20EC         PMERR_PATH_INCOMPLETE 
 0x20ED         PMERR_PATH_LIMIT_EXCEEDED 
 0x20EE         PMERR_PATH_UNKNOWN 
 0x20EF         PMERR_PEL_IS_CLIPPED 
 0x20F0         PMERR_PEL_NOT_AVAILABLE 
 0x20F1         PMERR_PRIMITIVE_STACK_EMPTY 
 0x20F2         PMERR_PROLOG_ERROR 
 0x20F3         PMERR_PROLOG_SEG_ATTR_NOT_SET 
 0x20F4         PMERR_PS_BUSY 
 0x20F5         PMERR_PS_IS_ASSOCIATED 
 0x20F6         PMERR_RAM_JNL_FILE_TOO_SMALL 
 0x20F7         PMERR_REALIZE_NOT_SUPPORTED 
 0x20F8         PMERR_REGION_IS_CLIP_REGION 
 0x20F9         PMERR_RESOURCE_DEPLETION 
 0x20FA         PMERR_SEG_AND_REFSEG_ARE_SAME 
 0x20FB         PMERR_SEG_CALL_RECURSIVE 
 0x20FC         PMERR_SEG_CALL_STACK_EMPTY 
 0x20FD         PMERR_SEG_CALL_STACK_FULL 
 0x20FE         PMERR_SEG_IS_CURRENT 
 0x20FF         PMERR_SEG_NOT_CHAINED 
 0x2100         PMERR_SEG_NOT_FOUND 
 0x2101         PMERR_SEG_STORE_LIMIT_EXCEEDED 
 0x2102         PMERR_SETID_IN_USE 
 0x2103         PMERR_SETID_NOT_FOUND 
 0x2104         PMERR_STARTDOC_NOT_ISSUED 
 0x2105         PMERR_STOP_DRAW_OCCURRED 
 0x2106         PMERR_TOO_MANY_METAFILES_IN_USE 
 0x2107         PMERR_TRUNCATED_ORDER 
 0x2108         PMERR_UNCHAINED_SEG_ZERO_INV 
 0x2109         PMERR_UNSUPPORTED_ATTR 
 0x210A         PMERR_UNSUPPORTED_ATTR_VALUE 
 0x210B         PMERR_ENDDOC_NOT_ISSUED 
 0x210C         PMERR_PS_NOT_ASSOCIATED 
 0x210D         PMERR_INV_FLOOD_FILL_OPTIONS 
 0x210E         PMERR_INV_FACENAME 
 0x210F         PMERR_PALETTE_SELECTED 
 0x2110         PMERR_NO_PALETTE_SELECTED 
 0x2111         PMERR_INV_HPAL 
 0x2112         PMERR_PALETTE_BUSY 
 0x2113         PMERR_START_POINT_CLIPPED 
 0x2114         PMERR_NO_FILL 
 0x2115         PMERR_INV_FACENAMEDESC 
 0x2116         PMERR_INV_BITMAP_DATA 
 0x2117         PMERR_INV_CHAR_ALIGN_ATTR 
 0x2118         PMERR_INV_HFONT 
 0x2119         PMERR_HFONT_IS_SELECTED 
 0x2120         PMERR_DRVR_NOT_SUPPORTED 
 0x2120         PMERR_RASTER_FONT 
 0x3001         HMERR_DDF_MEMORY 
 0x3002         HMERR_DDF_ALIGN_TYPE 
 0x3003         HMERR_DDF_BACKCOLOR 
 0x3004         HMERR_DDF_FORECOLOR 
 0x3005         HMERR_DDF_FONTSTYLE 
 0x3006         HMERR_DDF_REFTYPE 
 0x3007         HMERR_DDF_LIST_UNCLOSED 
 0x3008         HMERR_DDF_LIST_UNINITIALIZED 
 0x3009         HMERR_DDF_LIST_BREAKTYPE 
 0x300A         HMERR_DDF_LIST_SPACING 
 0x300B         HMERR_DDF_HINSTANCE 
 0x300C         HMERR_DDF_EXCEED_MAX_LENGTH 
 0x300D         HMERR_DDF_EXCEED_MAX_INC 
 0x300E         HMERR_DDF_INVALID_DDF 
 0x300F         HMERR_DDF_FORMAT_TYPE 
 0x3010         HMERR_DDF_INVALID_PARM 
 0x3011         HMERR_DDF_INVALID_FONT 
 0x3012         HMERR_DDF_SEVERE 
 0x4001         PMERR_SPL_DRIVER_ERROR 
 0x4001         MERR_SPL_DRIVER_ERROR 
 0x4002         PMERR_SPL_DEVICE_ERROR 
 0x4002         MERR_SPL_DEVICE_ERROR 
 0x4003         PMERR_SPL_DEVICE_NOT_INSTALLED 
 0x4003         MERR_SPL_DEVICE_NOT_INSTALLED 
 0x4004         PMERR_SPL_QUEUE_ERROR 
 0x4004         MERR_SPL_QUEUE_ERROR 
 0x4005         PMERR_SPL_INV_HSPL 
 0x4005         MERR_SPL_INV_HSPL 
 0x4006         PMERR_SPL_NO_DISK_SPACE 
 0x4006         MERR_SPL_NO_DISK_SPACE 
 0x4007         PMERR_SPL_NO_MEMORY 
 0x4007         MERR_SPL_NO_MEMORY 
 0x4008         PMERR_SPL_PRINT_ABORT 
 0x4008         MERR_SPL_PRINT_ABORT 
 0x4009         PMERR_SPL_SPOOLER_NOT_INSTALLED 
 0x4009         MERR_SPL_SPOOLER_NOT_INSTALLED 
 0x400A         PMERR_SPL_INV_FORMS_CODE 
 0x400A         MERR_SPL_INV_FORMS_CODE 
 0x400B         PMERR_SPL_INV_PRIORITY 
 0x400B         MERR_SPL_INV_PRIORITY 
 0x400C         PMERR_SPL_NO_FREE_JOB_ID 
 0x400C         MERR_SPL_NO_FREE_JOB_ID 
 0x400D         PMERR_SPL_NO_DATA 
 0x400D         MERR_SPL_NO_DATA 
 0x400E         PMERR_SPL_INV_TOKEN 
 0x400E         MERR_SPL_INV_TOKEN 
 0x400F         PMERR_SPL_INV_DATATYPE 
 0x400F         MERR_SPL_INV_DATATYPE 
 0x4010         PMERR_SPL_PROCESSOR_ERROR 
 0x4010         MERR_SPL_PROCESSOR_ERROR 
 0x4011         PMERR_SPL_INV_JOB_ID 
 0x4011         MERR_SPL_INV_JOB_ID 
 0x4012         PMERR_SPL_JOB_NOT_PRINTING 
 0x4012         MERR_SPL_JOB_NOT_PRINTING 
 0x4013         PMERR_SPL_JOB_PRINTING 
 0x4013         MERR_SPL_JOB_PRINTING 
 0x4014         PMERR_SPL_QUEUE_ALREADY_EXISTS 
 0x4014         MERR_SPL_QUEUE_ALREADY_EXISTS 
 0x4015         PMERR_SPL_INV_QUEUE_NAME 
 0x4015         MERR_SPL_INV_QUEUE_NAME 
 0x4016         PMERR_SPL_QUEUE_NOT_EMPTY 
 0x4016         MERR_SPL_QUEUE_NOT_EMPTY 
 0x4017         PMERR_SPL_DEVICE_ALREADY_EXISTS 
 0x4017         MERR_SPL_DEVICE_ALREADY_EXISTS 
 0x4018         PMERR_SPL_DEVICE_LIMIT_REACHED 
 0x4018         MERR_SPL_DEVICE_LIMIT_REACHED 
 0x4019         PMERR_SPL_STATUS_STRING_TRUNC 
 0x4019         MERR_SPL_STATUS_STRING_TRUNC 
 0x401A         PMERR_SPL_INV_LENGTH_OR_COUNT 
 0x401A         MERR_SPL_INV_LENGTH_OR_COUNT 
 0x401B         PMERR_SPL_FILE_NOT_FOUND 
 0x401B         MERR_SPL_FILE_NOT_FOUND 
 0x401C         PMERR_SPL_CANNOT_OPEN_FILE 
 0x401C         MERR_SPL_CANNOT_OPEN_FILE 
 0x401D         PMERR_SPL_DRIVER_NOT_INSTALLED 
 0x401D         MERR_SPL_DRIVER_NOT_INSTALLED 
 0x401E         PMERR_SPL_INV_PROCESSOR_DATTYPE 
 0x401E         MERR_SPL_INV_PROCESSOR_DATTYPE 
 0x401F         PMERR_SPL_INV_DRIVER_DATATYPE 
 0x401F         MERR_SPL_INV_DRIVER_DATATYPE 
 0x4020         PMERR_SPL_PROCESSOR_NOT_INST 
 0x4020         MERR_SPL_PROCESSOR_NOT_INST 
 0x4021         PMERR_SPL_NO_SUCH_LOG_ADDRESS 
 0x4021         MERR_SPL_NO_SUCH_LOG_ADDRESS 
 0x4022         PMERR_SPL_PRINTER_NOT_FOUND 
 0x4022         MERR_SPL_PRINTER_NOT_FOUND 
 0x4023         PMERR_SPL_DD_NOT_FOUND 
 0x4023         MERR_SPL_DD_NOT_FOUND 
 0x4024         PMERR_SPL_QUEUE_NOT_FOUND 
 0x4024         MERR_SPL_QUEUE_NOT_FOUND 
 0x4025         PMERR_SPL_MANY_QUEUES_ASSOC 
 0x4025         MERR_SPL_MANY_QUEUES_ASSOC 
 0x4026         PMERR_SPL_NO_QUEUES_ASSOCIATED 
 0x4026         MERR_SPL_NO_QUEUES_ASSOCIATED 
 0x4027         PMERR_SPL_INI_FILE_ERROR 
 0x4027         MERR_SPL_INI_FILE_ERROR 
 0x4028         PMERR_SPL_NO_DEFAULT_QUEUE 
 0x4028         MERR_SPL_NO_DEFAULT_QUEUE 
 0x4029         PMERR_SPL_NO_CURRENT_FORMS_CODE 
 0x4029         MERR_SPL_NO_CURRENT_FORMS_CODE 
 0x402A         PMERR_SPL_NOT_AUTHORISED 
 0x402A         MERR_SPL_NOT_AUTHORISED 
 0x402B         PMERR_SPL_TEMP_NETWORK_ERROR 
 0x402B         MERR_SPL_TEMP_NETWORK_ERROR 
 0x402C         PMERR_SPL_HARD_NETWORK_ERROR 
 0x402C         MERR_SPL_HARD_NETWORK_ERROR 
 0x402D         PMERR_DEL_NOT_ALLOWED 
 0x402D         MERR_DEL_NOT_ALLOWED 
 0x402E         PMERR_CANNOT_DEL_QP_REF 
 0x402E         MERR_CANNOT_DEL_QP_REF 
 0x402F         PMERR_CANNOT_DEL_QNAME_REF 
 0x402F         MERR_CANNOT_DEL_QNAME_REF 
 0x4030         PMERR_CANNOT_DEL_PRINTER_DD_REF 
 0x4030         MERR_CANNOT_DEL_PRINTER_DD_REF 
 0x4031         PMERR_CANNOT_DEL_PRN_NAME_REF 
 0x4031         MERR_CANNOT_DEL_PRN_NAME_REF 
 0x4032         PMERR_CANNOT_DEL_PRN_ADDR_REF 
 0x4032         MERR_CANNOT_DEL_PRN_ADDR_REF 
 0x4033         PMERR_SPOOLER_QP_NOT_DEFINED 
 0x4033         MERR_SPOOLER_QP_NOT_DEFINED 
 0x4034         PMERR_PRN_NAME_NOT_DEFINED 
 0x4034         MERR_PRN_NAME_NOT_DEFINED 
 0x4035         PMERR_PRN_ADDR_NOT_DEFINED 
 0x4035         MERR_PRN_ADDR_NOT_DEFINED 
 0x4036         PMERR_PRINTER_DD_NOT_DEFINED 
 0x4036         MERR_PRINTER_DD_NOT_DEFINED 
 0x4037         PMERR_PRINTER_QUEUE_NOT_DEFINED 
 0x4037         MERR_PRINTER_QUEUE_NOT_DEFINED 
 0x4038         PMERR_PRN_ADDR_IN_USE 
 0x4038         MERR_PRN_ADDR_IN_USE 
 0x4039         PMERR_SPL_TOO_MANY_OPEN_FILES 
 0x4039         MERR_SPL_TOO_MANY_OPEN_FILES 
 0x403A         PMERR_SPL_CP_NOT_REQD 
 0x403A         MERR_SPL_CP_NOT_REQD 
 0x4040         PMERR_UNABLE_TO_CLOSE_DEVICE 
 0x4040         MERR_UNABLE_TO_CLOSE_DEVICE 
 0x4FC9         PMERR_SPLMSGBOX_INFO_CAPTION 
 0x4FC9         MERR_SPLMSGBOX_INFO_CAPTION 
 0x4FCA         PMERR_SPLMSGBOX_WARNING_CAPTION 
 0x4FCA         MERR_SPLMSGBOX_WARNING_CAPTION 
 0x4FCB         PMERR_SPLMSGBOX_ERROR_CAPTION 
 0x4FCB         MERR_SPLMSGBOX_ERROR_CAPTION 
 0x4FCC         PMERR_SPLMSGBOX_SEVERE_CAPTION 
 0x4FCC         MERR_SPLMSGBOX_SEVERE_CAPTION 
 0x4FCD         PMERR_SPLMSGBOX_JOB_DETAILS 
 0x4FCD         MERR_SPLMSGBOX_JOB_DETAILS 
 0x4FCE         PMERR_SPLMSGBOX_ERROR_ACTION 
 0x4FCE         MERR_SPLMSGBOX_ERROR_ACTION 
 0x4FCF         PMERR_SPLMSGBOX_SEVERE_ACTION 
 0x4FCF         MERR_SPLMSGBOX_SEVERE_ACTION 
 0x4FD0         PMERR_SPLMSGBOX_BIT_0_TEXT 
 0x4FD0         MERR_SPLMSGBOX_BIT_0_TEXT 
 0x4FD1         PMERR_SPLMSGBOX_BIT_1_TEXT 
 0x4FD1         MERR_SPLMSGBOX_BIT_1_TEXT 
 0x4FD2         PMERR_SPLMSGBOX_BIT_2_TEXT 
 0x4FD2         MERR_SPLMSGBOX_BIT_2_TEXT 
 0x4FD3         PMERR_SPLMSGBOX_BIT_3_TEXT 
 0x4FD3         MERR_SPLMSGBOX_BIT_3_TEXT 
 0x4FD4         PMERR_SPLMSGBOX_BIT_4_TEXT 
 0x4FD4         MERR_SPLMSGBOX_BIT_4_TEXT 
 0x4FD5         PMERR_SPLMSGBOX_BIT_5_TEXT 
 0x4FD5         MERR_SPLMSGBOX_BIT_5_TEXT 
 0x4FD6         PMERR_SPLMSGBOX_BIT_15_TEXT 
 0x4FD6         MERR_SPLMSGBOX_BIT_15_TEXT 
 0x4FD7         PMERR_SPL_NOPATHBUFFER 
 0x4FD7         MERR_SPL_NOPATHBUFFER 
 0x4FD8         MERR_SPL_ALREADY_INITIALISED 
 0x4FD9         MERR_SPL_ERROR 
 0x5001         PMERR_INV_TYPE 
 0x5001         MERR_INV_TYPE 
 0x5002         PMERR_INV_CONV 
 0x5002         MERR_INV_CONV 
 0x5003         PMERR_INV_SEGLEN 
 0x5003         MERR_INV_SEGLEN 
 0x5004         PMERR_DUP_SEGNAME 
 0x5004         MERR_DUP_SEGNAME 
 0x5005         PMERR_INV_XFORM 
 0x5005         MERR_INV_XFORM 
 0x5006         PMERR_INV_VIEWLIM 
 0x5006         MERR_INV_VIEWLIM 
 0x5007         PMERR_INV_3DCOORD 
 0x5007         MERR_INV_3DCOORD 
 0x5008         PMERR_SMB_OVFLOW 
 0x5008         MERR_SMB_OVFLOW 
 0x5009         PMERR_SEG_OVFLOW 
 0x5009         MERR_SEG_OVFLOW 
 0x5010         PMERR_PIC_DUP_FILENAME 
 0x5010         MERR_PIC_DUP_FILENAME 
 SPLERR_BASE+0FA1   PMERR_SPL_ERROR_1 
 SPLERR_BASE+0FA2   PMERR_SPL_ERROR_2 
 SPLERR_BASE+0FA3   PMERR_SPL_ERROR_3 
 SPLERR_BASE+0FA4   PMERR_SPL_ERROR_4 
 SPLERR_BASE+0FA5   PMERR_SPL_ERROR_5 
 SPLERR_BASE+0FA6   PMERR_SPL_ERROR_6 
 SPLERR_BASE+0FA7   PMERR_SPL_ERROR_7 
 SPLERR_BASE+0FA8   PMERR_SPL_ERROR_8 
 SPLERR_BASE+0FA9   PMERR_SPL_ERROR_9 
 SPLERR_BASE+0FAA   PMERR_SPL_ERROR_10 
 SPLERR_BASE+0FAB   PMERR_SPL_ERROR_11 
 SPLERR_BASE+0FAC   PMERR_SPL_ERROR_12 
 SPLERR_BASE+0FAD   PMERR_SPL_ERROR_13 
 SPLERR_BASE+0FAE   PMERR_SPL_ERROR_14 
 SPLERR_BASE+0FAF   PMERR_SPL_ERROR_15 
 SPLERR_BASE+0FB0   PMERR_SPL_ERROR_16 
 SPLERR_BASE+0FB1   PMERR_SPL_ERROR_17 
 SPLERR_BASE+0FB2   PMERR_SPL_ERROR_18 
 SPLERR_BASE+0FB3   PMERR_SPL_ERROR_19 
 SPLERR_BASE+0FB4   PMERR_SPL_ERROR_20 
 SPLERR_BASE+0FB5   PMERR_SPL_ERROR_21 
 SPLERR_BASE+0FB6   PMERR_SPL_ERROR_22 
 SPLERR_BASE+0FB7   PMERR_SPL_ERROR_23 
 SPLERR_BASE+0FB8   PMERR_SPL_ERROR_24 
 SPLERR_BASE+0FB9   PMERR_SPL_ERROR_25 
 SPLERR_BASE+0FBA   PMERR_SPL_ERROR_26 
 SPLERR_BASE+0FBB   PMERR_SPL_ERROR_27 
 SPLERR_BASE+0FBC   PMERR_SPL_ERROR_28 
 SPLERR_BASE+0FBD   PMERR_SPL_ERROR_29 
 SPLERR_BASE+0FBE   PMERR_SPL_ERROR_30 
 SPLERR_BASE+0FBF   PMERR_SPL_ERROR_31 
 SPLERR_BASE+0FC0   PMERR_SPL_ERROR_32 
 SPLERR_BASE+0FC1   PMERR_SPL_ERROR_33 
 SPLERR_BASE+0FC2   PMERR_SPL_ERROR_34 
 SPLERR_BASE+0FC3   PMERR_SPL_ERROR_35 
 SPLERR_BASE+0FC4   PMERR_SPL_ERROR_36 
 SPLERR_BASE+0FC5   PMERR_SPL_ERROR_37 
 SPLERR_BASE+0FC6   PMERR_SPL_ERROR_38 
 SPLERR_BASE+0FC7   PMERR_SPL_ERROR_39 
 SPLERR_BASE+0FC8   PMERR_SPL_ERROR_40 
 SPLERR_BASE+0FFF   PMERR_SPL_ERROR 
 SPLERR_BASE+0FFD   PMERR_SPL_ALREADY_INITIALISED 


═══ 4.2. Error Name and Explanation ═══

This appendix gives an explanation for each PM error. The errors are listed in 
alphabetic order. The number associated with each error is given in Error 
Number and Name. 

 Error Constant                                  Explanation 

 HMERR_ALLOCATE_SEGMENT                          Unable to allocate a segment 
                                                 of memory for memory 
                                                 allocation requests from the 
                                                 Help Manager. 

 HMERR_CLOSE_LIB_FILE                            The library file cannot be 
                                                 closed. 

 HMERR_CONTENT_NOT_FOUND                         The library file does not have 
                                                 any content. 

 HMERR_DATABASE_NOT_OPEN                         Unable to read the unopened 
                                                 database. 

 HMERR_DDF_ALIGN_TYPE                            The alignment type is not 
                                                 valid. 

 HMERR_DDF_BACKCOLOR                             The background color is not 
                                                 valid. 

 HMERR_DDF_EXCEED_MAX_INC                        The value specified to 
                                                 increment DDF memory is too 
                                                 large. 

 HMERR_DDF_EXCEED_MAX_LENGTH                     The amount of data is too 
                                                 large for the DDF buffer. 

 HMERR_DDF_FONTSTYLE                             The font style is not valid. 

 HMERR_DDF_FORECOLOR                             The foreground color is not 
                                                 valid. 

 HMERR_DDF_FORMAT_TYPE                           The format type specified is 
                                                 invalid. 

 HMERR_DDF_HINSTANCE                             The DDF instance is invalid. 

 HMERR_DDF_INVALID_DDF                           The DDF handle is invalid. 

 HMERR_DDF_INVALID_FONT                          The font value specified is 
                                                 invalid. 

 HMERR_DDF_INVALID_PARM                          One of the DDF parameters 
                                                 specified is invalid. 

 HMERR_DDF_LIST_BREAKTYPE                        The value of BreakType is not 
                                                 valid. 

 HMERR_DDF_LIST_SPACING                          The value for Spacing is not 
                                                 valid. 

 HMERR_DDF_LIST_UNCLOSED                         An attempt was made to nest a 
                                                 list. 

 HMERR_DDF_LIST_UNINITIALIZED                    No definition list has been 
                                                 initialized by DdfBeginList. 

 HMERR_DDF_MEMORY                                Not enough memory is 
                                                 available. 

 HMERR_DDF_REFTYPE                               The reference type is not 
                                                 valid. 

 HMERR_DDF_SEVERE                                Internal error detected by the 
                                                 Help Manager. 

 HMERR_FREE_MEMORY                               Unable to free allocated 
                                                 memory. 

 HMERR_HELP_INST_CALLED_INVALID                  The handle of the instance 
                                                 specified on a call to the 
                                                 Help Manager does not have the 
                                                 class name of a Help Manager 
                                                 instance. 

 HMERR_HELP_INSTANCE_UNDEFINE                    The help instance handle 
                                                 specified is invalid. 

 HMERR_HELPITEM_NOT_FOUND                        Context-sensitive help was 
                                                 requested but the ID of the 
                                                 main help item specified was 
                                                 not found in the help table. 

 HMERR_HELPSUBITEM_NOT_FOUND                     Context-sensitive help was 
                                                 requested but the ID of the 
                                                 help item specified was not 
                                                 found in the help subtable. 

 HMERR_HELPTABLE_UNDEFINE                        The application did not 
                                                 provide a help table for 
                                                 context-sensitive help. 

 HMERR_INDEX_NOT_FOUND                           The index is not in the 
                                                 library file. 

 HMERR_INVALID_ASSOC_APP_WND                     The application window handle 
                                                 specified on the 
                                                 WinAssociateHelpInstance 
                                                 function is not a valid window 
                                                 handle. 

 HMERR_INVALID_ASSOC_HELP_INST                   The help instance handle 
                                                 specified on the 
                                                 WinAssociateHelpInstance 
                                                 function is not a valid window 
                                                 handle. 

 HMERR_INVALID_DESTROY_HELP_INST                 The window handle specified as 
                                                 the help instance to destroy 
                                                 is not of the help instance 
                                                 class. 

 HMERR_INVALID_HELP_INSTANCE_HDL                 The handle specified to be a 
                                                 help instance does not have 
                                                 the class name of a Help 
                                                 Manager instance. 

 HMERR_INVALID_HELPSUBITEM_SIZE                  The help subtable item size is 
                                                 less than 2. 

 HMERR_INVALID_LIB_FILE                          Improper library file 
                                                 provided. 

 HMERR_INVALID_QUERY_APP_WND                     The application window 
                                                 specified on a 
                                                 WinQueryHelpInstance function 
                                                 is not a valid window handle. 

 HMERR_LOAD_DLL                                  Unable to load resource data 
                                                 link library. 

 HMERR_NO_FRAME_WND_IN_CHAIN                     There is no frame window in 
                                                 the window chain from which to 
                                                 find or set the associated 
                                                 help instance. 

 HMERR_NO_HELP_INST_IN_CHAIN                     The parent or owner chain of 
                                                 the application window 
                                                 specified does not have an 
                                                 associated help instance. 

 HMERR_NO_MEMORY                                 Unable to allocate the 
                                                 requested amount of memory. 

 HMERR_OPEN_LIB_FILE                             The library file cannot be 
                                                 opened. 

 HMERR_PANEL_NOT_FOUND                           Unable to find the requested 
                                                 help panel. 

 HMERR_READ_LIB_FILE                             The library file cannot be 
                                                 read. 

 PMERR_ACCESS_DENIED                             The memory block was not 
                                                 allocated properly. 

 PMERR_ALREADY_IN_AREA                           An attempt was made to begin a 
                                                 new area while an existing 
                                                 area bracket was already open. 

 PMERR_ALREADY_IN_ELEMENT                        An attempt was made to begin a 
                                                 new element while an existing 
                                                 element bracket was already 
                                                 open. 

 PMERR_ALREADY_IN_PATH                           An attempt was made to begin a 
                                                 new path while an existing 
                                                 path bracket was already open. 

 PMERR_ALREADY_IN_SEG                            An attempt was made to open a 
                                                 new segment while an existing 
                                                 segment bracket was already 
                                                 open. 

 PMERR_APPL_STRUCTURE_TOO_SMALL                  The application buffer length 
                                                 is less than the total length 
                                                 required for the (application) 
                                                 component types. 

 PMERR_AREA_INCOMPLETE                           One of the following has 
                                                 occurred: 

                                                                                                  o A segment has been opened , closed,
                                                                                                   or drawn.
                                                                                                  o GpiAssociate was issued while an
                                                                                                   area bracket was open.
                                                                                                  o A drawn segment has opened an area
                                                                                                   bracket and ended without closing it.

 PMERR_ARRAY_TOO_LARGE                           More than 4 bytes was 
                                                 attempted to be inserted or 
                                                 extracted. 

 PMERR_ARRAY_TOO_SMALL                           The array specified was too 
                                                 small. 

 PMERR_ATOM_NAME_NOT_FOUND                       The specified atom name is not 
                                                 in the atom table. 

 PMERR_BASE_ERROR                                An OS/2 base error has 
                                                 occurred.  The base error code 
                                                 can be accessed using the 
                                                 OffBinaryData field of the 
                                                 ERRINFO structure returned by 
                                                 WinGetErrorInfo. 

 PMERR_BITMAP_IN_USE                             An attempt was made either to 
                                                 set a bit map into a device 
                                                 context using GpiSetBitmap 
                                                 while it was already selected 
                                                 into an existing device 
                                                 context, or to tag a bit map 
                                                 with a local pattern set 
                                                 identifier (setid) using 
                                                 GpiSetBitmapId while it was 
                                                 already tagged with an 
                                                 existing setid. 

 PMERR_BITMAP_IS_SELECTED                        An attempt was made to delete 
                                                 a bit map while it was 
                                                 selected into a device 
                                                 context. 

 PMERR_BITMAP_NOT_FOUND                          A attempt was made to perform 
                                                 a bit-map operation on a bit 
                                                 map that did not exist. 

 PMERR_BITMAP_NOT_SELECTED                       A attempt was made to perform 
                                                 an operation on presentation 
                                                 space associated with a memory 
                                                 device context that had no 
                                                 selected bit map. 

 PMERR_BOUNDS_OVERFLOW                           An internal overflow error 
                                                 occurred during boundary data 
                                                 accumulation.  This can occur 
                                                 if coordinates or matrix 
                                                 transformation elements (or 
                                                 both) are invalid or too 
                                                 large. 

 PMERR_BUFFER_TOO_SMALL                          The supplied buffer was not 
                                                 large enough for the data to 
                                                 be returned. 

 PMERR_C_LENGTH_TOO_SMALL                        The maximum length of the C 
                                                 structure is less than the 
                                                 total length required for the 
                                                 (C) component types. 

 PMERR_CALLED_SEG_IS_CHAINED                     An attempt was made to call a 
                                                 segment that has a chained 
                                                 attribute set. 

 PMERR_CALLED_SEG_IS_CURRENT                     An attempt was made to call a 
                                                 segment that is currently 
                                                 open. 

 PMERR_CALLED_SEG_NOT_FOUND                      An attempt was made to call a 
                                                 segment that did not exist. 

 PMERR_CAN_NOT_CALL_SPOOLER                      An error occurred attempting 
                                                 to call the spooler validation 
                                                 routine.  This error is not 
                                                 raised if the spooler is not 
                                                 installed. 

 PMERR_CANNOT_DEL_PRINTER_DD_REF                 Presentation Manager device 
                                                 driver deletion not possible 
                                                 due to a reference. 

 PMERR_CANNOT_DEL_PRN_ADDR_REF                   Printer port deletion not 
                                                 possible due to a reference. 

 PMERR_CANNOT_DEL_PRN_NAME_REF                   Printer deletion not possible 
                                                 due to a reference. 

 PMERR_CANNOT_DEL_QNAME_REF                      Spooler queue deletion not 
                                                 possible due to a reference. 

 PMERR_CANNOT_DEL_QP_REF                         Spooler queue processor 
                                                 deletion not possible due to a 
                                                 reference. 

 PMERR_CANNOT_SET_FOCUS                          Focus cannot be set if a focus 
                                                 change is in progress, or if a 
                                                 system-modal window exists. 

 PMERR_CANNOT_STOP                               The session cannot be stopped. 

 PMERR_COL_TABLE_NOT_REALIZABLE                  An attempt was made to realize 
                                                 a color table that is not 
                                                 realizable. 

 PMERR_COL_TABLE_NOT_REALIZED                    An attempt was made to realize 
                                                 a color table on a device 
                                                 driver that does not support 
                                                 this function. 

 PMERR_COORDINATE_OVERFLOW                       An internal coordinate 
                                                 overflow error occurred.  This 
                                                 can occur if coordinates or 
                                                 matrix transformation elements 
                                                 (or both) are invalid or too 
                                                 large. 

 PMERR_DATA_TOO_LONG                             An attempt was made to 
                                                 transfer more than the maximum 
                                                 permitted amount of data 
                                                 (64512 bytes) using 
                                                 GpiPutData, GpiGetData, or 
                                                 GpiElement. 

 PMERR_DATATYPE_ENTRY_BAD_INDEX                  An invalid datatype entry 
                                                 index was specified. 

 PMERR_DATATYPE_ENTRY_CTL_BAD                    An invalid datatype entry 
                                                 control was specified. 

 PMERR_DATATYPE_ENTRY_CTL_MISS                   The datatype entry control was 
                                                 missing. 

 PMERR_DATATYPE_ENTRY_NOT_NUM                    The datatype entry specified 
                                                 was not numerical. 

 PMERR_DATATYPE_ENTRY_NOT_OFF                    The datatype entry specified 
                                                 was not an offset. 

 PMERR_DATATYPE_INVALID                          An invalid datatype was 
                                                 specified. 

 PMERR_DATATYPE_NOT_UNIQUE                       An attempt to register a 
                                                 datatype failed because it is 
                                                 not unique. 

 PMERR_DATATYPE_TOO_LONG                         The datatype specified was too 
                                                 long. 

 PMERR_DATATYPE_TOO_SMALL                        The datatype specified was too 
                                                 small. 

 PMERR_DC_IS_ASSOCIATED                          An attempt was made to 
                                                 associate a presentation space 
                                                 with a device context that was 
                                                 already associated or to 
                                                 destroy a device context that 
                                                 was associated. 

 PMERR_DEL_NOT_ALLOWED                           Deletion not possible. 

 PMERR_DESC_STRING_TRUNCATED                     An attempt was made to supply 
                                                 a description string with 
                                                 GpiBeginElement that was 
                                                 greater then the permitted 
                                                 maximum length (251 
                                                 characters).  The string was 
                                                 truncated. 

 PMERR_DEV_FUNC_NOT_INSTALLED                    The function requested is not 
                                                 supported by the presentation 
                                                 driver. 

 PMERR_DEVICE_DRIVER_ERROR_1                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_10                    Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_2                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_3                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_4                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_5                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_6                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_7                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_8                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DEVICE_DRIVER_ERROR_9                     Miscellaneous error available 
                                                 for use by user written device 
                                                 drivers. 

 PMERR_DOS_ERROR                                 A DOS call returned an error. 

 PMERR_DOSOPEN_FAILURE                           A DosOpen call made during 
                                                 GpiLoadMetaFile or 
                                                 GpiSaveMetaFile gave a good 
                                                 return code but the file was 
                                                 not opened successfully. 

 PMERR_DOSREAD_FAILURE                           A DosRead call made during 
                                                 GpiLoadMetaFile gave a good 
                                                 return code.  However, it 
                                                 failed to read any more bytes 
                                                 although the file length 
                                                 indicated that there were more 
                                                 to be read. 

 PMERR_DRIVER_NOT_FOUND                          The device driver specified 
                                                 with DevPostDeviceModes was 
                                                 not found. 

 PMERR_DUP_SEG                                   During GpiPlayMetaFile, while 
                                                 the actual drawing mode was 
                                                 draw-and-retain or retain, a 
                                                 metafile segment to be stored 
                                                 in the presentation space was 
                                                 found to have the same segment 
                                                 identifier as an existing 
                                                 segment. 

 PMERR_DUP_SEGNAME                               A called segment has a name 
                                                 that has already been used by 
                                                 another called segment in the 
                                                 input PIF. 

 PMERR_DUPLICATE_TITLE                           The program title specified in 
                                                 the PIBSTRUCT already exists 
                                                 within the same group. 

 PMERR_DYNAMIC_SEG_SEQ_ERROR                     During removal of dynamic 
                                                 segments while processing 
                                                 GpiDrawChain, GpiDrawFrom, or 
                                                 GpiDrawSegment, the internal 
                                                 state indicated that dynamic 
                                                 segment data was still visible 
                                                 after all chained dynamic 
                                                 segments had been processed. 
                                                 This can occur if segments 
                                                 drawn dynamically (including 
                                                 called segments) are modified 
                                                 or removed from the chain 
                                                 while visible. 

 PMERR_DYNAMIC_SEG_ZERO_INV                      An attempt was been made to 
                                                 open a dynamic segment with a 
                                                 segment identifier of zero. 

 PMERR_ENDDOC_NOT_ISSUED                         A request to close the spooled 
                                                 output without first issuing a 
                                                 an ENDDOC was attempted. 

 PMERR_ESC_CODE_NOT_SUPPORTED                    The code specified with 
                                                 DevEscape is not supported by 
                                                 the target device driver. 

 PMERR_EXCEEDS_MAX_SEG_LENGTH                    During metafile creation or 
                                                 generation of retained 
                                                 graphics the system has 
                                                 exceeded maximum segment size. 

 PMERR_FONT_AND_MODE_MISMATCH                    An attempt was made to draw 
                                                 characters with a character 
                                                 mode and character set that 
                                                 are incompatible.  For 
                                                 example, the character 
                                                 specifies an image/raster font 
                                                 when the mode calls for a 
                                                 vector/outline font. 

 PMERR_FONT_FILE_NOT_LOADED                      An attempt was made to unload 
                                                 a font file that was not 
                                                 loaded. 

 PMERR_FONT_NOT_LOADED                           An attempt was made to create 
                                                 a font that was not loaded. 

 PMERR_FUNCTION_NOT_SUPPORTED                    The function is not supported. 

 PMERR_GREATER_THAN_64K                          A data item or array dimension 
                                                 is greater than 65 535. 

 PMERR_HBITMAP_BUSY                              An internal bit map busy error 
                                                 was detected.  The bit map was 
                                                 locked by one thread during an 
                                                 attempt to access it from 
                                                 another thread. 

 PMERR_HDC_BUSY                                  An internal device context 
                                                 busy error was detected.  The 
                                                 device context was locked by 
                                                 one thread during an attempt 
                                                 to access it from another 
                                                 thread. 

 PMERR_HEAP_MAX_SIZE_REACHED                     The heap has reached its 
                                                 maximum size (64KB), and 
                                                 cannot be increased. 

 PMERR_HEAP_OUT_OF_MEMORY                        An attempt to increase the 
                                                 size of the heap failed. 

 PMERR_HFONT_IS_SELECTED                         An attempt has been made to 
                                                 either change the owner of a 
                                                 font, or delete when it is 
                                                 currently selected. 

 PMERR_HRGN_BUSY                                 An internal region busy error 
                                                 was detected.  The region was 
                                                 locked by one thread during an 
                                                 attempt to access it from 
                                                 another thread. 

 PMERR_HUGE_FONTS_NOT_SUPPORTED                  An attempt was made using 
                                                 GpiSetCharSet, 
                                                 GpiSetPatternSet, 
                                                 GpiSetMarkerSet, or 
                                                 GpiSetAttrs to select a font 
                                                 that is larger than the 
                                                 maximum size (64Kb) supported 
                                                 by the target device driver. 

 PMERR_ID_HAS_NO_BITMAP                          No bit map was tagged with the 
                                                 setid specified on a 
                                                 GpiQueryBitmapHandle function. 

 PMERR_IMAGE_INCOMPLETE                          A drawn segment has opened an 
                                                 image bracket and ended 
                                                 without closing it. 

 PMERR_INCOMPATIBLE_BITMAP                       An attempt was made to select 
                                                 a bit map or perform a BitBlt 
                                                 operation on a device context 
                                                 that was incompatible with the 
                                                 format of the bit map. 

 PMERR_INCOMPATIBLE_METAFILE                     An attempt was made to 
                                                 associate a presentation space 
                                                 and a metafile device context 
                                                 with incompatible page units, 
                                                 size or coordinate format; or 
                                                 to play a metafile using the 
                                                 RES_RESET option (to reset the 
                                                 presentation space) to a 
                                                 presentation space that is 
                                                 itself associated with a 
                                                 metafile device context. 

 PMERR_INCORRECT_DATATYPE                        A data type is specified which 
                                                 is incorrect for this 
                                                 function. 

 PMERR_INCORRECT_DC_TYPE                         An attempt was made to perform 
                                                 a bit-map operation on a 
                                                 presentation space associated 
                                                 with a device context of a 
                                                 type that is unable to support 
                                                 bit-map operations. 

 PMERR_INCORRECT_HSTRUCT                         A structure handle is 
                                                 non-NULL, and is invalid for 
                                                 one of the following reasons: 

                                                                                                  o It is not the handle of a data structure.
                                                                                                  o It is the handle of an ERRINFO
                                                                                                   structure, which should not be used in
                                                                                                   this call.
                                                                                                  o A handle block returned by the bindings
                                                                                                   to the application has been used for an
                                                                                                   in-line structure handle.

 PMERR_INI_FILE_IS_SYS_OR_USER                   User or system initialization 
                                                 file cannot be closed. 

 PMERR_INSUFF_SPACE_TO_ADD                       The initialization file could 
                                                 not be extended to add the 
                                                 required program or group. 

 PMERR_INSUFFICIENT_DISK_SPACE                   The operation terminated 
                                                 through insufficient disk 
                                                 space. 

 PMERR_INSUFFICIENT_MEMORY                       The operation terminated 
                                                 through insufficient memory. 

 PMERR_INV_3DCOORD                               An order specifying 
                                                 3-dimensional coordinates has 
                                                 been found in the input PIF. 

 PMERR_INV_ANGLE_PARM                            An invalid angle parameter was 
                                                 specified with GpiPartialArc. 

 PMERR_INV_ARC_CONTROL                           An invalid control parameter 
                                                 was specified with GpiFullArc. 

 PMERR_INV_AREA_CONTROL                          An invalid options parameter 
                                                 was specified with 
                                                 GpiBeginArea. 

 PMERR_INV_ATTR_MODE                             An invalid mode parameter was 
                                                 specified with GpiSetAttrMode. 

 PMERR_INV_BACKGROUND_COL_ATTR                   An invalid background color 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_BACKGROUND_MIX_ATTR                   An invalid background mix 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_BITBLT_MIX                            An invalid lRop was specified 
                                                 with a GpiBitBlt or 
                                                 GpiWCBitBlt function. 

 PMERR_INV_BITBLT_STYLE                          An invalid options parameter 
                                                 was specified with a GpiBitBlt 
                                                 or GpiWCBitBlt function. 

 PMERR_INV_BITMAP_DATA                           In processing a bit map, the 
                                                 end of the data was 
                                                 unexpectedly encountered. 

 PMERR_INV_BITMAP_DIMENSION                      An invalid dimension was 
                                                 specified with a load bit-map 
                                                 function. 

 PMERR_INV_BOX_CONTROL                           An invalid control parameter 
                                                 was specified with GpiBox. 

 PMERR_INV_BOX_ROUNDING_PARM                     An invalid corner rounding 
                                                 control parameter was 
                                                 specified with GpiBox. 

 PMERR_INV_CHAR_ALIGN_ATTR                       The text alignment attribute 
                                                 specified in 
                                                 GpiSetTextAlignment is not 
                                                 valid. 

 PMERR_INV_CHAR_ANGLE_ATTR                       The default character angle 
                                                 attribute value was explicitly 
                                                 specified with GpiSetAttrs 
                                                 instead of using the defaults 
                                                 mask. 

 PMERR_INV_CHAR_DIRECTION_ATTR                   An invalid character direction 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_CHAR_MODE_ATTR                        An invalid character mode 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_CHAR_POS_OPTIONS                      An invalid options parameter 
                                                 was specified with 
                                                 GpiCharStringPos or 
                                                 GpiCharStringPosAt. 

 PMERR_INV_CHAR_SET_ATTR                         An invalid character setid 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_CHAR_SHEAR_ATTR                       An invalid character shear 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_CLIP_PATH_OPTIONS                     An invalid options parameter 
                                                 was specified with 
                                                 GpiSetClipPath. 

 PMERR_INV_CODEPAGE                              An invalid code-page parameter 
                                                 was specified with GpiSetCp. 

 PMERR_INV_COLOR_ATTR                            An invalid color attribute 
                                                 value was specified or the 
                                                 default value was explicitly 
                                                 specified with GpiSetAttrs 
                                                 instead of using the defaults 
                                                 mask. 

 PMERR_INV_COLOR_DATA                            Invalid color table definition 
                                                 data was specified with 
                                                 GpiCreateLogColorTable. 

 PMERR_INV_COLOR_FORMAT                          An invalid format parameter 
                                                 was specified with 
                                                 GpiCreateLogColorTable. 

 PMERR_INV_COLOR_INDEX                           An invalid color index 
                                                 parameter was specified with 
                                                 GpiQueryRGBColor. 

 PMERR_INV_COLOR_OPTIONS                         An invalid options parameter 
                                                 was specified with a logical 
                                                 color table or color query 
                                                 function. 

 PMERR_INV_COLOR_START_INDEX                     An invalid starting index 
                                                 parameter was specified with a 
                                                 logical color table or color 
                                                 query function. 

 PMERR_INV_CONV                                  Invalid conversion-type 
                                                 parameter. 

 PMERR_INV_COORD_OFFSET                          An invalid coordinate offset 
                                                 value was specified. 

 PMERR_INV_COORD_SPACE                           An invalid source or target 
                                                 coordinate space parameter was 
                                                 specified with GpiConvert. 

 PMERR_INV_COORDINATE                            An invalid coordinate value 
                                                 was specified. 

 PMERR_INV_CORRELATE_DEPTH                       An invalid maxdepth parameter 
                                                 was specified with 
                                                 GpiCorrelateSegment, 
                                                 GpiCorrelateFrom, or 
                                                 GpiCorrelateChain. 

 PMERR_INV_CORRELATE_TYPE                        An invalid type parameter was 
                                                 specified with 
                                                 GpiCorrelateSegment, 
                                                 GpiCorrelateFrom, or 
                                                 GpiCorrelateChain. 

 PMERR_INV_CURSOR_BITMAP                         An invalid pointer was 
                                                 referenced with WinSetPointer. 

 PMERR_INV_DC_DATA                               An invalid data parameter was 
                                                 specified with DevOpenDC. 

 PMERR_INV_DC_TYPE                               An invalid type parameter was 
                                                 specified with DevOpenDC, or a 
                                                 function was issued that is 
                                                 invalid for a 
                                                 OD_METAFILE_NOQUERY device 
                                                 context. 

 PMERR_INV_DEV_MODES_OPTIONS                     An invalid options parameter 
                                                 was specified with 
                                                 DevPostDeviceModes. 

 PMERR_INV_DEVICE_NAME                           An invalid devicename 
                                                 parameter was specified with 
                                                 DevPostDeviceModes. 

 PMERR_INV_DRAW_BORDER_OPTION                    An invalid option parameter 
                                                 was specified with 
                                                 WinDrawBorder. 

 PMERR_INV_DRAW_CONTROL                          An invalid control parameter 
                                                 was specified with 
                                                 GpiSetDrawControl or 
                                                 GpiQueryDrawControl. 

 PMERR_INV_DRAW_VALUE                            An invalid value parameter was 
                                                 specified with 
                                                 GpiSetDrawControl. 

 PMERR_INV_DRAWING_MODE                          An invalid mode parameter was 
                                                 specified with 
                                                 GpiSetDrawControl not 
                                                 draw-and-retain or draw. 

 PMERR_INV_DRIVER_DATA                           Invalid driver data was 
                                                 specified. 

 PMERR_INV_DRIVER_NAME                           A driver name was specified 
                                                 which has not been installed. 

 PMERR_INV_EDIT_MODE                             An invalid mode parameter was 
                                                 specified with GpiSetEditMode. 

 PMERR_INV_ELEMENT_OFFSET                        An invalid off (offset) 
                                                 parameter was specified with 
                                                 GpiQueryElement. 

 PMERR_INV_ELEMENT_POINTER                       An attempt was made to issue 
                                                 GpiPutData with the element 
                                                 pointer not pointing at the 
                                                 last element. 

 PMERR_INV_END_PATH_OPTIONS                      An attempt to create or delete 
                                                 a path out of context of the 
                                                 path bracket was made. 

 PMERR_INV_ESC_CODE                              An invalid escape code was 
                                                 used in a call to DevEscape. 

 PMERR_INV_ESCAPE_DATA                           An invalid data parameter was 
                                                 specified with DevEscape. 

 PMERR_INV_FACENAME                              An invalid font family name 
                                                 was passed to 
                                                 GpiQueryFaceString. 

 PMERR_INV_FACENAMEDESC                          The font facename description 
                                                 is invalid. 

 PMERR_INV_FILL_PATH_OPTIONS                     An invalid options parameter 
                                                 was specified with 
                                                 GpiFillPath. 

 PMERR_INV_FIRST_CHAR                            An invalid firstchar parameter 
                                                 was specified with 
                                                 GpiQueryWidthTable. 

 PMERR_INV_FLOOD_FILL_OPTIONS                    Invalid flood fill parameters 
                                                 were specified. 

 PMERR_INV_FONT_ATTRS                            An invalid attrs parameter was 
                                                 specified with 
                                                 GpiCreateLogFont. 

 PMERR_INV_FONT_FILE_DATA                        The font file specified with 
                                                 GpiLoadFonts, 
                                                 GpiLoadPublicFonts, 
                                                 GpiQueryFontFileDescriptions, 
                                                 or GpiQueryFullFontFileDescs 
                                                 contains invalid data. 

 PMERR_INV_FOR_THIS_DC_TYPE                      An attempt has been made to 
                                                 issue GpiRemoveDynamics or 
                                                 GpiDrawDynamics to a 
                                                 presentation space associated 
                                                 with a metafile device 
                                                 context. 

 PMERR_INV_FORMS_CODE                            An invalid forms code 
                                                 parameter was specified with 
                                                 DevQueryHardcopyCaps. 

 PMERR_INV_GEOM_LINE_WIDTH_ATTR                  An invalid geometric line 
                                                 width attribute value was 
                                                 specified. 

 PMERR_INV_GETDATA_CONTROL                       An invalid format parameter 
                                                 was specified with GpiGetData. 

 PMERR_INV_GRAPHICS_FIELD                        An invalid field parameter was 
                                                 specified with 
                                                 GpiSetGraphicsField. 

 PMERR_INV_HBITMAP                               An invalid bit-map handle was 
                                                 specified. 

 PMERR_INV_HDC                                   An invalid device-context 
                                                 handle or (micro presentation 
                                                 space) presentation-space 
                                                 handle was specified. 

 PMERR_INV_HFONT                                 An invalid font handle was 
                                                 specified. 

 PMERR_INV_HMF                                   An invalid metafile handle was 
                                                 specified. 

 PMERR_INV_HPAL                                  An invalid color palette 
                                                 handle was specified. 

 PMERR_INV_HPS                                   An invalid presentation-space 
                                                 handle was specified. 

 PMERR_INV_HRGN                                  An invalid region handle was 
                                                 specified. 

 PMERR_INV_ID                                    An invalid lPSid parameter was 
                                                 specified with GpiRestorePS. 

 PMERR_INV_IMAGE_DATA_LENGTH                     An invalid lLength parameter 
                                                 was specified with GpiImage. 
                                                 There is a mismatch between 
                                                 the image size and the data 
                                                 length. 

 PMERR_INV_IMAGE_DIMENSION                       An invalid psizlImageSize 
                                                 parameter was specified with 
                                                 GpiImage. 

 PMERR_INV_IMAGE_FORMAT                          An invalid lFormat parameter 
                                                 was specified with GpiImage. 

 PMERR_INV_IN_AREA                               An attempt was made to issue a 
                                                 function invalid inside an 
                                                 area bracket. This can be 
                                                 detected while the actual 
                                                 drawing mode is draw or 
                                                 draw-and-retain or during 
                                                 segment drawing or correlation 
                                                 functions. 

 PMERR_INV_IN_CURRENT_EDIT_MODE                  An attempt was made to issue a 
                                                 function invalid inside the 
                                                 current editing mode. 

 PMERR_INV_IN_ELEMENT                            An attempt was made to issue a 
                                                 function invalid inside an 
                                                 element bracket. 

 PMERR_INV_IN_IMAGE                              An attempt was made to issue a 
                                                 function invalid inside an 
                                                 element bracket. 

 PMERR_INV_IN_PATH                               An attempt was made to issue a 
                                                 function invalid inside a path 
                                                 bracket. 

 PMERR_INV_IN_RETAIN_MODE                        An attempt was made to issue a 
                                                 function (for example, query) 
                                                 that is invalid when the 
                                                 actual drawing mode is not 
                                                 draw or draw-and-retain. 

 PMERR_INV_IN_SEG                                An attempt was made to issue a 
                                                 function invalid inside a 
                                                 segment bracket. 

 PMERR_INV_IN_VECTOR_SYMBOL                      An invalid order was detected 
                                                 inside a vector symbol 
                                                 definition while drawing a 
                                                 vector (outline) font. 

 PMERR_INV_INFO_TABLE                            An invalid bit-map info table 
                                                 was specified with a bit-map 
                                                 operation. 

 PMERR_INV_LENGTH_OR_COUNT                       An invalid length or count 
                                                 parameter was specified. 

 PMERR_INV_LINE_END_ATTR                         An invalid line end attribute 
                                                 value was specified. 

 PMERR_INV_LINE_JOIN_ATTR                        An invalid line join attribute 
                                                 value was specified. 

 PMERR_INV_LINE_TYPE_ATTR                        An invalid line type attribute 
                                                 value was specified or the 
                                                 default value was explicitly 
                                                 specified with GpiSetAttrs 
                                                 instead of using the defaults 
                                                 mask. 

 PMERR_INV_LINE_WIDTH_ATTR                       An invalid line width 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_LOGICAL_ADDRESS                       An invalid device logical 
                                                 address was specified. 

 PMERR_INV_MARKER_BOX_ATTR                       An invalid marker box 
                                                 attribute value was specified. 

 PMERR_INV_MARKER_SET_ATTR                       An invalid marker set 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_MARKER_SYMBOL_ATTR                    An invalid marker symbol 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_MATRIX_ELEMENT                        An invalid transformation 
                                                 matrix element was specified. 

 PMERR_INV_MAX_HITS                              An invalid maxhits parameter 
                                                 was specified with 
                                                 GpiCorrelateSegment, 
                                                 GpiCorrelateFrom, or 
                                                 GpiCorrelateChain. 

 PMERR_INV_METAFILE                              An invalid metafile was 
                                                 specified with 
                                                 GpiPlayMetaFile. 

 PMERR_INV_METAFILE_LENGTH                       An invalid length parameter 
                                                 was specified with 
                                                 GpiSetMetaFileBits or 
                                                 GpiQueryMetaFileBits. 

 PMERR_INV_METAFILE_OFFSET                       An invalid length parameter 
                                                 was specified with 
                                                 GpiSetMetaFileBits or 
                                                 GpiQueryMetaFileBits. 

 PMERR_INV_MICROPS_DRAW_CONTROL                  A draw control parameter was 
                                                 specified with 
                                                 GpiSetDrawControl that is 
                                                 invalid in a micro 
                                                 presentation space. 

 PMERR_INV_MICROPS_FUNCTION                      An attempt was made to issue a 
                                                 function that is invalid in a 
                                                 micro presentation space. 

 PMERR_INV_MICROPS_ORDER                         An attempt was made to play a 
                                                 metafile containing orders 
                                                 that are invalid in a micro 
                                                 presentation space. 

 PMERR_INV_MIX_ATTR                              An invalid mix attribute value 
                                                 was specified or the default 
                                                 value was explicitly specified 
                                                 with GpiSetAttrs instead of 
                                                 using the defaults mask. 

 PMERR_INV_MODE_FOR_OPEN_DYN                     An attempt was made to open a 
                                                 segment with the ATTR_DYNAMIC 
                                                 segment set, while the drawing 
                                                 mode was set to DM_DRAW or 
                                                 DM_DRAWANDRETAIN. 

 PMERR_INV_MODE_FOR_REOPEN_SEG                   An attempt was made to reopen 
                                                 an existing segment while the 
                                                 drawing mode was set to 
                                                 DM_DRAW or DM_DRAWANDRETAIN. 

 PMERR_INV_MODIFY_PATH_MODE                      An invalid mode parameter was 
                                                 specified with GpiModifyPath. 

 PMERR_INV_MULTIPLIER                            An invalid multiplier 
                                                 parameter was specified with 
                                                 GpiPartialArc or GpiFullArc. 

 PMERR_INV_NESTED_FIGURES                        Nested figures have been 
                                                 detected within a path 
                                                 definition. 

 PMERR_INV_OR_INCOMPAT_OPTIONS                   An invalid or incompatible 
                                                 (with micro presentation 
                                                 space) options parameter was 
                                                 specified with GpiCreatePS or 
                                                 GpiSetPS. 

 PMERR_INV_ORDER_LENGTH                          An invalid order length was 
                                                 detected during GpiPutData or 
                                                 segment drawing. 

 PMERR_INV_ORDERING_PARM                         An invalid order parameter was 
                                                 specified with 
                                                 GpiSetSegmentPriority. 

 PMERR_INV_OUTSIDE_DRAW_MODE                     An attempt was made to issue a 
                                                 GpiSavePS or GpiRestorePS 
                                                 function, or an output only 
                                                 function (for example, 
                                                 GpiPaintRegion) from 
                                                 GpiPlayMetaFile without the 
                                                 drawing mode set to DM_DRAW. 

 PMERR_INV_PAGE_VIEWPORT                         An invalid viewport parameter 
                                                 was specified with 
                                                 GpiSetPageViewport. 

 PMERR_INV_PATH_ID                               An invalid path identifier 
                                                 parameter was specified. 

 PMERR_INV_PATTERN_ATTR                          An invalid pattern symbol 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_PATTERN_REF_PT_ATTR                   An invalid refpoint attribute 
                                                 value was specified. 

 PMERR_INV_PATTERN_SET_ATTR                      An invalid pattern set 
                                                 attribute value was specified 
                                                 or the default value was 
                                                 explicitly specified with 
                                                 GpiSetAttrs instead of using 
                                                 the defaults mask. 

 PMERR_INV_PATTERN_SET_FONT                      An attempt was made to use an 
                                                 unsuitable font as a pattern 
                                                 set. 

 PMERR_INV_PICK_APERTURE_OPTION                  An invalid options parameter 
                                                 was specified with 
                                                 GpiSetPickApertureSize. 

 PMERR_INV_PICK_APERTURE_POSN                    An invalid pick aperture 
                                                 position was specified. 

 PMERR_INV_PICK_APERTURE_SIZE                    An invalid size parameter was 
                                                 specified with 
                                                 GpiSetPickApertureSize. 

 PMERR_INV_PLAY_METAFILE_OPTION                  An invalid option parameter 
                                                 was specified with 
                                                 GpiPlayMetaFile. 

 PMERR_INV_PRIMITIVE_TYPE                        An invalid primitive type 
                                                 parameter was specified with 
                                                 GpiSetAttrs or GpiQueryAttrs. 

 PMERR_INV_PS_SIZE                               An invalid size parameter was 
                                                 specified with GpiCreatePS or 
                                                 GpiSetPS. 

 PMERR_INV_PUTDATA_FORMAT                        An invalid format parameter 
                                                 was specified with GpiPutData. 

 PMERR_INV_QUERY_ELEMENT_NO                      An invalid start parameter was 
                                                 specified with DevQueryCaps. 

 PMERR_INV_RECT                                  An invalid rectangle parameter 
                                                 was specified. 

 PMERR_INV_REGION_CONTROL                        An invalid control parameter 
                                                 was specified with 
                                                 GpiQueryRegionRects. 

 PMERR_INV_REGION_MIX_MODE                       An invalid mode parameter was 
                                                 specified with 
                                                 GpiCombineRegion. 

 PMERR_INV_REPLACE_MODE_FUNC                     An attempt was made to issue 
                                                 GpiPutData with the editing 
                                                 mode set to SEGEM_REPLACE. 

 PMERR_INV_RESERVED_FIELD                        An invalid reserved field was 
                                                 specified. 

 PMERR_INV_RESET_OPTIONS                         An invalid options parameter 
                                                 was specified with GpiResetPS. 

 PMERR_INV_RGBCOLOR                              An invalid rgb color parameter 
                                                 was specified with 
                                                 GpiQueryNearestColor or 
                                                 GpiQueryColor. 

 PMERR_INV_SCAN_START                            An invalid scanstart parameter 
                                                 was specified with a bit-map 
                                                 function. 

 PMERR_INV_SEG_ATTR                              An invalid attribute parameter 
                                                 was specified with 
                                                 GpiSetSegmentAttrs, 
                                                 GpiQuerySegmentAttrs, 
                                                 GpiSetInitialSegmentAttrs, or 
                                                 GpiQueryInitialSegmentAttrs. 

 PMERR_INV_SEG_ATTR_VALUE                        An invalid attribute value 
                                                 parameter was specified with 
                                                 GpiSetSegmentAttrs or 
                                                 GpiSetInitialSegmentAttrs. 

 PMERR_INV_SEG_NAME                              An invalid segment identifier 
                                                 was specified. 

 PMERR_INV_SEG_OFFSET                            An invalid offset parameter 
                                                 was specified with GpiPutData. 

 PMERR_INV_SEGLEN                                An order length exceeds the 
                                                 remaining segment length in 
                                                 the input PIF. 

 PMERR_INV_SETID                                 An invalid setid parameter was 
                                                 specified. 

 PMERR_INV_SHARPNESS_PARM                        An invalid sharpness parameter 
                                                 was specified with 
                                                 GpiPolyFilletSharp. 

 PMERR_INV_STOP_DRAW_VALUE                       An invalid value parameter was 
                                                 specified with GpiSetStopDraw. 

 PMERR_INV_TRANSFORM_TYPE                        An invalid options parameter 
                                                 was specified with a transform 
                                                 matrix function. 

 PMERR_INV_TYPE                                  Invalid file-type parameter. 

 PMERR_INV_USAGE_PARM                            An invalid options parameter 
                                                 was specified with 
                                                 GpiCreateBitmap. 

 PMERR_INV_VIEWING_LIMITS                        An invalid limits parameter 
                                                 was specified with 
                                                 GpiSetViewingLimits. 

 PMERR_INV_VIEWLIM                               A set viewing limits order has 
                                                 an inconsistent mask and order 
                                                 length in the input PIF. 

 PMERR_INV_XFORM                                 A set (default) viewing 
                                                 transform order has an 
                                                 inconsistent mask and order 
                                                 length in the input PIF. 

 PMERR_INVALID_APPL                              Attempted to start an 
                                                 application whose type is not 
                                                 recognized by OS/2. 

 PMERR_INVALID_ARRAY_COUNT                       An array has an invalid count, 
                                                 that is, less than or equal to 
                                                 zero. 

 PMERR_INVALID_ARRAY_SIZE                        A control data type array size 
                                                 is invalid. 

 PMERR_INVALID_ASCIIZ                            The profile string is not a 
                                                 valid zero-terminated string. 

 PMERR_INVALID_ATOM                              The specified atom does not 
                                                 exist in the atom table. 

 PMERR_INVALID_ATOM_NAME                         An invalid atom name string 
                                                 was passed. 

 PMERR_INVALID_BUNDLE_TYPE                       An invalid bundle type was 
                                                 passed. 

 PMERR_INVALID_CHARACTER_INDEX                   On WinNextChar or WinPrevChar, 
                                                 a character index is invalid, 
                                                 that is, it is less than 1 or 
                                                 is greater than the string 
                                                 length+1. 

 PMERR_INVALID_CONTROL_DATATYPE                  An invalid control data type 
                                                 was specified. 

 PMERR_INVALID_DATATYPE                          An invalid data type was 
                                                 specified. 

 PMERR_INVALID_DST_CODEPAGE                      The destination code page 
                                                 parameter is invalid. 

 PMERR_INVALID_ERRORINFO_HANDLE                  On WinFreeErrorInfo, the 
                                                 ERRINFO is not the handle of 
                                                 an ERRINFO structure, that is, 
                                                 it was not created by 
                                                 WinGetErrorInfo. 

 PMERR_INVALID_FLAG                              An invalid bit was set for a 
                                                 parameter. Use constants 
                                                 defined by PM for options, and 
                                                 do not set any reserved bits. 

 PMERR_INVALID_FREE_MESSAGE_ID                   An invalid message identifier 
                                                 was specified. The call has 
                                                 completed by assuming the 
                                                 message parameter and reply 
                                                 data types to be ULONG. 

 PMERR_INVALID_GROUP_HANDLE                      An invalid program-group 
                                                 handle was specified. 

 PMERR_INVALID_HACCEL                            An invalid accelerator-table 
                                                 handle was specified. 

 PMERR_INVALID_HAPP                              The application handle passed 
                                                 to WinTerminateApp does not 
                                                 correspond to a valid session. 

 PMERR_INVALID_HATOMTBL                          An invalid atom-table handle 
                                                 was specified. 

 PMERR_INVALID_HEAP_POINTER                      An invalid pointer was found 
                                                 within the heap. 

 PMERR_INVALID_HEAP_SIZE                         Invalid data was found within 
                                                 the heap. 

 PMERR_INVALID_HEAP_SIZE_PARM                    Invalid data was found within 
                                                 the heap. 

 PMERR_INVALID_HEAP_SIZE_WORD                    Invalid data was found within 
                                                 the heap. 

 PMERR_INVALID_HENUM                             An invalid enumeration handle 
                                                 was specified. 

 PMERR_INVALID_HHEAP                             An invalid heap handle was 
                                                 specified. 

 PMERR_INVALID_HMQ                               An invalid message-queue 
                                                 handle was specified. 

 PMERR_INVALID_HPTR                              An invalid pointer handle was 
                                                 specified. 

 PMERR_INVALID_HSTRUCT                           An invalid (null) structure 
                                                 handle was specified. 

 PMERR_INVALID_HWND                              An invalid window handle was 
                                                 specified. 

 PMERR_INVALID_INI_FILE_HANDLE                   An invalid initialization-file 
                                                 handle was specified. 

 PMERR_INVALID_INTEGER                           The specified atom is not a 
                                                 valid integer atom. 

 PMERR_INVALID_INTEGER_ATOM                      The specified atom is not a 
                                                 valid integer atom. 

 PMERR_INVALID_MESSAGE_ID                        A message identifier is 
                                                 invalid. 

 PMERR_INVALID_NUMBER_OF_PARMS                   The number of parameters is 
                                                 invalid. 

 PMERR_INVALID_NUMBER_OF_TYPES                   The function call has an 
                                                 invalid number (zero) of 
                                                 types. 

 PMERR_INVALID_PARAMETER                         An application parameter value 
                                                 is invalid for its converted 
                                                 PM type. For example: a 4-byte 
                                                 value outside the range 
                                                 -32,768 to +32,767 cannot be 
                                                 converted to a SHORT, and a 
                                                 negative number cannot be 
                                                 converted to a ULONG or 
                                                 USHORT. 

 PMERR_INVALID_PARAMETER_TYPE                    A parameter type is invalid 
                                                 for a bundle mask. 

 PMERR_INVALID_PARAMETERS                        An application parameter value 
                                                 is invalid for its converted 
                                                 PM type. For example: a 4-byte 
                                                 value outside the range 
                                                 -32768 to +32 767 cannot be 
                                                 converted to a SHORT, and a 
                                                 negative number cannot be 
                                                 converted to a ULONG or 
                                                 USHORT. 

  PMERR_INVALID_PARAMETERS

 PMERR_INVALID_PARM                              A parameter to the function 
                                                 contained invalid data. 

 PMERR_INVALID_PROGRAM_HANDLE                    An invalid program handle was 
                                                 specified. 

 PMERR_INVALID_SESSION_ID                        The specified session 
                                                 identifier is invalid.  Either 
                                                 zero (for the application's 
                                                 own session) or a valid 
                                                 identifier must be specified. 

 PMERR_INVALID_SRC_CODEPAGE                      The source code page parameter 
                                                 is invalid. 

 PMERR_INVALID_STRING_PARM                       The specified string parameter 
                                                 is invalid. 

 PMERR_INVALID_SWITCH_HANDLE                     An invalid Window List entry 
                                                 handle was specified. 

 PMERR_INVALID_TARGET_HANDLE                     An invalid target 
                                                 program-group handle was 
                                                 specified. 

 PMERR_INVALID_TITLE                             The specified program or group 
                                                 title is too long or contains 
                                                 invalid characters. 

 PMERR_INVALID_TYPE_FOR_LENGTH                   The data type for a control 
                                                 length is invalid. 

 PMERR_INVALID_TYPE_FOR_MPARAM                   The message parameter type for 
                                                 a control MPARAM is invalid, 
                                                 that is, not mparam1, mparam2 
                                                 or mreply. 

 PMERR_INVALID_TYPE_FOR_OFFSET                   The data type for a control 
                                                 offset is invalid. 

 PMERR_INVALID_WINDOW                            The window specified with a 
                                                 Window List call is not a 
                                                 valid frame window. 

 PMERR_KERNING_NOT_SUPPORTED                     Kerning was requested on 
                                                 GpiCreateLogFont call to a 
                                                 presentation space associated 
                                                 with a device context that 
                                                 does not support kerning. 

 PMERR_LABEL_NOT_FOUND                           The specified element label 
                                                 did not exist. 

 PMERR_MATRIX_OVERFLOW                           An internal overflow error 
                                                 occurred during matrix 
                                                 multiplication. This can occur 
                                                 if coordinates or matrix 
                                                 transformation elements (or 
                                                 both) are invalid or too 
                                                 large. 

 PMERR_MEMORY_ALLOC                              An error occurred during 
                                                 memory management. 

 PMERR_MEMORY_ALLOCATION_ERR                     An error occurred during 
                                                 memory management. 

 PMERR_MEMORY_DEALLOCATION_ERR                   An error occurred during 
                                                 memory management. 

 PMERR_METAFILE_IN_USE                           An attempt has been made to 
                                                 access a metafile that is in 
                                                 use by another thread. 

 PMERR_METAFILE_INTERNAL_ERROR                   An internal inconsistency has 
                                                 been detected during metafile 
                                                 unlock processing. 

 PMERR_METAFILE_LIMIT_EXCEEDED                   The maximum permitted metafile 
                                                 size limit was exceeded during 
                                                 metafile recording. 

 PMERR_MSG_QUEUE_ALREADY_EXISTS                  An attempt to create a message 
                                                 queue for a thread failed 
                                                 because a message queue 
                                                 already exists for the calling 
                                                 thread. 

 PMERR_MSGID_TOO_SMALL                           The message identifier 
                                                 specified is too small. 

 PMERR_NEGATIVE_STRCOND_DIM                      A negative array dimension was 
                                                 passed for a data type length. 

 PMERR_NO_BITMAP_SELECTED                        An attempt has been made to 
                                                 operate on a memory device 
                                                 context that has no bit map 
                                                 selected. 

 PMERR_NO_CURRENT_ELEMENT                        An attempt has been made to 
                                                 issue GpiQueryElementType or 
                                                 GpiQueryElement while there is 
                                                 no currently open element. 

 PMERR_NO_CURRENT_SEG                            An attempt has been made to 
                                                 issue GpiQueryElementType or 
                                                 GpiQueryElement while there is 
                                                 no currently open segment. 

 PMERR_NO_FILL                                   No flood fill occurred because 
                                                 either the starting point 
                                                 color was the same as the 
                                                 input color when a boundary 
                                                 fill was requested, or the 
                                                 starting point color was not 
                                                 the same as the input color 
                                                 when a surface fill was 
                                                 requested. 

 PMERR_NO_METAFILE_RECORD_HANDLE                 The metafile record handle was 
                                                 not found during metafile 
                                                 recording, or DevEscape 
                                                 (DEVESC_STARTDOC) was not 
                                                 issued when drawing to a 
                                                 OD_QUEUED device context with 
                                                 a pszDataType field of 
                                                 PM_Q_STD. 

 PMERR_NO_MSG_QUEUE 

 PMERR_NO_PALETTE_SELECTED                       An attempt to realize a 
                                                 palette failed because no 
                                                 palette was previously 
                                                 selected into the Presentation 
                                                 Space. 

 PMERR_NO_SPACE                                  The limit on the number of 
                                                 Window List entries has been 
                                                 reached with 
                                                 WinAddSwitchEntry. 

 PMERR_NOT_CREATED_BY_DEVOPENDC                  An attempt has been made to 
                                                 destroy a device context using 
                                                 DevCloseDC that was not 
                                                 created using DevOpenDC. 

 PMERR_NOT_CURRENT_PL_VERSION                    An unexpected data format was 
                                                 found in the initialization 
                                                 file. 

 PMERR_NOT_DRAGGING                              A drag operation is not in 
                                                 progress at this time. 

 PMERR_NOT_IN_A_PM_SESSION                       An attempt was made to access 
                                                 function that is only 
                                                 available from PM programs 
                                                 from a non-PM session. 

 PMERR_NOT_IN_AREA                               An attempt was made to end an 
                                                 area using GpiEndArea or 
                                                 during segment drawing while 
                                                 not in an area bracket. 

 PMERR_NOT_IN_DRAW_MODE                          An attempt was made to issue 
                                                 GpiSavePS or GpiRestorePS 
                                                 while the drawing mode was not 
                                                 set to DM_DRAW. 

 PMERR_NOT_IN_ELEMENT                            An attempt was made to end an 
                                                 element using GpiEndElement or 
                                                 during segment drawing while 
                                                 not in an element bracket. 

 PMERR_NOT_IN_IDX                                The application name, key-name 
                                                 or program handle was not 
                                                 found. 

 PMERR_NOT_IN_IMAGE                              An attempt was made to end an 
                                                 image during segment drawing 
                                                 while not in an image bracket. 

 PMERR_NOT_IN_PATH                               An attempt was made to end a 
                                                 path using GpiEndPath or 
                                                 during segment drawing while 
                                                 not in a path bracket. 

 PMERR_NOT_IN_RETAIN_MODE                        An attempt was made to issue a 
                                                 segment editing element 
                                                 function that is invalid when 
                                                 the actual drawing mode is not 
                                                 set to retain. 

 PMERR_NOT_IN_SEG                                An attempt was made to end a 
                                                 segment using GpiCloseSegment 
                                                 while not in a segment 
                                                 bracket. 

 PMERR_NOT_SELF_DESCRIBING_DTYP                  A data type is not 
                                                 self-describing. 

 PMERR_OK                                        The code page or country code 
                                                 passed is not valid. 

 PMERR_OK                                        The window handle or menu item 
                                                 passed is not valid. 

 PMERR_OPENING_INI_FILE                          Unable to open initialization 
                                                 file (due to lack of disk 
                                                 space for example). 

 PMERR_ORDER_TOO_BIG                             An internal size limit was 
                                                 exceeded while converting 
                                                 orders from short to long 
                                                 format during GpiPutData 
                                                 processing. An order was too 
                                                 long to convert. 

 PMERR_OWN_SET_ID_REFS                           An attempt to unload a font 
                                                 failed because the setid is 
                                                 still being referenced. 

 PMERR_PALETTE_BUSY                              An attempt has been made to 
                                                 reset the owner of a palette 
                                                 when it was busy. 

 PMERR_PALETTE_SELECTED                          Color palette operations 
                                                 cannot be performed on a 
                                                 presentation space while a 
                                                 palette is selected. 

 PMERR_PARAMETER_OUT_OF_RANGE                    The value of a parameter was 
                                                 not within the defined valid 
                                                 range for that parameter. 

 PMERR_PATH_INCOMPLETE                           An attempt was made to open or 
                                                 close a segment either 
                                                 directly or during segment 
                                                 drawing, or to issue 
                                                 GpiAssociate while there is an 
                                                 open path bracket. 

 PMERR_PATH_LIMIT_EXCEEDED                       An internal size limit was 
                                                 exceeded during path or area 
                                                 processing. 

 PMERR_PATH_UNKNOWN                              An attempt was made to perform 
                                                 a path function on a path that 
                                                 did not exist. 

 PMERR_PEL_IS_CLIPPED                            An attempt was made to query a 
                                                 pel that had been clipped 
                                                 using GpiQueryPel. 

 PMERR_PEL_NOT_AVAILABLE                         An attempt was made to query a 
                                                 pel that did not exist in 
                                                 GpiQueryPel (for example, a 
                                                 memory device context with no 
                                                 selected bit map). 

 PMERR_PRINTER_DD_NOT_DEFINED                    The Presentation Manager 
                                                 device driver has not been 
                                                 defined. 

 PMERR_PRINTER_QUEUE_NOT_DEFINED                 The spooler queue for the 
                                                 printer has not been defined. 

 PMERR_PRN_ADDR_IN_USE                           A printer is already defined 
                                                 on the port. 

 PMERR_PRN_ADDR_NOT_DEFINED                      The printer port has not been 
                                                 defined. 

 PMERR_PRN_NAME_NOT_DEFINED                      The printer has not been 
                                                 defined. 

 PMERR_PROLOG_ERROR                              A prolog error was detected 
                                                 during drawing.  Segment 
                                                 prologs are used internally 
                                                 within retained segments and 
                                                 also appear in metafiles. This 
                                                 error can also arise from an 
                                                 End Prolog order that is 
                                                 outside a prolog. 

 PMERR_PS_BUSY                                   An attempt was made to access 
                                                 the presentation space from 
                                                 more than one thread 
                                                 simultaneously. 

 PMERR_PS_IS_ASSOCIATED                          An attempt was made to destroy 
                                                 a presentation or associate a 
                                                 presentation space that is 
                                                 still associated with a device 
                                                 context. 

 PMERR_PS_NOT_ASSOCIATED                         An attempt was made to access 
                                                 a presentation space that is 
                                                 not associated with a device 
                                                 context. 

 PMERR_QUEUE_TOO_LARGE                           An attempt to create a message 
                                                 queue has failed because the 
                                                 value specified for the size 
                                                 of the message queue is too 
                                                 large. 

 PMERR_RASTER_FONT                               A request was made for the 
                                                 outline of a bit-map font. 
                                                 Outlines can only be returned 
                                                 for vector font characters. 

 PMERR_REALIZE_NOT_SUPPORTED                     An attempt was made to create 
                                                 a realizable logical color 
                                                 table on a device driver that 
                                                 does not support this 
                                                 function. 

 PMERR_REGION_IS_CLIP_REGION                     An attempt was made to perform 
                                                 a region operation on a region 
                                                 that is selected as a clip 
                                                 region. 

 PMERR_RESOURCE_DEPLETION                        An internal resource depletion 
                                                 error has occurred. 

 PMERR_RESOURCE_NOT_FOUND                        The specified resource 
                                                 identity could not be found. 

 PMERR_SEG_AND_REFSEG_ARE_SAME                   The segid and refsegid 
                                                 specified with 
                                                 GpiSetSegmentPriority were the 
                                                 same. 

 PMERR_SEG_CALL_STACK_EMPTY                      A call stack empty condition 
                                                 was detected when attempting a 
                                                 pop function during GpiPop or 
                                                 segment drawing. 

 PMERR_SEG_CALL_STACK_FULL                       A call stack full condition 
                                                 was detected when attempting 
                                                 to call a segment using 
                                                 GpiCallSegmentMatrix, 
                                                 attempting to preserve an 
                                                 attribute, or during segment 
                                                 drawing. 

 PMERR_SEG_IS_CURRENT                            An attempt was made to issue 
                                                 GpiGetData to a segment that 
                                                 was currently open. 

 PMERR_SEG_NOT_CHAINED                           An attempt was made to issue 
                                                 GpiDrawFrom, GpiCorrelateFrom 
                                                 or GpiQuerySegmentPriority for 
                                                 a segment that was not 
                                                 chained. 

 PMERR_SEG_NOT_FOUND                             The specified segment 
                                                 identifier did not exist. 

 PMERR_SEG_OVFLOW                                The input PIF has more than 
                                                 1000 called segments. This has 
                                                 overflowed an internal buffer. 

 PMERR_SEG_STORE_LIMIT_EXCEEDED                  The maximum permitted retained 
                                                 segment store size limit was 
                                                 exceeded. 

 PMERR_SETID_IN_USE                              An attempt was made to specify 
                                                 a setid that was already in 
                                                 use as the currently selected 
                                                 character, marker or pattern 
                                                 set. 

 PMERR_SETID_NOT_FOUND                           An attempt was made to delete 
                                                 a setid that did not exist. 

 PMERR_SMB_OVFLOW                                The input PIF has more than 
                                                 100 symbol sets defined. This 
                                                 has overflowed an internal 
                                                 buffer. 

 PMERR_SOMDD_IS_ACTIVE                           The DSOM daemon is already 
                                                 active. 

 PMERR_SOMDD_NOT_STARTED                         The DSOM daemon failed to 
                                                 start. 

 PMERR_SOURCE_SAME_AS_TARGET                     The direct manipulation source 
                                                 and target process are the 
                                                 same. 

 PMERR_SPL_CANNOT_OPEN_FILE                      Unable to open the file. 

 PMERR_SPL_DD_NOT_FOUND                          The Presentation Manager 
                                                 device driver definition could 
                                                 not be found. 

 PMERR_SPL_DEVICE_ALREADY_EXISTS                 The device already exists. 

 PMERR_SPL_DEVICE_LIMIT_REACHED                  The limit on the number of 
                                                 devices has been reached. 

 PMERR_SPL_DEVICE_NOT_INSTALLED                  The device has not been 
                                                 installed. 

 PMERR_SPL_DRIVER_ERROR                          No Presentation Manager device 
                                                 driver supplied or found. 

 PMERR_SPL_DRIVER_NOT_INSTALLED                  The Presentation Manager 
                                                 device driver has not been 
                                                 installed. 

 PMERR_SPL_FILE_NOT_FOUND                        Unable to find the file. 

 PMERR_SPL_HARD_NETWORK_ERROR                    Hard network error. 

 PMERR_SPL_INI_FILE_ERROR                        Error accessing the 
                                                 initialization file. 

 PMERR_SPL_INV_DATATYPE                          The spool file data type is 
                                                 invalid. 

 PMERR_SPL_INV_DRIVER_DATATYPE                   The data type is invalid for 
                                                 the Presentation Manager 
                                                 device driver. 

 PMERR_SPL_INV_FORMS_CODE                        The forms code for the job is 
                                                 invalid. 

 PMERR_SPL_INV_HSPL                              The spooler handle is invalid. 

 PMERR_SPL_INV_JOB_ID                            The job id is invalid. 

 PMERR_SPL_INV_LENGTH_OR_COUNT                   The length or count is 
                                                 invalid. 

 PMERR_SPL_INV_PRIORITY                          The priority for the job is 
                                                 invalid. 

 PMERR_SPL_INV_PROCESSOR_DATTYPE                 The data type is invalid for 
                                                 the spooler queue processor. 

 PMERR_SPL_INV_QUEUE_NAME                        The spooler queue name is 
                                                 invalid. 

 PMERR_SPL_INV_TOKEN                             The token is invalid. 

 PMERR_SPL_JOB_NOT_PRINTING                      The print job is not printing. 

 PMERR_SPL_JOB_PRINTING                          The print job is already 
                                                 printing. 

 PMERR_SPL_MANY_QUEUES_ASSOC                     More than one queue has been 
                                                 associated with the printer. 

 PMERR_SPL_NO_CURRENT_FORMS_CODE                 There is no current forms code 
                                                 defined to the Presentation 
                                                 Manager device driver. 

 PMERR_SPL_NO_DATA                               No data supplied or found. 

 PMERR_SPL_NO_DEFAULT_QUEUE                      There is no default spooler 
                                                 queue for the printer. 

 PMERR_SPL_NO_DISK_SPACE                         There is not enough free disk 
                                                 space. 

 PMERR_SPL_NO_FREE_JOB_ID                        There is no free job id 
                                                 available. 

 PMERR_SPL_NO_MEMORY                             There is not enough free 
                                                 memory. 

 PMERR_SPL_NO_QUEUES_ASSOCIATED                  A queue has not been 
                                                 associated with the printer. 

 PMERR_SPL_NO_SUCH_LOG_ADDRESS                   The logical address does not 
                                                 exist (that is, it is not 
                                                 defined in the initialization 
                                                 file). 

 PMERR_SPL_NOT_AUTHORISED                        Not authorized to perform the 
                                                 operation. 

 PMERR_SPL_PRINT_ABORT                           The job has already been 
                                                 aborted. 

 PMERR_SPL_PRINTER_NOT_FOUND                     The printer definition could 
                                                 not be found. 

 PMERR_SPL_PROCESSOR_ERROR                       No spooler queue processor 
                                                 supplied or found. 

 PMERR_SPL_PROCESSOR_NOT_INST                    The spooler queue processor 
                                                 has not been installed. 

 PMERR_SPL_QUEUE_ALREADY_EXISTS                  The spooler queue already 
                                                 exists. 

 PMERR_SPL_QUEUE_ERROR                           No spooler queue supplied or 
                                                 found. 

 PMERR_SPL_QUEUE_NOT_EMPTY                       The spooler queue contains 
                                                 print jobs. 

 PMERR_SPL_QUEUE_NOT_FOUND                       The spooler queue definition 
                                                 could not be found. 

 PMERR_SPL_SPOOLER_NOT_INSTALLED                 The spooler is not installed. 

 PMERR_SPL_STATUS_STRING_TRUNC                   The print job status string 
                                                 has been truncated. 

 PMERR_SPL_TEMP_NETWORK_ERROR                    Temporary network error. 

 PMERR_SPL_TOO_MANY_OPEN_FILES                   Too many open files. 

 PMERR_SPOOLER_QP_NOT_DEFINED                    The spooler queue processor 
                                                 has not been defined. 

 PMERR_START_POINT_CLIPPED                       The starting point specified 
                                                 for flood fill is outside the 
                                                 current clipping path or 
                                                 region. 

 PMERR_STARTDOC_NOT_ISSUED                       A request to write spooled 
                                                 output without first issuing a 
                                                 STARTDOC was attempted. 

 PMERR_STARTED_IN_BACKGROUND                     The application started a new 
                                                 session in the background. 

 PMERR_STOP_DRAW_OCCURRED                        Segment drawing or 
                                                 GpiPlayMetaFile was stopped 
                                                 prematurely in response to a 
                                                 GpiSetStopDraw request. 

 PMERR_TOO_MANY_METAFILES_IN_USE                 The maximum number of 
                                                 metafiles allowed for a given 
                                                 process was exceeded. 

 PMERR_TRUNCATED_ORDER                           An incomplete order was 
                                                 detected during segment 
                                                 processing. 

 PMERR_UNABLE_TO_CLOSE_DEVICE                    Unable to close the print 
                                                 device (for example, powered 
                                                 off or offline). 

 PMERR_UNCHAINED_SEG_ZERO_INV                    An attempt was made to open 
                                                 segment with segment 
                                                 identifier zero and the 
                                                 ATTR_CHAINED segment attribute 
                                                 not specified. 

 PMERR_UNSUPPORTED_ATTR                          An unsupported attribute was 
                                                 specified in the attrmask with 
                                                 GpiSetAttrs or GpiQueryAttrs. 

 PMERR_UNSUPPORTED_ATTR_VALUE                    An attribute value was 
                                                 specified with GpiSetAttrs 
                                                 that is not supported. 

 PMERR_WINDOW_LOCK_OVERFLOW                      An overflow occurred for the 
                                                 use count of a window. 

 PMERR_WINDOW_LOCK_UNDERFLOW                     An attempt was made to 
                                                 decrement the use count of a 
                                                 window below zero. 

 PMERR_WINDOW_NOT_LOCKED                         The window specified in 
                                                 WinSendMsg was not locked. 

 PMERR_WPDSERVER_IS_ACTIVE                       The Workplace Shell DSOM 
                                                 Server is already active. 

 PMERR_WPDSERVER_NOT_STARTED                     The Workplace Shell DSOM 
                                                 Server could not be started. 

 WPERR_INVALID_FLAGS                             An invalid flag was specified. 

 WPERR_INVALID_OBJECTID                          An invalid object ID was 
                                                 specified. 

 WPERR_INVALID_TARGET_OBJECT                     An invalid target object was 
                                                 specified. 


═══ 5. Area and Polygon Primitives ═══

An area is one or more closed figures that can be drawn filled, outlined, or 
filled and outlined. If an area includes more than one figure, those figures 
can be separate or intersecting. 

A polygon, too, is one or more closed figures that can be drawn filled, 
outlined, or filled and outlined. Polygons, unlike areas, are limited to 
figures with straight edges. Polygons also can be separate or intersecting. 

The following topics are related to information in this chapter: 

     Presentation spaces 
     Line and arc primitives 
     Color and mix attributes 
     Fonts 
     Bit maps 
     Paths 


═══ 5.1. About Area Primitives ═══

Applications can create, outline, and fill areas and can create custom-fill 
patterns from bit maps or font symbols. Some graphics functions are not valid 
within an area definition. For example, you cannot include marker, image, or 
character-string primitives in an area definition. The following figure is an 
example of an area. 

An Area 

This area comprises two hexagons, one completely enclosed by the other. The 
area is filled with the current area-fill pattern. 


═══ 5.1.1. Attributes of Area Primitives ═══

The attributes of the area primitive are contained in a data structure called 
AREABUNDLE. These attributes are: 

     Pattern symbol 
     Pattern reference point 
     Pattern set 
     Foreground color 
     Background color 
     Foreground mix attribute 
     Background mix mode 

 When an application creates a presentation space, the area attributes are set 
 to the default values shown in the following table. 

 Area Attribute Default Values 

  ┌──────────────────┬────────────┬──────────────────────────────┐
  │Attribute         │Default     │Function that Redefines       │
  │                  │Value       │Attribute                     │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Pattern symbol    │solid       │GpiSetPattern                 │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Pattern reference │(0,0)       │GpiSetPatternRefPoint         │
  │point             │            │                              │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Pattern set       │LCID_DEFAULT│GpiSetPatternSet              │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Foreground color  │Black       │GpiSetAttrs (ABB_COLOR)       │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Background color  │Clear       │GpiSetAttrs (ABB_BACK_COLOR)  │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Foreground mix    │Overpaint   │GpiSetAttrs (ABB_MIX_MODE)    │
  ├──────────────────┼────────────┼──────────────────────────────┤
  │Background mix    │Leave alone │GpiSetAttrs                   │
  │                  │            │(ABB_BACK_MIX_MODE)           │
  └──────────────────┴────────────┴──────────────────────────────┘

 Note:  If the default (LCID_DEFAULT) for pattern set is changed, the base 
 pattern set cannot be reselected with GpiSetPatternSet. 


═══ 5.1.2. Pattern Symbol Attribute ═══

The current pattern symbol, also called the symbol point code, is selected from 
the current pattern set with GpiSetPattern. The pattern symbol selected for the 
specified presentation space is used as the subsequent fill pattern until a new 
symbol is selected. Applications must not call GpiSetPattern while in an area 
or a path. If the current pattern set specifies a bit map, this attribute is 
ignored. 

The following table describes the pattern symbols provided by the PM 
programming interface in a base pattern set. These symbols are not necessarily 
available from other pattern sets. 

The Base Pattern Set 

┌──────────────────────────────────────────┬─────────────────┬──────────┐
│Symbol                                    │Identifier       │Long Value│
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Solid shading decreasing in dots per inch │PATSYM_DENSE1    │1L - 8L   │
│                                          │through          │          │
│                                          │PATSYM_DENSE8    │          │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Vertical lines                            │PATSYM_VERT      │9L        │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Horizontal lines                          │PATSYM_HORIZ     │10L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Lines bottom left to top right            │PATSYM_DIAG1     │11L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Lines bottom left to middle right         │PATSYM_DIAG2     │12L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Lines top left to bottom right            │PATSYM_DIAG3     │13L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Lines top left to middle right            │PATSYM_DIAG4     │14L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│No shading                                │PATSYM_NOSHADE   │15L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Solid shading                             │PATSYM_SOLID     │16L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Alternate pels                            │PATSYM_HALFTONE  │17L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Cartesian grid                            │PATSYM_HATCH     │18L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Diagonal crosshatch                       │PATSYM_DIAGHATCH │19L       │
├──────────────────────────────────────────┼─────────────────┼──────────┤
│Blank (often called the clear pattern)    │PATSYM_BLANK     │64L       │
└──────────────────────────────────────────┴─────────────────┴──────────┘

The default pattern symbol (PATSYM_DEFAULT) is identical to the PATSYM_SOLID 
symbol, and has a long value of 0L. The error pattern symbol (PATSYM_ERROR) has 
a long value of -1L. 

The following figure shows the patterns from the base pattern symbol set. 
Applications can determine the current pattern set by calling GpiQueryPattern. 

The Base Pattern Symbol Set 


═══ 5.1.3. Pattern Reference Point Attribute ═══

The pattern reference point is the point from which the area's fill-pattern 
spreads horizontally and vertically. The lower-left corner of the pattern is 
aligned on this point. The pattern reference point has a default value of 
(0,0), and is expressed in world coordinates. Applications can determine the 
pattern reference point with GpiQueryPatternRefPoint. Applications can specify 
the pattern reference point with GpiSetPatternRefPoint; however, this should 
not be done inside an area. The pattern reference point does not have to be 
within the boundary of the area. The following figure shows an area that was 
filled using the default pattern reference point. 

The Pattern Reference Point 

The pattern of diagonal lines is aligned with the pattern reference point 
(0,0).  When the picture is displayed or printed, only the hexagon will be 
filled. 

Use of the default reference point causes the diagonal lines of the pattern to 
intersect the area boundary at specific points. If you change the reference 
point to (0,4), for example, the pattern shifts upward, and the points of 
intersection with the area boundary are different. Although the reference point 
is outside the area, when an application displays or prints the picture, only 
the area is filled. 


═══ 5.1.4. Pattern Set Attribute ═══

When you create a presentation space, the current pattern set and other area 
attributes are set to the default. The current pattern-a black solid, as 
described earlier- is specified from the supplied pattern set. (The supplied 
set of pattern symbols contains image or raster patterns only.) An area 
primitive is filled by repeating this pattern vertically and horizontally 
within the area boundary. 


═══ 5.1.4.1. Default Pattern Set ═══

The standard pattern set contains patterns of solid shading with decreasing 
intensity, and patterns of vertical, horizontal, and diagonal lines. If the 
default pattern set is changed with GpiSetDefAttrs, its patterns are not 
accessible. The patterns from the default set can be recovered by specifying 
GpiSetDefAttrs with the value LCID_DEFAULT, (0). 


═══ 5.1.4.2. Customizing Pattern Sets ═══

An application can create custom patterns by using bit maps or characters and 
symbols from an image font. When designing custom patterns, consider that the 
operating system uses only the first eight bits in the first eight rows, 
starting with the lower-left corner of the bit map. The cell size of an image 
font used as a fill pattern might be too large to include the complete 
character or symbol. 

An application can change the appearance of a fill pattern by changing its 
alignment in an area primitive with GpiSetPatternRefPoint. When the default 
reference point is set, the operating system aligns the lower-left corner of 
the fill pattern with the point (0,0) in the application's world space and 
begins filling the area. If an application adjusts the pattern reference point 
to (3,2), The operating system aligns the lower-left corner of the fill pattern 
with the point (3,2) in the application's world space and begins filling the 
area. By moving the reference point from (0,0) to (3,2), the fill pattern 
appears shifted up two pels and to the right three pels. 


═══ 5.1.4.2.1. Custom Fill Patterns from a Bit Map ═══

To create a custom pattern from a hard-coded bit map, an application must use 
the following steps: 

   1. Create or load a bit map to obtain a bit-map handle; for example, use 
      GpiLoadBitmap. 

   2. Call GpiSetBitmapId (ID) to tag the bit map with a local identifier 
      (lcid) from 1 to 254. 

   3. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET) to set the current 
      fill pattern. 

 The application can now draw the area. 


═══ 5.1.4.2.2. Custom Fill Patterns from a Font Symbol ═══

To create a custom pattern from a character or a symbol in a font: 

   1. Create a logical image font and assign it an ID; for example use 
      GpiCreateLogFont. 

   2. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET), passing it the local 
      identifier for the font. 

   3. Call GpiSetPattern, passing the value of the code point for a character 
      or symbol in the font. 

 The application can now draw the area. 


═══ 5.1.5. Area Colors and Mix Attributes ═══

The color attribute defines the color used to draw a primitive or an object. 
The mix attribute determines how the color of a primitive or an object is 
combined with the color of the drawing surface, or any other objects on the 
surface. Both attributes also are described in Color and Mix Attributes. 

The area color defines the color used to fill the output from any of the IBM 
OS/2 area functions, when necessary. The area primitive is the only primitive 
in which the color can be changed during the drawing of the area. Therefore, 
this attribute, more than the other area attributes, depends on the current 
value as described in Attribute Currentness. 

When a presentation space is created, the area color initial default is black. 
The pattern symbol initial default, explained previously, is solid. Areas are 
one of the primitives that have a foreground and background color, as shown in 
the following figure. The appearance of the area also depends on the pattern 
symbol. 

Area Primitives 

Area primitives have both a color and background color attribute. The 
background color does not appear if the pattern symbol is solid, and the 
background color is undefined if the pattern symbol is a customized, 
multi-colored bit map. 

When a presentation space is created, the area mix attribute initial default is 
FM_OVERPAINT. The overpaint mix attribute specifies that the area color is not 
to be modified by the color of the drawing surface. If the area mix attribute 
is changed, the area color is mixed with colors that are already on the drawing 
surface. 

When the pattern symbol is solid, the color that fills the area, if necessary, 
is the current area foreground color. If the pattern symbol is changed to be a 
pattern of vertical lines, for example, the color of those lines is the current 
area foreground color. Inside of the area bracket, there can be other colors if 
these colors are the current color for primitives such as lines or arcs, that 
are drawn within the area bracket. These colors are not specifically defined or 
influenced by the area foreground color. 

The area background color initial default is CLR_BACKGROUND. Usually this is 
defined by the application to the same color as the drawing surface. If the 
pattern symbol is solid, the area background color does not appear. If the 
pattern symbol is changed to be a pattern of vertical lines, for example, the 
color in between those lines is the current area background color. 

The area background mix attribute initial default is BM_LEAVEALONE. The 
leave-alone background mix attribute specifies that the area background color 
is not drawn. This means that for a nonsolid pattern symbol, the 
drawing-surface color or the color of an object, not created by the area 
bracket, but on the drawing surface, shows through the nonsolid pattern. The 
area background color, for nonsolid pattern symbols, appears only if the 
background mix attribute is changed to overpaint, BM_OVERPAINT. 

If you have customized the pattern symbol with a bit map, the color definitions 
of the area primitive change. The foreground color corresponds to the color of 
the pels that are specified ON in the fill-pattern bit map. The background 
color corresponds to the color of the pels that are specified OFF in the 
fill-pattern bit map. The foreground and background mix attribute do not 
change. 

Note:  Background color and mix attribute only apply to monochrome (2-color) 
fill patterns. The bit set to 0 is defined as the background and the bit set to 
1 is defined as the foreground. 

A multi-colored bit map is unaffected by the background color and mix 
attributes. 

To specify a new color or mix attribute call GpiSetAttrs. This function accepts 
as input the type of primitive, for example PRIM_AREA, a list of attributes 
that are to be changed, a list of attributes that are to be set to their 
default values, and the values for the attributes that are to be changed. 
GpiSetAttrs is useful to specify colors and mix attributes just for a specific 
data structure -for example the AREABUNDLE structure. GpiSetAttrs also provides 
some protection against invalid colors. 

To determine the current area color and mix attribute, call GpiQueryAttrs. This 
function accepts as input the primitive type and the attributes in question. It 
returns as output an array of values for the specifically queried attributes. 

To reset the default area color and mix attribute, just as with any other 
attribute specified in the AREABUNDLE. data structure, call GpiSetDefAttrs. 
This function accepts as input the type of primitive, for example PRIM_AREA, 
the attributes to be changed, and the values that will become the new default 
values. The changing of default values is important when working with segments. 
Changing the default values during a series of drawing functions is not 
recommended. 

The area color and mix attribute also can be specified with: 

     GpiSetColor 
     GpiSetMix 
     GpiSetBackColor 
     GpiSetBackMix 

 However, these functions have the disadvantage of specifying the foreground 
 and background color or mix attribute for all primitive BUNDLE data structures 
 that have the respective component. 

 There are four queries that determine the color and mix attribute as specified 
 by GpiSet... functions: 

     GpiQueryColor 
     GpiQueryMix 
     GpiQueryBackColor 
     GpiQueryBackMix 

 If the area color, area background color, mix attribute, or background mix 
 attribute were specified individually, the aforementioned queries can return a 
 value inconsistent with the current area attribute. 


═══ 5.1.6. Area Brackets ═══

Areas also are referred to as area brackets, because the functions that create 
and define the area always are "bracketed" by the two functions, GpiBeginArea 
and GpiEndArea. Only one area is defined between these two functions. However, 
within the area, there can be any number of adjacent, intersecting, or 
completely separate area primitives. 

GpiBeginArea signals the start of a group of primitives that define the 
boundary of the area. The current position is not changed by GpiBeginArea, 
although it is updated by any drawing instructions that follow. 

If you call GpiSetCurrentPosition or GpiMove within an area definition, the 
current figure is closed automatically, and a new figure is started at the 
current position by the next line or curve. A figure in the area, whose start 
and end points are not the same, is closed by drawing a straight line from the 
current position to the start position of the figure. 

GpiEndArea signals the end of an area definition and tells the operating system 
to draw the area. If an application does not close a figure before calling 
GpiEndArea, the figure is closed automatically by drawing a straight line from 
the end point of the last line or curve to the start point of the current 
figure. The current position is always updated to the end point of the last 
line drawn. 

The functional sequence to draw the area in the following figure could be: 


#include <os2.h>
void fncAREA01(void){

#if 0

GpiBeginArea                /* Starts the area bracket          */

GpiSetCurrentPosition       /* Set the start point of the       */
                            /* outer hexagon.                   */
GpiPolyLine                 /* Draw the outer hexagon.          */
GpiSetCurrentPosition       /* Set the start point of the inner */
                            /*  hexagon.                        */
GpiPolyLine                 /* Draw the inner hexagon.          */

GpiEndArea                  /* End the area definition.         */

#endif

}

An area bracket contains the functions that define an area. Only one area can 
be defined between "bracket" functions. 

Following the beginning of an area bracket, an application can define the shape 
and location of the area in world space by using the following line and arc 
functions: 

     GpiBox 
     GpiFullArc 
     GpiLine 
     GpiPartialArc 
     GpiPointArc 
     GpiPolyFillet 
     GpiPolyFilletSharp 
     GpiPolyLine 
     GpiPolySpline 

 If an application calls either GpiBox or GpiFullArc inside an area, it must 
 use the DRO_OUTLINE option. 

 In addition to the drawing functions, an application also can use the 
 following specification functions inside an area bracket: 

     GpiBeginElement 
     GpiCallSegmentMatrix 
     GpiComment 
     GpiElement 
     GpiEndArea 
     GpiEndElement 
     GpiGetData 
     GpiLabel 
     GpiMove 
     GpiOffsetElementPointer 
     GpiPop 
     GpiPutData 
     GpiSetArcParams 
     GpiSetAttrMode 
     GpiSetAttrs 
     GpiSetColor 
     GpiSetCurrentPosition 
     GpiSetEditMode 
     GpiSetElementPointer 
     GpiSetElementPointerAtLabel 
     GpiSetLineEnd 
     GpiSetLineJoin 
     GpiSetLineType 
     GpiSetLineWidth 
     GpiSetMix 
     GpiSetModelTransformMatrix 
     GpiSetSegmentTransformMatrix 

 An application also can use the following query functions inside an area 
 bracket: 

     GpiQueryArcParams 
     GpiQueryAttrMode 
     GpiQueryAttrs 
     GpiQueryBackColor 
     GpiQueryBackMix 
     GpiQueryBoundaryData 
     GpiQueryCharAngle 
     GpiQueryCharBox 
     GpiQueryCharDirection 
     GpiQueryCharMode 
     GpiQueryCharSet 
     GpiQueryCharShear 
     GpiQueryCharStringPos 
     GpiQueryCharStringPosAt 
     GpiQueryClipBox 
     GpiQueryClipRegion 
     GpiQueryColor 
     GpiQueryColorData 
     GpiQueryColorIndex 
     GpiQueryCp 
     GpiQueryCurrentPosition 
     GpiQueryDefaultViewMatrix 
     GpiQueryDefCharBox 
     GpiQueryDevice 
     GpiQueryDeviceBitmapFormats 
     GpiQueryEditMode 
     GpiQueryFontFileDescriptions 
     GpiQueryFontMetrics 
     GpiQueryFonts 
     GpiQueryGraphicsField 
     GpiQueryInitialSegmentAttrs 
     GpiQueryKerningPairs 
     GpiQueryLineEnd 
     GpiQueryLineJoin 
     GpiQueryLineType 
     GpiQueryLineWidth 
     GpiQueryLineWidthGeom 
     GpiQueryLogColorTable 
     GpiQueryMarker 
     GpiQueryMarkerBox 
     GpiQueryMarkerSet 
     GpiQueryMix 
     GpiQueryModelTransformMatrix 
     GpiQueryNearestColor 
     GpiQueryNumberSetIds 
     GpiQueryPageViewport 
     GpiQueryPattern 
     GpiQueryPatternRefPoint 
     GpiQueryPatternSet 
     GpiQueryPel 
     GpiQueryPickAperturePosition 
     GpiQueryPickApertureSize 
     GpiQueryRealColors 
     GpiQueryRegionBox 
     GpiQueryRegionRects 
     GpiQueryRGBColor 
     GpiQuerySegmentAttrs 
     GpiQuerySegmentNames 
     GpiQuerySegmentPriority 
     GpiQuerySegmentTransformMatrix 
     GpiQuerySetIds 
     GpiQueryStopDraw 
     GpiQueryTag 
     GpiQueryViewingLimits 
     GpiQueryViewingTransformMatrix 
     GpiQueryWidthTable 


═══ 5.1.7. Area Bracket Attributes ═══

In addition to the attributes controlled by the AREABUNDLE data structure, 
there are two attributes that can be specified for each individual area 
bracket: 

     Area boundary 
     Area construction 

 These bracket attributes affect how the area primitives inside the bracket are 
 drawn. 

 The concept of attribute currentness is especially important to areas and 
 paths that contain multiple figures. 


═══ 5.1.8. Area Boundaries ═══

An application specifies the area boundary when it calls GpiBeginArea. There 
are two options: 

     BA_BOUNDARY (the default) 
     BA_NOBOUNDARY. 

 The BA_BOUNDARY value tells the programming interface to draw all outlines of 
 the area primitives within the area bracket, using a line that conforms to the 
 current LINEBUNDLE attributes. If the line attributes have not been changed, 
 the default outline color is black on most displays and printers, and the 
 default line style is solid. An application can change the line color and line 
 styles within the area bracket. The interior of the area primitive is filled 
 with the current pattern. 

 To prevent the interface from outlining an area, an application can use the 
 BA_NOBOUNDARY flag when calling GpiBeginArea. Only the interior fill pattern 
 is visible. This value most often is used when an area contains many 
 overlapping figures, and the interior lines are not desired. 

 You could think of this option in terms similar to the outline and fill 
 options discussed with boxes and full arcs. The BA_BOUNDARY value corresponds 
 to DRO_OUTLINEFILL, and BA_NOBOUNDARY, to DRO_FILL. There is no distinct 
 boundary value that corresponds to DRO_OUTLINE, the simple outline. To 
 simulate this effect, OR the BA_NOBOUNDARY value with the appropriate area 
 construction value when calling GpiBeginArea. 


═══ 5.1.9. Area Construction ═══

An application specifies the area construction when it calls GpiBeginArea. 
There are two options: 

     BA_ALTERNATE  (the default) 
     BA_WINDING. 

 Construction modes also are called area-fill modes. They provide different 
 ways of determining whether a given point is included in the filled area. 
 Normally, the construction mode you use is a matter of personal preference. 


═══ 5.1.9.1. Alternate Mode ═══

In alternate mode, the following occurs: 

     A point is included in the filled area if you have to cross an odd number 
      of lines in the area when drawing a line from that point to infinity. 

     A point is not included in the filled area if you have to cross an even 
      number of lines in the area when drawing a line from that point to 
      infinity. 
 In the example in the following figure, the inner hexagon is not shaded, 
 because to draw a line from any point in the hexagon to infinity, you must 
 cross two boundary lines. The remainder of the area is shaded, because to move 
 outside the area, you need to cross only one boundary line. 

 Calculating Filled Areas Constructed in Alternate Mode 


═══ 5.1.9.2. Winding Mode ═══

In winding mode, the direction in which the boundary lines in the area are 
drawn determines whether a given point is included in the filled area. The 
direction of a line depends on both the graphics functions used to draw it and 
the world coordinates that define it. For example, if the current position of a 
presentation space is (c,c), and GpiBox is called with the diagonally-opposite 
corner of the box specified as (d,d), GpiBox always draws the box in the 
following order: 

   1. (xc.,yc.) to 
   2. (xd.,yc.) to 
   3. (xd.,yd.) to 
   4. (xc.,yd.) and returning to 
   5. (xc.,yc.). 

 As illustrated in the following figure, in some cases the box is drawn in a 
 counterclockwise direction. When either xd. is less than xc., or yd. is less 
 than yc., but not both, a box is drawn clockwise. 

 The Box 

 The current position is (3,2) and the specified corner is at (8,6).  The box 
 is drawn from (3,2) to (8,2) to (8,6) to (3,8) to (3,2). 

 For the polyline primitive, the direction in which a line is drawn depends on 
 the relative values of the end points of each line, so you can choose whether 
 to draw in a clockwise or counterclockwise direction. 

 To determine if a given point is included in the filled area, count the number 
 of lines to be crossed to move from that point to infinity. For each boundary 
 line drawn in one direction, add one to the tally. For each line drawn in the 
 opposite direction, subtract one from the tally. A point is within the area if 
 the result is nonzero. 

 If two figures -for example, the hexagons in the following figure- are drawn 
 in different directions, the tally for the inner hexagon is 0 and the area 
 will look exactly as it does in alternate mode. 

 Area Constructed in Different Directions in Winding Mode 

 If the two hexagons are drawn in the same direction, the result is 2, and the 
 inner hexagon is shaded as shown in the following figure. 

 Area Constructed in the Same Direction in Winding Mode 

 The boundary lines of the area in the previous figure have been drawn and are 
 visible through the area-fill pattern. The boundary lines of an area primitive 
 do not have to be drawn; but if they are, they are drawn according to the 
 current line attributes. 

 To vary the appearance of different parts of the boundary line, you can change 
 the current line attributes during area definition. 

 The boundary lines of an area are considered a part of the area's interior. 
 Therefore, when you draw an area without boundary lines (BA_NOBOUNDARY), the 
 area-fill pattern extends to include the boundaries of the area, and the area 
 is the same size it would be if the boundary lines had been drawn. 


═══ 5.1.10. Attribute Currentness ═══

Graphics functions that change attributes are valid within the area bracket. 
There are misconceptions, however, about which attributes are used when the 
figures are displayed in a window or drawn to the printer. 

Review the following functional sequence: 

 Function       Effect 

 GpiSetColor    Sets color to red. 

 GpiBeginArea   Opens area bracket 

 GpiLine        Draws a straight line 

 GpiSetColor    Sets color to green. 

 GpiPolyLine    Draws two additional lines to form a triangle. 

 GpiEndArea     Ends the area bracket and displays a picture. 

 If you are displaying on a color monitor, the image appears as follows: 

 The triangle has one red line, drawn with GpiLine and two green lines, drawn 
 with GpiPolyLine. The interior of the triangle, if drawn, is red. Red is the 
 color that was current when the area was defined and, therefore, is the 
 current color for the area interior. In terms of the interior area, green is 
 only the color that was current when the function that initiates drawing was 
 called. 

 If the application immediately opened a new area bracket, the interior of that 
 bracket, if drawn, would be green. The color attribute for the second 
 AREABUNDLE, is not "inherited" from the last AREABUNDLE drawn. 


═══ 5.2. About Polygon Primitives ═══

Area brackets have the flexibility to draw any combination of curved or 
straight lines and combine the results into a closed figure. An advantage that 
polygons sometimes have over area brackets, however, is that they require fewer 
time-consuming calculations to provide that kind of flexibility. 

The operating system provides a function that enables you to draw multiple 
straight-line closed areas outside of an area bracket. Like bracket-generated 
areas, they can be adjacent, intersecting, or completely separate. 

The function is GpiPolygons and the set of objects it draws are called polygon 
primitives. A polygon primitive is any set of polygons with specified vertices 
that can be filled or filled and outlined. This function accepts as input the 
desired number of polygons, the POLYGON data structure for each polygon, and a 
boundary and construction option similar to those of the GpiBeginArea function. 

The purpose of GpiPolygons is to enable you to specify an area in such a way as 
to pass all of the area boundaries at once. This improves performance 
significantly because the operating system cannot process the accumulated 
primitives inside an area bracket until it reaches a GpiEndArea. GpiPolygons is 
not valid inside an area bracket because the figures it defines are areas 
already. 

Although GpiPolygons is limited to straight line figures, it retains a great 
deal of flexibility. The polygon data structure (POLYGON) contains the number 
of vertices, and the vertices themselves are in world coordinates. The 
collection of POLYGON structures accepted in a single GpiPolygons is not 
limited to one type of polygon. 

The drawing of the first polygon begins at the current position. For all 
subsequent polygons, all vertices must be explicitly defined. If the individual 
polygons are not completely defined, they are closed with a straight line drawn 
from the last defined vertex to the first. 

After the application has defined the polygons, they may be transformed and 
manipulated just as other primitives are. 


═══ 5.2.1. Polygon Boundaries ═══

Applications have two options when specifying the polygon boundary: 

     POLYGON_BOUNDARY (the default) 
     POLYGON_NOBOUNDARY. 

 The POLYGON_BOUNDARY value tells the PM programming interface to draw all 
 outlines of the polygon primitives using a line that conforms to the current 
 LINEBUNDLE attributes. If the line attributes have not been changed, the 
 default outline color is black on most display devices and printers, and the 
 default line style is solid. As the attributes cannot be changed within the 
 context of GpiPolygons, all polygons are drawn with the same line. The 
 interior of the polygons are filled with the pattern that conforms to the 
 current AREABUNDLE attributes. 

 To prevent PM from outlining an area, an application can use the 
 POLYGON_NOBOUNDARY flag when calling GpiPolygons. Only the interior fill 
 pattern is visible. This value is used most often when there are many 
 overlapping polygons, and the interior lines are not desired. 

 You might think of this option in terms similar to the outline and fill 
 options discussed with boxes and full arcs. The POLYGON_BOUNDARY value 
 corresponds to the DRO_OUTLINEFILL value, and POLYGON_NOBOUNDARY, to the 
 DRO_FILL. There is no distinct boundary value that corresponds to DRO_OUTLINE, 
 the simple outline. 

 To simulate this effect, OR the POLYGON_NOBOUNDARY value with the appropriate 
 polygon construction value, described below, when calling GpiPolygons. 


═══ 5.2.2. Polygon Construction ═══

An application specifies the area construction when it calls GpiBeginArea. 
There are two options: 

     POLYGON_ALTERNATE (the default) 
     POLYGON_WINDING. 

 As with area construction, in alternate mode: 

     A point is included in the filled polygon if you have to cross an odd 
      number of lines in the set of polygons when drawing a line from that 
      point to infinity. 

     A point is not included in the filled polygon if you have to cross an 
      even number of lines in the set of polygons when drawing a line from that 
      point to infinity. 

 Also as with area construction, in winding mode, the direction in which the 
 boundary lines of the polygons are drawn determines whether a given point is 
 included in the filled polygon. Since the individual polygons drawn with 
 GpiPolygons are generated by independent structures, the direction in which a 
 polygon is drawn depends only on the vertices of that polygon. 

 To determine if a given point is included in the filled polygon, count the 
 number of lines to be crossed to move from that point to infinity. For each 
 boundary line drawn in one direction add one to the tally. For each line drawn 
 in the opposite direction, subtract one from the tally. A point is within the 
 polygon if the result is nonzero. 


═══ 5.2.3. Polygon Overlap ═══

An application specifies which pels are drawn when it calls GpiPolygons. There 
are two options: 

     POLYGON_INCL (the default) 
     POLYGON_EXCL. 

 When the overlap value is POLYGON_INCL, the bottom right is included in the 
 polygon. The value POLYGON_EXCL, the exclusive value, indicates that the 
 bottom right is excluded from the polygon. This value acts in conjunction with 
 the mix attribute in determining the appearance of a polygon, which is 
 especially important for a group of overlapping or adjacent polygons. 

 For example, GpiPolygons specifies a number of polygons. Two of the polygons 
 share the vertex pair (6,7) and (9,7). When the polygons are drawn, if the 
 overlap value was POLYGON_INCL, there are two distinct lines to be drawn from 
 (6,7) to (9,7). A mix attribute other than FM_OVERPAINT could cause 
 undesirable results as the line and drawing-surface colors mix. 

 As with the polygon boundary and construction values, the overlap value can be 
 ORed when calling GpiPolygons to create a specific effect. 


═══ 5.3. Using Area and Polygon Primitives ═══

You can use area functions to: 

     Draw one or more closed figures 
     Create a custom fill pattern from a bit map 
     Create a custom fill pattern from a font character 


═══ 5.3.1. Drawing a Single, Closed Figure ═══

The following figure shows an example of how to use area functions to draw a 
single closed figure that is filled with a vertical pattern using the alternate 
mode. The closed figure in this example is a 5-pointed star. 

#define INCL_GPI
#include <os2.h>
void fncAREA02(void){
   POINTL aptl[5];               /* Structure for current position */
   HPS hps;

    /* Initialize the array of points for the 5-pointed star.       */
    aptl[0].x = 400; aptl[0].y = 195;
    aptl[1].x = 40;  aptl[1].y = 320;
    aptl[2].x = 260; aptl[2].y = 10;
    aptl[3].x = 260; aptl[3].y = 390;
    aptl[4].x = 37;  aptl[4].y = 82;

    GpiSetPattern(hps, PATSYM_VERT);/* Set pattern outside bracket */

    /* Draw the star. */
    GpiBeginArea(hps, BA_ALTERNATE);
    GpiMove(hps, &aptl[4]);         /* First and last point of star */
    GpiPolyLine(hps, 5L, aptl);
    GpiEndArea(hps);
} /* fncAREA02 */


═══ 5.3.2. Drawing Multiple, Intersecting, Closed Figures ═══

The following figure is an example of how to use area functions to draw two 
intersecting boxes, filled, using the winding mode. 

#define INCL_GPI
#include <os2.h>
void fncAREA03(void){
    POINTL ptl;            /* Structure for current position */
    HPS    hps;

    GpiBeginArea(hps, BA_WINDING);
    ptl.x = 100;
    ptl.y = 50;
    GpiMove(hps, &ptl);
    ptl.x = 300;
    ptl.y = 250;
    GpiBox(hps, DRO_OUTLINE, &ptl, 0, 0);
    ptl.x = 180;
    ptl.y = 120;
    GpiMove(hps, &ptl);
    ptl.x = 380;
    ptl.y = 320;
    GpiBox(hps, DRO_OUTLINE, &ptl, 0, 0);
    GpiEndArea(hps);
} /* fncAREA03 */


═══ 5.3.3. Creating a Custom Fill Pattern from a Bit Map ═══

The following figure is an example of how to create a custom fill pattern by 
using a hard-coded bit map. In this example, the bit map creates a pattern of 
arrows. 

#define INCL_DOS
#define INCL_GPI
#define INCL_WIN
#include <os2.h>
   LONG lcidCustom;                  /* Bit map tag                           */
   HPS  hps;

   VOID CreatePattern(VOID);

   VOID MyFunction(VOID){
       CreatePattern();
       GpiSetPatternSet(hps, lcidCustom);
        .
        .
        .
   } /* func */

   VOID CreatePattern(VOID){
        HBITMAP hbm;               /* Bit map handle                          */
        BITMAPINFOHEADER2 bmp2;    /* Structure for bit map information       */
        PBITMAPINFO2 pbmi2;        /* Pointer to structure for bit map data   */
        PRGB2 prgb2;               /* Structure for color data                */
        ULONG cbBitmapInfo, cColors;

        BYTE abPattern[] = { 0xFF, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xC3, 0xFF,
                             0xC3, 0xFF, 0x81, 0xFF,
                             0x81, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xE7, 0xFF,
                             0xE7, 0xFF, 0xFF, 0xFF
   };


        lcidCustom = 1;            /* Bit map tag                             */

        bmp2.cbFix = (ULONG) sizeof(BITMAPINFOHEADER2);
        bmp2.cx = 8;               /* Bit map is 8 pels wide                  */
        bmp2.cy = 8;               /* Bit map is 8 pels high                  */
        bmp2.cPlanes = 1;          /* One bit plane                           */
        bmp2.cBitCount = 1;        /* One bit per pel                         */

        /* Use default values for the remainder of the structure.             */

        bmp2.ulCompression = 0;
        bmp2.cbImage = 0;
        bmp2.cxResolution = 0;
        bmp2.cyResolution = 0;
        bmp2.cclrUsed = 0;
        bmp2.cclrImportant = 0;
        bmp2.usUnits = 0;
        bmp2.usReserved = 0;
        bmp2.usRecording = 0;
        bmp2.usRendering = 0;
        bmp2.cSize1 = 0;
        bmp2.cSize2 = 0;
        bmp2.ulColorEncoding = 0;
        bmp2.ulIdentifier = 0;

        cColors = 1 << (bmp2.cBitCount * bmp2.cPlanes);

        cbBitmapInfo = sizeof(BITMAPINFO2) + (sizeof(RGB2) * cColors);

        DosAllocMem((PVOID)&pbmi2, cbBitmapInfo,
                    PAG_COMMIT | PAG_READ | PAG_WRITE);

        pbmi2->cbFix = bmp2.cbFix;
        pbmi2->cx = bmp2.cx;
        pbmi2->cy = bmp2.cy;
        pbmi2->cPlanes = bmp2.cPlanes;
        pbmi2->cBitCount = bmp2.cBitCount;

        /* Use default values for the remainder of the structure.             */

        pbmi2->ulCompression = 0;
        pbmi2->cbImage = 0;
        pbmi2->cxResolution = 0;
        pbmi2->cyResolution = 0;
        pbmi2->cclrUsed = 0;
        pbmi2->cclrImportant = 0;
        pbmi2->usUnits = 0;
        pbmi2->usReserved = 0;
        pbmi2->usRecording = 0;
        pbmi2->usRendering = 0;
        pbmi2->cSize1 = 0;
        pbmi2->cSize2 = 0;
        pbmi2->ulColorEncoding = 0;
        pbmi2->ulIdentifier = 0;

        prgb2 = (PRGB2) (pbmi2 + 1);  /* Set address to follow bmp2           */

        /* Set bit map colors to black and white.                             */
        prgb2[0].bBlue = 0;                               /* Color[0] = black */
        prgb2[0].bGreen = 0;                              /* Color[0] = black */
        prgb2[0].bRed = 0;                                /* Color[0] = black */
        prgb2[0].fcOptions = 0;
        prgb2[1].bBlue = 255;                             /* Color[1] = white */
        prgb2[1].bGreen = 255;                            /* Color[1] = white */
        prgb2[1].bRed = 255;                              /* Color[1] = white */
        prgb2[1].fcOptions = 0;

        /* Create a bit map and retrieve its handle.                          */
        hbm = GpiCreateBitmap(hps,
            &bmp2,
            CBM_INIT,
            (PBYTE) abPattern,                            /* Array of bits    */
            pbmi2);

        /* Tag the bit map just created with a custom identifier (lcid).      */
        GpiSetBitmapId(hps, hbm, lcidCustom);
   } /* CreatePattern */

Creating a Custom Fill Pattern from a Bit Map 


═══ 5.3.4. Creating a Custom Fill Pattern from a Font Character ═══

The following figure is an example of how to create a custom fill pattern by 
using a character from a font. The fill pattern can be only an 8-by-8 bit map; 
as a result, not all of the character is used. 

#define INCL_GPI
#define INCL_WIN
#include <os2.h>
   HPS hps;                      /* Presentation-space handle */
   LONG lcidCustom;              /* Font identifier           */
   FONTMETRICS afm[80];
   FATTRS fat;

   VOID LoadFont(VOID);

   void fncAREA05(void){

        LoadFont();
GpiSetPatternSet(hps, lcidCustom);
GpiSetPattern(hps, 'o');         /* Use lowercase 'o' as fill */
    .
    .
    .
   } /* fncAREA05 */

   VOID LoadFont(VOID){
      LONG cFonts = 0;
      LONG cPublicFonts, i;

      lcidCustom = 1;

/* Determine the number of loaded public fonts.               */
cPublicFonts = GpiQueryFonts(hps, QF_PUBLIC, NULL, (PLONG) &cFonts,
    (LONG) (sizeof(FONTMETRICS)), NULL);

/* Load the metrics for all public fonts into afm.            */
GpiQueryFonts(hps, QF_PUBLIC, NULL, (PLONG) &cPublicFonts,
    (LONG) (sizeof(FONTMETRICS)), afm);

/* Get the first image font with a point size larger than 8.  */
for (i = 0; ((afm[i].fsDefn & FM_DEFN_OUTLINE) ||
     afm[i].lEmHeight <= 8) && i < cPublicFonts; i++);

/* Load the FATTRS structure with the required metrics.       */
fat.usRecordLength = sizeof(fat);
fat.fsSelection = 0;
fat.lMatch = afm[i].lMatch;
StringCopy(fat.szFacename, afm[i].szFacename);
fat.idRegistry = 0;
fat.usCodePage = 0;
fat.lMaxBaselineExt = 0;
fat.lAveCharWidth = 0;
fat.fsType = 0;
fat.fsFontUse = 0;

/* Select this font and assign it a custom lcid.              */
GpiCreateLogFont(hps, NULL, lcidCustom, &fat);
GpiSetCharSet(hps, lcidCustom);
} /* LoadFont */


Creating a Custom Fill Pattern from a Font Character 


═══ 6. Bit Maps ═══

Raster output devices, such as display screens, are made up of a number of 
picture elements, called pixels or pels. By setting the color of the pels, you 
can create an image on the screen. The screen image can be represented 
internally by a graphics object called a bit map. The bit map contains a number 
of bits that describe the appearance of each pel on the screen. 

This chapter describes bit maps, their creation, uses, and functions. The 
following topics are related to information in this chapter: 

     Presentation spaces and device contexts 
     Coordinate spaces 
     Color and mix modes 
     Area primitives 
     Paths 


═══ 6.1. About Bit Maps ═══

Applications can use bit maps to: 

     Store and display scanned images, icons, and symbols 
     Create fill patterns for area primitives and paths 

 An application can display a bit-map image on any raster output device. A 
 raster is a rectangular matrix of pels on a video display or dot matrix 
 printer. A raster output device displays an image by setting pels in its 
 matrix to colors specified in a corresponding bit map. An image created in 
 this way is called a "bit-map image". Bit maps cannot be sent to vector output 
 devices such as plotters. 

 A bit map is drawn to an output device row by row. Each horizontal line of 
 pels is known as a scan line. 

 There is a 1-to-1 correspondence between the number of rows of pels in a 
 bit-map image and the rows of bits in a bit map. The first pel in a bit-map 
 image is in the lower-left corner, and the last pel is in the upper-right 
 corner. The pels are in left-to-right order inside each row of the image. The 
 following figure shows this relationship between bit map and image. 

 Bits and Pels in a Bit-Map Image 

 When an application creates a bit map by calling GpiCreateBitmap, it specifies 
 the bit-map width and height in terms of pels in the bit-map image. The width 
 is the number of pels within a row; the height is the number of rows. The 
 application must store these dimensions in the BITMAPINFO2 and 
 BITMAPINFOHEADER and pass their addresses to GpiCreateBitmap. 


═══ 6.1.1. System Implementation ═══

Bit maps are most useful when rapid and frequent movement is required, such as 
with icons and pointers. They are especially useful for restoring the contents 
of a window-for example, when an overlying window is removed. If you save the 
contents of a window in a bit map, you can restore the window contents simply 
by redisplaying the bit map when the window needs to be redrawn. 

Using bit maps is also an effective method of erasing some of the screen 
contents. For example, you can save the image of the screen in a bit map at any 
time while drawing on the screen. If you continue drawing after saving the 
screen image, you can "erase" any drawing done since you saved the screen image 
by redisplaying the bit map. 

Bit maps are not, however, the recommended way to store graphics that are going 
to be changed. Most changes to the bit-map contents mean that you have to 
re-create the bit map. 

Bit-map images are device-dependent. Their appearance is affected by the shape 
of the device's pels and the device's color capabilities. For example, if the 
pels on one display measure 0.05 mm by 0.1 mm, but 0.1 mm by 0.3 mm on a second 
display, a circular bit-map pie chart drawn on the first display appears 
elliptical on the second. The following figure shows how a bit map appears on 
two types of displays. 

Bit Map Shown on Two Types of Displays 

Bit maps, particularly color bit maps, can also occupy large amounts of memory. 
The actual amount of memory occupied by a bit map is determined by both the 
size of the bit map and the number of bits used to describe each pel. 


═══ 6.1.2. Bit Map Functions ═══

The OS/2 operating system provides a set of functions that allow you to: 

     Create bit maps 
     Create and load custom bit maps 
     Store color information on a bit map 
     Draw bit maps 
     Transfer bit maps 
     Change the size of a bit map 
     Specify the mix values for a bit map 
     Convert between monochrome and color data 
     Manipulate single pels 
     Copy images from a display into a bit map 
     Save a bit map 
     Delete a bit map 
     Make a bit map available to other processes 


═══ 6.1.2.1. Creating a Bit Map ═══

A bit map can be created by an application or by using the PM Icon Editor. 


═══ 6.1.2.1.1. By an Application ═══

To enable an application to create a bit map: 

   1. Create a memory device context. 

      A memory device context enables an application to treat a bit map in 
      memory as though it were a device. For example, an application can copy 
      color information from another bit map, or copy pels on the display, into 
      a bit map associated with a memory device context. 

      To create the memory device context, call DevOpenDC with: 

          A device type of OD_MEMORY (second argument) 

          A handle to a compatible device context (such as the device context 
           of a device with which the bit map is to be compatible). 

           Note:  The device device-context handle ideally should be the handle 
           of the actual device to which you will be directing the bit map. 
           Otherwise, it will be necessary to change ownership to the 
           appropriate device driver before the BitBlt operation (which copies 
           the bit map from one presentation space to one associated with a 
           screen device context). As a consequence, the image may appear 
           distorted. 

      If you omit the handle of the compatible device context by specifying 
      NULL, screen compatibility is assumed. 

   2. Create a graphics presentation space and associate it with the memory 
      device context. 

      The operating system requires this association before the application can 
      perform many of the bit map operations. The handle of this graphics 
      presentation space is required as input to subsequent bit-map-creation 
      and manipulation functions. 

   3. Create the bit map. 

      When an application creates a bit map, the handle of the presentation 
      space that you have associated with the memory device context causes the 
      bit map to be created in a format that is compatible with the memory 
      device context. 

      The application also passes two structures: the bit-map information 
      header and the bit-map information table. These structures contain a 
      great deal of information about the bit map. 

      To create the bit map, call GpiCreateBitmap with: 

          The handle of the presentation space (first argument) 
          The bit-map information header, BITMAPINFOHEADER (second argument). 
           (last argument). 

      The bit-map information table contains similar information, with the 
      addition of the RGB2 array structure. 

      GpiCreateBitmap returns a handle to the bit map, which is used to 
      identify the bit map. 

      To determine which bit-map formats are supported on a particular device, 
      call GpiQueryDeviceBitmapFormats. This returns every format supported on 
      a named device. The data is returned as an array of bit-map plane and 
      bit-count pairs. The first pair of values in the array is the one most 
      suitable for the device. 

      You can think of the bit map at this stage as a rectangular area of 
      memory containing random data. You can initialize the bit map at this 
      stage by providing GpiCreateBitmap with the address in application 
      storage of some initialization data and by setting the CBM_INIT option. 
      This is a useful function if, for example, your application always starts 
      by displaying the same image. 

   4. Select the bit map. 

      Before selecting the bit map, you can disassociate the presentation space 
      from the original memory device context and associate it with a different 
      memory device context. However, the bit-map format must be convertible to 
      a format that is supported by the new device. If you have selected one of 
      the four standard bit-map formats, this compatibility is guaranteed and 
      the conversion is automatic. 

      Note:  When a presentation space is associated with a memory device 
      context, a bit map must be selected into the device context before you 
      can draw in the presentation space. 

      To select the bit map, call GpiSetBitmap with: 

          The presentation-space handle (first parameter) 
          The bit-map handle (second parameter). 

 The following figure shows the sequence of events when you create and display 
 a bit map. 

 Creating and Displaying Bit Maps 

 The application: 

   1. Calls DevOpenDC to create the memory device context. 

   2. Creates a graphics presentation space. This is associated with the memory 
      device context. 

   3. Calls GpiCreateBitmap to define a bit map. 

   4. Calls GpiSetBitmap to designate the bit map as the one currently selected 
      in the memory device context. 

   5. Calls drawing instructions to the presentation space to draw to the bit 
      map. 

      Note:  If the bit map is initialized when it is created, this step does 
             not normally exist. Alternatively, this step can be a 
             GpiSetBitmapBits call. 

   6. Calls GpiBitBlt to copy the bit map from presentation space 1 to 
      presentation space 2 (associated with a screen device context). The bit 
      map is transferred directly to the screen. 


═══ 6.1.2.1.2. Using the Icon Editor ═══

Using the Icon Editor, you can create monochrome or color bit maps that have a 
static appearance. This means that the bit maps can be created in advance and 
then used without change while the application is running. 

When you use the Icon Editor to create a bit map, the bit map is saved in a 
resource file that can be loaded whenever it is needed. To load a bit-map file, 
call GpiLoadBitmap, with the identifier of the resource file that contains the 
bit map, as the second parameter. If you allow this value to default, the 
application's .EXE file is assumed to contain the bit map. 

GpiLoadBitmap lets you specify the x- and y-dimensions (in pels) of the bit 
map. The loaded bit map is stretched or compressed accordingly. If you supply a 
0 value for one of these dimensions, the bit map is sized in the other 
dimension only, which is likely to cause distortion of the image. If the bit 
map is to be produced in its original size, specify 0 for both its width and 
its height. 

Output from the call to this function is the bit-map handle. To display the 
loaded bit map on the screen, follow the sequence of steps described in the 
preceding section, omitting steps 3 (defining the bit map) and 5 (issuing 
drawing instructions to the presentation space). 

A bit map created by the Icon Editor is saved in a device-independent format. 
This format generates an array of bit maps with formats (bits per pel) matching 
each of the supported display devices. 


═══ 6.1.2.2. Creating and Loading a Custom Bit Map ═══

An application can create a custom bit map by setting the bits in an array and 
passing the array to GpiCreateBitmap or by running the Icon Editor and loading 
the bit map with GpiLoadBitmap. 

To create a custom bit map with an array, an application: 

   1. Defines an array of bytes that will set pels in an image to the 
      appropriate colors. This array of bytes typically represents the output 
      of a scanned image. 

   2. Sets the fields in the BITMAPINFOHEADER to their appropriate values. 

   3. Sets the fields in the BITMAPINFO2 structure to their appropriate values. 

   4. Calls GpiCreateBitmap, passes it the addresses of the structures and the 
      array of bytes that the application has already defined, and sets the 
      flOptions parameter to CBM_INIT. 

 If the application is to use this bit map as a fill pattern, it assigns the 
 bit map a local identifier by calling GpiSetBitmapId. 

 To load a custom bit map that was created with the Icon Editor: 

   1. Copy the bit map file to the directory in which you compile your 
      application. 

   2. Create a BITMAP entry in your application's resource file, assigning a 
      unique integer identifier to the bit map. 

   3. Call GpiLoadBitmap, passing it the identifier that you assigned to the 
      bit map in the resource file. 

 An application can use GpiLoadBitmap to load any bit map from a file that 
 conforms to any of the standard OS/2 bit-map formats or to a device-specific 
 format supported by the device concerned. This means that an application can 
 load a bit map created by another application, if that application created the 
 correct bit-map header and stored the bit-map bits correctly. 


═══ 6.1.2.3. Storing Color Information in a Bit Map ═══

Graphics systems use one of two formats for storing color information in bit 
maps. The first format uses a single plane and a multiple bit count. The second 
format uses multiple color planes. 


═══ 6.1.2.3.1. Color Planes ═══

Bit maps are arranged in one or more color planes. A color plane is an array of 
bit-map bits that contains color information. 

The bit maps in each of the previous illustrations use the single bit-map plane 
format, which is the standard format for bit maps in OS/2 applications. In this 
format, a specified number of adjacent bit-map bits contains indexes to either 
a special color table of RGB values or actual RGB2 structures. Whether the 
application maps bits into an RGB or RGB2 structure depends on the bit-map 
format. All of the color information resides in a single plane. 

The second color format uses more than one color plane. A common multiplane 
bit-map format is the three-plane format, in which one plane corresponds to the 
red pels, another to the green pels, and a third to the blue pels. Multiplane 
bit-map formats are rare in PM applications. Most bit maps are stored 
externally in a single-plane format, although the device driver (such as VGA) 
may internally convert them to the multiplane format. 

The single-plane format can be converted internally to any multiplane format 
used by a device. You also can use a nonstandard number of bits to describe 
each pel, if supported by your output device. If you write your own 
presentation driver, it must be able to convert the standard bit-map formats to 
its own internal format. 

An application can determine which color-plane format a device supports by 
calling GpiQueryDeviceBitmapFormats. 


═══ 6.1.2.3.2. Standard Bit-Map Formats ═══

On a monochrome device, you need only one bit to describe a single pel, and 
that bit is switched on or off. Color devices require more bits. For example, 
an eight-color picture requires three bits to describe a single pel, because 
each component of the RGB mix (red, green, blue) that gives a pel its color 
must be described. 

A bit count is a value that specifies how many adjacent bit-map bits correspond 
to each pel in a bit-map image.  There are four standard bit-map formats, each 
with a different bit count.  The formats are shown in the following table. 

┌────────────────────┬────────────────────┬────────────────────┐
│Format              │Bits per pel        │Size of 640 x 480   │
│                    │                    │image in bytes      │
│                    │                    │(uncompressed)      │
├────────────────────┼────────────────────┼────────────────────┤
│Monochrome          │1                   │38 400              │
├────────────────────┼────────────────────┼────────────────────┤
│16 color            │4                   │153 600             │
├────────────────────┼────────────────────┼────────────────────┤
│256 color           │8                   │307 200             │
├────────────────────┼────────────────────┼────────────────────┤
│16.7 million color  │24                  │921 600             │
└────────────────────┴────────────────────┴────────────────────┘

Note:  The bits are stored consecutively in the bit-map plane. If you have four 
bits for each pel, the four bits for pel 1 are followed by the four bits for 
pel 2, and so on. The bits that describe pel 1 are stored beginning in the 
most-significant bits of the first byte. The data for each scan line is packed 
together, and the bottom scan line appears first in memory with the leftmost 
pel first. Each scan line, however, is padded at the end so that each line 
begins on a ULONG (32-bit) boundary. 

If the device supports a bit count of one bit per pel, the color table contains 
two entries. A device that supports a bit count of n bits per pel, has a 
corresponding color table with 2n entries. However, a bit count of 24 bits per 
pel indicates that there is no color table, because each pel is a direct RGB 
value. 

The following figure shows a bit map using a bit count of four bits per pel and 
an associated color table: 

A Bit Map and Its Associated Color Table 

If a device uses a bit count of one, four or eight bits per pel, the bit-map 
bits contain index values for a bit-map color table. If the device supports a 
bit count of 24 bits per pel, the bit-map bits contain the bRed, bGreen, and 
bBlue fields of RGB2 structures. No color table is associated with a bit map on 
a device that supports a format of 24 bits per pel-such a device can support 
over 16 million colors. Instead of using a color table, the BITMAPINFO2 
structure consists of only the header, and the red, green, and blue color 
values are provided directly by the bit-map data. 

An application can determine the bit-count format that a device supports by 
calling GpiQueryDeviceBitmapFormats. 


═══ 6.1.2.4. Drawing Bit Maps ═══

An application can draw bit-map images on a raster printer or display screen, 
or into metafiles associated with a raster device. Any GPI drawing requests 
(including those that produce graphics text), issued to a presentation space 
associated with a memory DC containing a selected bit map, cause the bit map to 
receive raster images of your drawings. The following table describes the bit 
map drawing functions: 

┌────────────────────┬────────────────────┬────────────────────┐
│Function            │Input               │Output              │
├────────────────────┼────────────────────┼────────────────────┤
│WinDrawBitmap       │The handle of a bit │A bit-map image on a│
│                    │map.                │raster display.     │
├────────────────────┼────────────────────┼────────────────────┤
│GpiImage            │A buffer containing │A special monochrome│
│                    │bit map image data. │bit-map image on a  │
│                    │                    │raster display or   │
│                    │                    │printer.            │
├────────────────────┼────────────────────┼────────────────────┤
│GpiDrawBits         │A buffer containing │A bit-map image on a│
│                    │bit map image data. │raster display or   │
│                    │                    │printer.            │
├────────────────────┼────────────────────┼────────────────────┤
│GpiBitBlt           │The handle of a     │A bit-map image on a│
│                    │presentation space  │raster display or   │
│                    │containing a bit    │printer, or a       │
│                    │map.                │bit-map image into a│
│                    │                    │metafile (albeit in │
│                    │                    │an escape order).   │
├────────────────────┼────────────────────┼────────────────────┤
│GpiWCBitBlt         │The handle of a bit │A bit-map image on a│
│                    │map.                │raster display or   │
│                    │                    │printer, or a       │
│                    │                    │bit-map image into a│
│                    │                    │metafile.           │
└────────────────────┴────────────────────┴────────────────────┘


═══ 6.1.2.4.1. WinDrawBitmap ═══

WinDrawBitmap draws a bit-map image by copying it into a window linked to a 
target presentation space. A call to this function is valid only in draw mode 
(DM_DRAW), and only for a screen device context. This function does not require 
an application to select a bit map into a presentation space before the 
application draws the corresponding image. An application can use WinDrawBitmap 
to scale bit maps by specifying DBM_STRETCH as the last argument, and the 
address of a RECTL structure as the fourth argument. The coordinates in this 
structure are always device coordinates. 

WinDrawBitmap draws both color and monochrome bit maps. Color bit maps require 
no color conversion. Monochrome bit maps can be drawn in any two colors which 
can be explicitly specified as parameters to the call or taken from the image 
bundle. These parameters will be color table indexes or RGB values, depending 
on the color table mode of the target presentation space. The current image 
bundle mix modes are used and, for certain mix values, will affect color. 

You can call WinDrawBitmap in retain mode, but the bit-map image will only be 
drawn and not recorded in the segments. 

Note:  An application can determine the current colors and their corresponding 
mix modes by calling GpiQueryAttrs. The application can set them by calling 
GpiSetAttrs. 

An inverted bit map is a bit map in which the colors have been inverted; white 
becomes black and black becomes white. An application can draw inverted bit 
maps by calling WinDrawBitmap and passing it DBM_INVERT as the last argument. 
An application can draw halftone bit maps by calling WinDrawBitmap and passing 
it DBM_HALFTONE as the last argument. Before drawing the bit map, clear the 
presentation space to CLR_BACKGROUND using GpiErase. 


═══ 6.1.2.4.2. GpiImage ═══

GpiImage draws a nonstandard, monochrome (two-color) bit map called an image 
primitive. The bit-map bits in an image are stored in the opposite order from 
the bits in a standard bit map-the first bit in the bit map corresponds to the 
pel in the upper-left corner of the bit-map image, and the last bit in the bit 
map corresponds to the pel in the lower-right corner of the bit-map image. The 
following figure shows the correspondence between the bits in an image 
primitive and the pels in the drawing produced by GpiImage. 

Image-Primitive Bits and Pels 

A call to GpiImage also is valid only in draw mode (DM_DRAW), but can provide 
output to a screen or printer. An application cannot scale bit-map images by 
using GpiImage. 


═══ 6.1.2.5. Transferring Bit Maps ═══

The three remaining bit-map drawing functions operate in very similar ways. 
GpiDrawBits copies a bit-map image from application memory to a device or a 
device context. GpiBitBlt directs bit maps to devices other than the screen. 
GpiWCBitBlt enables you to retain the bit-map data in the segment store of the 
target presentation space. 

The similarities are discussed first. Their differences are discussed in the 
sections that follow. 

An application should use GpiDrawBits, GpiBitBlt, or GpiWCBitBlt to draw bit 
maps that use a color table or RGB2 structures color formats of 1, 4, 8, or 24 
bits per pel. 

An application can draw inverted bit maps for any of these three functions by 
calling the function and passing ROP_NOTSRCCOPY as the raster operation. 


═══ 6.1.2.5.1. GpiDrawBits ═══

GpiDrawBits copies bit map image data from storage into a bit map that has been 
selected into a device context associated with a presentation space. It can 
also copy bit-map image data to a device. An application can use this function 
to draw a bit map without first selecting the bit map into a presentation 
space. 

This function is valid in all draw modes. Set the draw mode to DM_RETAIN or 
DM_DRAWANDRETAIN to create retained segments; otherwise, the default mode, 
DM_DRAW, is selected. 


═══ 6.1.2.5.2. GpiBitBlt ═══

GpiBitBlt requires an application to use device coordinates for the dimensions 
of the source and target rectangles. GpiBitBlt allows you to direct bit maps to 
devices other than the screen. It is independent of the drawing mode, but it 
operates as if in draw mode. 

At its simplest, GpiBitBlt copies a whole bit map, unaltered, from a device or 
bit map source to a device or bit map target. At its most powerful, GpiBitBlt 
can take a part of or a whole bit map, and alter both its size and appearance 
in the process of copying it to another device context. A bit map can be 
copied: 

     From one memory device context to another memory device context 

     From a memory device context to the device context of an output device 
      (screen window or printer) that supports raster operations 

     From the device context of an output device to a memory device context 

     From the device context of an output device to another device context of 
      the same output device. In both cases, the screen device can be a PM 
      window. 

 A memory device context (whether it is the source or the target of the 
 GpiBitBlt operation) must have a bit map selected when GpiBitBlt is called. 

 GpiBitBlt has a number of input parameters, two of which are the handles of 
 two presentation spaces:  the source presentation space and the target 
 presentation space. Both of these presentation spaces must be associated with 
 an appropriate device context. Unless the associated device is a banded 
 printer, a single presentation space can be both source and target. This 
 allows you to copy a bit map within a single PM window, or to update the bit 
 map. The source and target rectangles are specified in device coordinates in 
 GpiBitBlt. GpiBitBlt, consequently, is very device-dependent, and should be 
 avoided when creating data for interchange. 


═══ 6.1.2.5.3. GpiWCBitBlt ═══

GpiWCBitBlt enables you to retain the bit-map data in the segment store of the 
target presentation space. It is a valid in all three drawing modes: 

     DM_DRAW-display, printer, or into metafile 
     DM_RETAIN-into metafile or segment 
     DM_DRAWANDRETAIN-display, printer, then into associated segment or 
      metafile. 

 Most of the bit-map drawing operations occur in an application's device space. 
 GpiWCBitBlt, however, lets an application draw in its world space, but 
 requires that you use device coordinates for the source rectangle, and world 
 coordinates for the target rectangle. 

 An application can use GpiWCBitBlt to draw a bit map with consistent 
 dimensions on devices with different aspect ratios. The aspect ratio is the 
 ratio of a pel's width to its height. 

 When creating data for interchange, use GpiWCBitBlt. GpiWCBitBlt provides the 
 same function as GpiBitBlt, with the following exceptions: 

     The target rectangle is specified in world coordinates, and all four 
      coordinates (the two source-rectangle coordinates and the two 
      target-rectangle coordinates) must be specified. 

     The source handle must be a bit-map handle. It must not be the handle of 
      a source presentation space. The bit map identified by the source handle 
      must not be selected into a memory device context when you call 
      GpiWCBitBlt. 

     GpiWCBitBlt conforms to the current drawing mode in the target 
      presentation space. If the drawing mode is retain or draw-and-retain, the 
      bit map is retained in segment store. 


═══ 6.1.2.6. Changing the Size of the Bit Map ═══

You can specify the sizes of the rectangular bit blocks in both the source and 
the target presentation spaces. To do this, provide an array of up to four 
device-coordinate positions as input to the call. The first two positions 
define the lower-left and upper-right corners of the target rectangle; the 
second two define the same two corners of the source rectangle. 

If you want the two rectangles to be of equal size, do not specify the device 
coordinates of the upper-right corner of the source rectangle. The correct 
amount of data is automatically transferred to fill the target rectangle. The 
following figure shows the points count for bit-block transfers. 

Points Count for Bit-Block Transfers 

Equal-size rectangles can be built much faster than rectangles that need 
stretching or compressing. Compression options (flOptions) are ignored if the 
rectangles are to be of equal size. 

If the rectangles are not to be of equal size, you must specify all four 
coordinate points. The bit-map data is stretched, if the target rectangle is 
larger than the source rectangle, or compressed, if the target rectangle is 
smaller, to fit the target rectangle. The bit map is stretched by duplicating 
rows and columns of data, an action that might cause distortion of the image. 
If the data is to be compressed, you can specify one of three compression 
options as shown in the following table. 

Bit-map Data Compression Rules 

┌────────────────────┬────────────────────────────────────────┐
│Option              │Compression Rules                       │
├────────────────────┼────────────────────────────────────────┤
│BBO_OR              │Compresses the bit map data as          │
│                    │necessary, using a logical OR operation │
│                    │on the eliminated rows and columns. This│
│                    │is useful for preserving the foreground │
│                    │when foreground pels are "1" and the    │
│                    │background pels are "0".                │
├────────────────────┼────────────────────────────────────────┤
│BBO_AND             │Compresses the bit map data as          │
│                    │necessary, using a logical AND operation│
│                    │on the eliminated rows and columns. This│
│                    │is useful for preserving the foreground │
│                    │when foreground pels are "0" and the    │
│                    │background pels are "1".                │
├────────────────────┼────────────────────────────────────────┤
│BBO_IGNORE          │Compresses the bit map data as          │
│                    │necessary, but ignores any eliminated   │
│                    │rows or columns. This is most useful for│
│                    │color bit maps, where the results of    │
│                    │combining pels of different colors are  │
│                    │unpredictable.                          │
└────────────────────┴────────────────────────────────────────┘


═══ 6.1.2.7. Specifying Mix Values ═══

When you draw a graphics primitive into a presentation space, it is affected by 
the current foreground-mix value, and possibly by the current background-mix 
value, in that presentation space. However, when you copy a bit map into a 
target presentation space, the current foreground- and background-mix values in 
the target presentation space are ignored. Instead, you specify a mix-mode 
value, also known as the raster-operation (ROP) value. This value determines: 

     How the bit map is affected by any data that might already be in the 
      target presentation space 

     The color of each pel in the bit map 

 Each pel in the bit map of the target presentation space has, potentially, 
 three color settings: 

     The setting of that pel in the source rectangle 

     The initial setting of that pel in the target rectangle 

     The setting of that pel in the current area-fill pattern in the target 
      presentation space 

 The (boolean) values of each of these settings can be combined using boolean 
 operations to produce the final value of each pel in the target presentation 
 space. For a color target, the target must be regarded as consisting of 
 multiple one-bit per pel planes, with the mixing applied to each plane 
 separately to produce the final color index into the physical color table. 
 Because the final color index is an index into the physical palette, the 
 results of any color mixing are therefore unpredictable. For example, if you 
 ORed together two numeric index values, the color indexed by the result is 
 unlikely to have any direct relation to the colors indexed by the two values 
 you ORed together. It depends on the order of the colors in the physical 
 table. 

 As input to the functions, you supply an actual mix value. The ROP mix value 
 required to achieve any given result can be determined from the following 
 table. The final value of each bit in every pel depends on the values of the 
 corresponding bits in the pattern (P), source (S), and the original target 
 value (T initial). Each row of the table shows one of the eight possible 
 combinations of these values. For each combination, mark the desired final 
 target value in the last column. The eight bits in this column then show the 
 value of the least significant byte of the ROP value required to achieve this 
 mixing function. For example, if the required mixing function is to copy the 
 source to the target, then the target (final) column will be the same as the S 
 column, and the ROP value will have the binary value 11001100, or the 
 hexadecimal value 00CC. 

 Possible Settings for the Index Bits 

  ┌───────┬───────┬────────────────┬──────────────┬────────────────┐
  │Pattern│Source │Target (initial)│              │Target (final)  │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │0      │0      │0               │              │Index bit 0     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │0      │0      │1               │              │Index bit 1     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │0      │1      │0               │              │Index bit 2     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │0      │1      │1               │              │Index bit 3     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │1      │0      │0               │              │Index bit 4     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │1      │0      │1               │              │Index bit 5     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │1      │1      │0               │              │Index bit 6     │
  ├───────┼───────┼────────────────┼──────────────┼────────────────┤
  │1      │1      │1               │              │Index bit 7     │
  └───────┴───────┴────────────────┴──────────────┴────────────────┘

 If you want the pattern to have no effect on the target rectangle, the four 
 low-order bits of the index must be the same as the four high-order bits. 

 A monochrome bit map consists only of source settings of 1s and 0s, where a 1 
 or 0 represents each pel. It also has a two-entry color table with index 0 
 specifying what color a 0 pel represents and index 1 representing what color a 
 1 pel represents. In a monochrome bit map, this color table is not used during 
 BitBlt operations (but is used when drawing to the bit map and moving the bit 
 map between devices). The preceding table defines how any combination of 
 pattern, source and target original (1 and 0) values define the target final 
 (1 or 0) value. A color bit map has an index (in the case of four bits, 0-15) 
 for each pel which, serves as index into the bit map color table (16 entries 
 for four bits per pel) to define the color of each pel. Unlike monochrome bit 
 maps, this table is used during BitBlt operations (instead of target image 
 bundle attributes) to provide the color of the target output. 

 The following table represents a selection of the most commonly used mixes 
 with predefined symbolic names and their effects. (There are many other 
 possible mixes). 

 Mix Value Names 

  ┌──────────────────┬──────────────────────────────────────────┐
  │Mix Name          │Effect                                    │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_SRCCOPY       │Source                                    │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_SRCPAINT      │Source OR Target                          │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_SRCAND        │Source AND Target                         │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_SRCINVERT     │Source XOR Target                         │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_SRCERASE      │Source AND NOT (Target)                   │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_NOTSRCCOPY    │NOT (Source)                              │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_NOTSRCERASE   │NOT (Source) AND NOT (Target)             │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_MERGECOPY     │Source AND Pattern                        │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_MERGEPAINT    │NOT (Source) OR Target                    │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_PATCOPY       │Pattern                                   │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_PATPAINT      │NOT (Source) OR Pattern OR Target         │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_PATINVERT     │Target XOR Pattern                        │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_DSTINVERT     │NOT (Target)                              │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_ZERO          │0                                         │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_ONE           │1                                         │
  ├──────────────────┼──────────────────────────────────────────┤
  │ROP_GRAY          │Gray pattern background                   │
  └──────────────────┴──────────────────────────────────────────┘

 ROP_SRCCOPY is the most often used value. It simply copies the bit map to the 
 target presentation space without performing any color mixing. Because most of 
 the remaining mixes involve some degree of color mixing, they result in an 
 image that is quite different from the original. 


═══ 6.1.2.8. Converting between Monochrome and Color Data Bit Maps ═══

It is possible to copy a monochrome bit map to a color bit map or device, and 
to copy a color bit map to a monochrome bit map or device. PM handles these 
conversions automatically according to the following rules: 

     If you are copying a monochrome bit map to a color bit map or to a color 
      or monochrome device surface, a source setting of 1 adopts the current 
      image-foreground color of the target presentation space, and a source 
      setting of 0 adopts the current image-background color of the target 
      presentation space. For example, if the image foreground color is blue 
      and the image background color is yellow in the target presentation 
      space, a monochrome bit map is converted to a blue foreground on a yellow 
      background. 

     If you are copying from a monochrome pattern to a color bit map or 
      device, a source setting of 1 adopts the current area-foreground color of 
      the target device and a source setting of 0 adopts the current 
      area-background color of the target device. Note that if image bundle 
      attributes do not exist for the source bit map, as is the case when using 
      GpiWCBitBlt (which uses a bit map handle as the source), then zero source 
      pixels adopt the image background color and nonzero source pixels adopt 
      the image-foreground color of the presentation space. 

     If you are copying a color bit map to a monochrome bit map or device, 
      those pels that have the same color as the current image-background color 
      in the source presentation space adopt the image background color of the 
      target presentation space. For example, if the current image-background 
      color in the source presentation space is blue, all blue pels in the bit 
      map take on the color of the current image background in the target 
      presentation space. 

      All other pels in the color bit map adopt the current image foreground 
      color of the target presentation space. 


═══ 6.1.2.9. Manipulating Single Pels ═══

You can manipulate single pels in a bit map by using GpiSetPel and GpiQueryPel. 
GpiSetPel sets the pel at the specified point (in world coordinates) to the 
current line color. This function is independent of the current drawing mode, 
and its effect is immediate. It is, however, a device-dependent function. The 
CAPS_RASTER_CAPS option of DevQueryCaps indicates if GpiSetPel is supported on 
the current device. 


═══ 6.1.2.10. Copying Images from a Display into a Bit Map ═══

An application can copy an image from a raster display screen to a bit map by 
calling GpiBitBlt or GpiWCBitBlt. Before copying the bit map, the application 
must call DevOpenDC to create a memory device context. This device context 
allows an application to treat a bit map in memory as though it were a 
device-the application can copy color information from pels on the display to 
the bit map. 

Once an application creates a memory device context, associates it with a 
presentation space, and selects a bit map into the presentation space, the 
application can use the presentation-space handle as the first argument to 
GpiBitBlt or GpiWCBitBlt. If the application will be drawing the image on 
devices with different aspect ratios, the application should use GpiWCBitBlt to 
preserve the original dimensions of the bit map. 


═══ 6.1.2.11. Saving a Bit Map ═══

You have two ways to save a bit map that has been created by an application: 

     Store the bit map in a metafile, by calling GpiWCBitBlt. 

      Metafiles are covered in detail later. 

     Use the IBM OS/2 file-handling functions, in conjunction with 
      GpiQueryBitmapBits and GpiSetBitmapBits. 

      An application can save a bit map in a file by calling 
      GpiQueryBitmapBits, DosOpen, DosWrite, and DosClose. 

 GpiQueryBitmapBits copies bit-map data from a memory device context (that has 
 a standard-format bit map selected into it) to a buffer. The bit map you copy 
 can be newly created or have been loaded from a resource file. 

 You must supply the address in application storage of a bit-map information 
 table. The bit-map information table has the same structure as the bit map 
 information header, except for an additional entry, the colors field. As input 
 to GpiQueryBitmapBits, you supply a bit-count value and a plane value. These 
 must both be standard bit-map format values, so the plane value is always 1, 
 and the bit-count value is 1, 4, 8, or 24. If any conversion of the bit-map 
 data is necessary, it is done automatically. You also must provide the address 
 of the application storage into which the bit-map data is to be loaded. You 
 probably will need to find out how large the bit map is before you can do 
 this. GpiQueryBitmapParameters returns the width, height, plane count, and bit 
 count of a named bit map. 

 You also must supply the size of the fixed portion of the header (as well as 
 bit count, and so on). Nonstandard formats supported by the device that owns 
 the bit map will also be valid for GpiQueryBitmapBits. 

 You must ensure that you allocate sufficient storage at the end of the bit map 
 information table for the returned color table which, if the number of planes 
 is 1, will have 2n entries, where n is the number of bits per pel. 

 On return from GpiQueryBitmapBits, the system supplies the width, height, and 
 bit-map color table in the bit-map information table. You can retrieve a part 
 of a bit map by specifying the number of the scan line from which the transfer 
 is to start, and the number of scan lines you want. 

 When you have copied a bit map into application storage, you can save the bit 
 map externally, and reload it later, by using OS/2 file-handling functions. 
 After the application creates a file by calling DosOpen, it can call DosWrite 
 to copy the buffer containing the bit-map bits into the file. The application 
 then closes the file by calling DosClose. 

 If an application needs to use a bit map it has stored on disk, it can copy 
 the file's contents into a buffer by calling DosRead, and then copy 
 information about the image to the bit map by calling GpiSetBitmapBits. The 
 application must select the bit map into a memory device context before it 
 sets the bits. As with GpiQueryBitmapBits, you can transfer a part of the bit 
 map rather than the whole. GpiSetBitmapBits can be used to transfer 
 standard-format bit maps only, and only to a bit map selected into a memory 
 device context. If necessary, bit-map data is automatically converted from one 
 standard format to another. Nonstandard formats supported by the device owning 
 the bit map will also be valid for GpiSetBitmapBits. 

 If an application creates bit maps another application might use, it should 
 create them by using the standard IBM OS/2 bit-map file format. 


═══ 6.1.2.12. Deleting a Bit Map ═══

It is good practice always to delete a bit map from memory when you have 
finished using it. To delete a bit map, use GpiDeleteBitmap. If you have loaded 
a bit map from a resource file, GpiDeleteBitmap deletes only its memory 
version. If the bit map has not been deleted when the owning process ends, it 
is deleted automatically by the system. 


═══ 6.1.2.13. Making Bit Maps Available to Other Processes ═══

When an application creates a bit map or loads one from a resource file, it can 
make the bit map available to other processes by placing the bit-map handle in 
the clipboard. 


═══ 6.2. Using Bit Maps ═══

An application can use bit-map functions to: 

     Copy an image from a raster device (such as a display screen) to a bit 
      map 
     Copy an image from a raster device (such as a display screen) to the same 
      device 
     Copy an image from a bit map to a raster device 
     Copy an image from a bit map to another bit map 
     Copy an image from application memory to a bit map 
     Copy an image from application memory to a raster device 
     Scale bit-map images 
     Create custom fill patterns for area primitives and paths 
     Load a bit map created with the Icon Editor 
     Draw bit-map images 
     Store bit maps in a metafile or application memory 


═══ 6.2.1. Copying an Image from a Display Screen to a Bit Map ═══

To copy an image from a display screen to a bit map: 

   1. Associate the memory device context with a presentation space. 

   2. Create a bit map. 

   3. Select the bit map into the memory device context by calling 
      GpiSetBitmap. 

   4. Determine the location (in device coordinates) of the image. 

   5. Call GpiBitBlt and copy the image to the bit map. 

 The following figure demonstrates these steps. 


      HDC hdcMem;
      PSZ pszData[4] = { "Display", NULL, NULL, NULL };
      HPS hpsMem, hps;
      HAB hab;
      SIZEL sizlPage = {0, 0};
      BITMAPINFOHEADER2 bmp;
      PBITMAPINFO2 pbmi;
      HBITMAP hbm;
      SHORT sWidth = 128, sHeight = 128;
      POINTL aptl[3];
      LONG alData[2];

      /*
       * Create the memory device context and presentation space so they
       * are compatible with the screen device context and presentation space.
       */

      hdcMem = DevOpenDC(hab, OD_MEMORY, "*", 4,
          (PDEVOPENDATA) pszData, NULLHANDLE);

      hpsMem = GpiCreatePS(hab, hdcMem, &sizlPage,
          PU_PELS | GPIA_ASSOC | GPIT_MICRO);

      /* Determine the device's plane/bit-count format. */

      GpiQueryDeviceBitmapFormats(hpsMem, 2, alData);

      /*
       * Load the BITMAPINFOHEADER2 and BITMAPINFO2 structures. The sWidth and
       * sHeight fields specify the width and height of the destination
       * rectangle.
       */

      bmp.cbFix = (ULONG) sizeof(BITMAPINFOHEADER2);
      bmp.cx = sWidth;
      bmp.cy = sHeight;
      bmp.cPlanes = alData[0];
      bmp.cBitCount = alData[1];
      bmp.ulCompression = BCA_UNCOMP;
      bmp.cbImage = (((sWidth *
          (1 << bmp.cPlanes) * (1 << bmp.cBitCount)) + 31) / 32) * sHeight;
      bmp.cxResolution = 70;
      bmp.cyResolution = 70;
      bmp.cclrUsed = 2;
      bmp.cclrImportant = 0;
      bmp.usUnits = BRU_METRIC;
      bmp.usReserved = 0;
      bmp.usRecording = BRA_BOTTOMUP;
      bmp.usRendering = BRH_NOTHALFTONED;
      bmp.cSize1 = 0;
      bmp.cSize2 = 0;
      bmp.ulColorEncoding = BCE_RGB;
      bmp.ulIdentifier = 0;


      DosAllocMem((PPVOID)&pbmi, sizeof(BITMAPINFO2) +
          (sizeof(RGB2) * (1 << bmp.cPlanes) * (1 << bmp.cBitCount)),
          PAG_COMMIT | PAG_READ | PAG_WRITE);

      pbmi->cbFix = bmp.cbFix;
      pbmi->cx = bmp.cx;
      pbmi->cy = bmp.cy;
      pbmi->cPlanes = bmp.cPlanes;
      pbmi->cBitCount = bmp.cBitCount;
      pbmi->ulCompression = BCA_UNCOMP;
      pbmi->cbImage = ((sWidth+31)/32) * sHeight;
      pbmi->cxResolution = 70;
      pbmi->cyResolution = 70;
      pbmi->cclrUsed = 2;
      pbmi->cclrImportant = 0;
      pbmi->usUnits = BRU_METRIC;
      pbmi->usReserved = 0;
      pbmi->usRecording = BRA_BOTTOMUP;
      pbmi->usRendering = BRH_NOTHALFTONED;
      pbmi->cSize1 = 0;
      pbmi->cSize2 = 0;
      pbmi->ulColorEncoding = BCE_RGB;
      pbmi->ulIdentifier = 0;

      /* Create a bit map that is compatible with the display.            */

      hbm = GpiCreateBitmap(hpsMem, &bmp, FALSE, NULL, pbmi);

      /* Associate the bit map and the memory presentation space.         */

      GpiSetBitmap(hpsMem, hbm);

      /* Copy the screen to the bit map.                                  */

      aptl[0].x = 0;       /* Lower-left corner of destination rectangle  */
      aptl[0].y = 0;       /* Lower-left corner of destination rectangle  */
      aptl[1].x = sWidth;  /* Upper-right corner of destination rectangle */
      aptl[1].y = sHeight; /* Upper-right corner of destination rectangle */
      aptl[2].x = 0;       /* Lower-left corner of source rectangle       */
      aptl[2].y = 0;       /* Lower-left corner of source rectangle       */

      hps = WinGetScreenPS(HWND_DESKTOP);

      GpiBitBlt(hpsMem, hps,
          sizeof(aptl) / sizeof(POINTL), /* Number of points in aptl      */
          aptl, ROP_SRCCOPY, BBO_IGNORE);

      WinReleasePS(hps);


═══ 6.2.2. Scaling and Drawing a Bit-Map Image ═══

You can scale a bit map by calling GpiBitBlt or GpiWCBitBlt and altering the 
dimensions of the target rectangle. The following figure shows how to shrink 
the screen copied in the first example to half its original size, and then 
redraw it by calling GpiBitBlt. 

    POINTL aptl[3];
    HPS hpsMem, hps;
    HWND hwnd;
    SHORT sWidth = 128, sHeight = 128;
    /* Target-rectangle dimensions (in device coordinates)              */
    aptl[0].x = 0;
    aptl[0].y = 0;
    aptl[1].x = sWidth / 2;
    aptl[1].y = sHeight / 2;

    /* Source-rectangle dimensions (in device coordinates)              */
    aptl[2].x = 0;
    aptl[2].y = 0;
    aptl[3].x = sWidth;
    aptl[3].y = sHeight;

    hps = WinGetPS(hwnd);

    GpiBitBlt(hps, hpsMem,
        sizeof(aptl) / sizeof(POINTL),      /* Number of points in aptl */
        aptl, ROP_SRCCOPY, BBO_IGNORE);

    WinReleasePS(hps);


═══ 6.2.3. Creating a Custom Fill Pattern ═══

To create a custom fill pattern that the operating system will use to fill area 
primitives and paths: 

   1. Set an array of bits for a bit map that measures 8-bits-by-8-bits 
      (remember that the operating system pads the bit-map bits on a ULONG 
      (32-bit) boundary). 

   2. Create a bit map in a screen presentation space by calling 
      GpiCreateBitmap and passing it the address of the array of bits from Step 
      1. 

   3. Assign a local identifier (lcid) to the bit map by calling 
      GpiSetBitmapId. 

   4. Set the attribute of the pattern set in the AREABUNDLE structure by 
      calling GpiSetPattern. 

 The following figure shows how to create the pattern. 

      /* Define an array of bytes;  this array creates a grid pattern. */

      BYTE abPattern5[] = {
          0xFF, 0xFF, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00,
          0x80, 0x00, 0x00, 0x00 };

          LONG lcidCustom = 1;
      HPS hps;
      PBITMAPINFO2 pbmi;
      BITMAPINFOHEADER2 bmp;
      HBITMAP hbm;
      PRGB2 prgb2;

      /* Create the bit map, passing the address of the array of bytes. */
      hbm = GpiCreateBitmap(hps, &bmp, CBM_INIT, (PBYTE) abPattern5, pbmi);

      /* Assign a local identifier to the bit map.                      */
      GpiSetBitmapId(hps, hbm, lcidCustom);

      /* Set the pattern-set attribute in the AREABUNDLE structure.     */
      GpiSetPatternSet(hps, lcidCustom);


═══ 6.2.4. Loading a Bit Map from a File ═══

You can load a bit map from a file if the format of the file corresponds to the 
standard IBM OS/2 bit-map file format. (Any bit map that you create with the 
Icon Editor is automatically stored in this format.) To load a bit map: 

   1. Copy the bit-map file to the directory that contains your application's 
      resource file and source code. 

   2. Create an entry in your application's resource file, assigning a unique 
      integer identifier to the bit map. 

   3. Call GpiLoadBitmap in your application's source code, passing it the 
      integer identifier that you assigned to the bit map in your application's 
      resource file. 

 You can actually include your bit map in the application's .EXE file or in a 
 separate resource file. If the bit map is included in a separate resource 
 file, you must specify both the resource ID and the ID of the bit map within 
 the resource file on GpiLoadBitmap. If bit map is to be included in the 
 application's .EXE file, the resource ID is specified as NULL and only the ID 
 of the bit map is required by GpiLoadBitmap. 

 Following is an example of code from an application's resource file that 
 assigns the integer value 200 to a bit-map file called CUSTOM.BMP. 

      BITMAP  200 CUSTOM.BMP

 The following figure is an example of code from the application that shows how 
 to retrieve a bit-map handle by calling GpiLoadBitmap, use the handle to tag 
 the bit map by calling GpiSetBitmapId, and then use the local identifier 
 supplied by GpiSetBitmapId to set the bit map as the current fill pattern, 
 using GpiSetPatternSet. 

      HPS hps;
      HBITMAP hbm;
      LONG lcidCustom = 1;
      POINTL ptl;

      hbm = GpiLoadBitmap(hps,  /* Presentation-space handle        */
          NULLHANDLE,           /* Resource in application's module */
          IDB_PATTERN,          /* Bit-map ID                       */
          16,                   /* Bit-map width                    */
          16);                  /* Bit-map height                   */

      /* Assign a local identifier to the bit map.                  */
      GpiSetBitmapId(hps, hbm, lcidCustom);

      /* Set the pattern-set attribute in the AREABUNDLE structure. */
      GpiSetPatternSet(hps, lcidCustom);

      ptl.x = 100;
      ptl.y = 100;
      GpiMove(hps, &ptl);
      ptl.x = 200;
      ptl.y = 200;
      GpiBox(hps, DRO_OUTLINEFILL, &ptl, 0, 0);


═══ 6.2.5. Storing a Bit Map in a Metafile ═══

You can draw bit maps in a metafile or segment by calling GpiWCBitBlt. The 
operating system converts this function to a drawing order. The 
target-rectangle dimensions that you pass to GpiWCBitBlt are in world 
coordinates, not device coordinates. The following figure shows how to draw a 
bit map in a metafile, and then play the metafile. 

    DEVOPENSTRUC dop;
    HDC hdcMeta;
    HPS hps, hpsMeta;
    SIZEL sizlPage;
    HMF hmf;
    HBITMAP hbm;
    HAB hab;
    HWND hwnd;
    POINTL aptl[4];

    dop.pszLogAddress = NULL;
    dop.pszDriverName = "DISPLAY";
    dop.pdriv = NULL;
    dop.pszDataType = NULL;

    hdcMeta = DevOpenDC(hab, OD_METAFILE, "*", 4L,
                  (PDEVOPENDATA) &dop, NULLHANDLE);
    hpsMeta = GpiCreatePS(hab, hdcMeta, &sizlPage, PU_PELS | GPIA_ASSOC);

    hbm = GpiLoadBitmap(hpsMeta, NULLHANDLE, IDB_PATTERN, 16L, 16L);

    aptl[0].x = aptl[0].y = 0;  /* Lower-left corner target rectangle        */
    aptl[1].x = 150;            /* X coordinate upper-right target rectangle */
    aptl[1].y = 300;            /* Y coordinate upper-right target rectangle */
    aptl[2].x = aptl[2].y = 0;  /* Lower-left corner source rectangle        */
    aptl[3].x = aptl[3].y = 16; /* Upper-right corner source rectangle       */

    GpiWCBitBlt(hpsMeta, hbm, 4L, aptl, ROP_SRCCOPY, BBO_IGNORE);

    GpiAssociate(hpsMeta, NULLHANDLE);
    hmf = DevCloseDC(hdcMeta);

    hps = WinGetPS(hwnd);

    GpiPlayMetaFile(hps, hmf, 0L, NULL, NULL, 0L, NULL);

    WinReleasePS(hps);

You can also store a bit map in a metafile by calling GpiBitBlt. In this case, 
however, the bit map will be stored inside an escape order. 


═══ 7. Creating and Drawing Retained Graphics ═══

There are two types of graphics output in the OS/2 operating system: 

     Retained graphics, which are stored in segments and can be redrawn or 
      edited when necessary 

     Nonretained graphics, which are drawn immediately but not stored and 
      therefore cannot be used again without repeating the graphics functions 
      needed to re-create the picture 

 This chapter describes the advantages of using retained graphics and provides 
 information on creating and drawing retained graphics. 

 The following topics are related to the information in this chapter: 

     Presentation spaces and device contexts 
     Coordinate spaces and transformations 
     Editing retained graphics and graphics segments 


═══ 7.1. About Creating and Drawing Retained Graphics ═══

An application draws by calling graphics functions. Applications store retained 
graphics in segments, which can be edited. This means that the retained image 
can be modified without having to re-create the unmodified portion using 
multiple GPI functions. 

When using nonretained graphics, the output appears on the output device (for 
example, a window) immediately. However, if part of the picture is erased or 
must be repeated, the application must call the same graphics functions a 
second, or even a third time. 

There are many other advantages to using retained graphics, including: 

     Convenience-An application can draw retained graphics with a single 
      function that accesses the storage area containing all the individual 
      functions necessary for the object. 

     Flexibility-An application can redraw graphics retained in the segment 
      store to any number of device contexts. 

     Editing-An application can modify an object without having to call all 
      the functions necessary to re-create the picture. Individual segments can 
      be moved, scaled, or rotated; then, redrawn. 

      Editing the graphics within a segment is described in Editing Retained 
      Graphics and Graphics Segments. 

     Power-An application can access the more powerful and useful graphics 
      functions only when graphics are stored in segments. 

     Organization-An application can use segments to store the components that 
      will be assembled into the final picture. 

 Primarily, a graphics segment is a means of grouping and storing graphics 
 primitives and their attributes. Although the graphics within a segment 
 usually are related in some way, they do not have to be. A segment might 
 contain a number of unrelated GPI functions that you want to keep and execute 
 at specific times. 

 Retained graphics do affect application performance, however, in that a normal 
 presentation space requires 114KB of main memory more than a micro 
 presentation space, and using the drawing mode DM_RETAIN adds an additional 
 46KB. 

 Note:  Your application can have up to 16KB (16378) segments in the segment 
        store of a single presentation space. The size of an individual segment 
        is limited only by the amount of storage available to you. 

 Do not confuse a graphics segment with a memory segment. 


═══ 7.1.1. Drawing Modes ═══

When you create a presentation space, the drawing mode is set to draw. Your 
application can change this mode using GpiSetDrawingMode. The two additional 
drawing modes provided by the PM are retain (DM_RETAIN) and draw-and-retain 
(DM_DRAWANDRETAIN). Your application can determine which drawing mode is set by 
using GpiQueryDrawingMode. 

The drawing mode that you select becomes current for the presentation space, 
and it can be changed any number of times. Select the appropriate drawing mode 
before creating a segment. The drawing mode affects the segment type. 


═══ 7.1.1.1. Draw Mode ═══

In draw mode, graphics output is provided immediately to the currently 
associated device and is not retained in a segment store.  When the graphics 
have been drawn, they cannot be used again unless they are re-created. For 
example, when a window containing draw mode graphics is moved or sized, the 
graphics have to be re-created by the application. 

Draw mode graphics are suitable if an application is creating fairly simple 
graphics quickly or is maintaining its own graphics database.  In the latter 
case, there is nothing to gain by retaining graphics. 

A segment created when the drawing mode is DM_DRAW, is called a nonretained 
segment. While it might sound contradictory, nonretained segments have certain 
advantages that are described in Nonretained Graphic Segments. 


═══ 7.1.1.2. Retain Mode ═══

In retain mode, graphics are retained in the segment store only. They are not 
directed to the current device as they are created. 

In retain mode, the presentation space does not have to be associated with a 
device context when graphics are being defined. It is possible to define 
graphics and store their definitions without sending them to a display screen 
or printer. The concept of attribute currentness, however, is relevant only 
when you are drawing graphics to an output device. For example, the color or 
other attribute that is current when you define a primitive is the color in 
which the line is drawn. That color or other attribute might not be the color 
that is current when you you actually draw the primitive. This is described in 
Attribute Currentness. 

Many of the GPI queries that return current attribute values are invalid in 
retain mode because current attribute values have no effect when graphics are 
not sent to an output device. 


═══ 7.1.1.3. Draw-and-Retain Mode ═══

In draw-and-retain mode, graphics are both drawn on the current device as they 
are created and stored for later use. The GPI queries that return current 
attribute values are valid in draw-and-retain mode. 


═══ 7.1.2. Creating a Graphics Segment ═══

Your application signals the start of a graphics segment using GpiOpenSegment, 
which is valid only in a normal presentation space. The following figure is an 
example of two segments in a presentation space. 


                            Presentation Space
                          ┌─────────────────────────────────────┐
                          │                                     │
                          │   Graphics Segment 1                │
                          │   ┌────────────┐                    │
                          │   │            │                    │
GpiOpenSegment (hps,1L);  │   │            │                    │
GpiSet... (hps,...);    ──┼───┼──────     │                    │
GpiLine (hps,...);      ──┼───┼──         │                    │
GpiCloseSegment (hps);    │   │            │  Graphics Segment 2│
                          │   │            │  ┌────────────┐    │
                          │   │            │  │            │    │
                          │   └────────────┘  │            │    │
                          │                   │            │    │
GpiOpenSegment (hps,2L);  │                   │            │    │
GpiSet... (hps,...);    ──┼───────────────────┼─────      │    │
GpiLine (hps,...);      ──┼───────────────────┼──         │    │
GpiCloseSegment (hps);    │                   │            │    │
                          │                   └────────────┘    │
                          │                                     │
                          │                                     │
                          └─────────────────────────────────────┘

Graphics Segments in a Presentation Space 

GpiOpenSegment accepts, as input, the presentation space handle and a long 
integer value, which names each segment. 

OS/2 applications identify segments with long integer values. If you want to 
refer to the segment individually in later graphics operations (for example, to 
edit the segment) the identifier you supply must be greater than 0 and unique 
within the presentation space. 

If you do not want to refer to the segment individually after it is created, 
you can give the segment an identifier of 0. You might do this when you are 
creating nonretained segments, for example. Any number of segments can have the 
0 identifier. They are referred to throughout this book as zero segments. 

To determine which names already have been used in a presentation space, use 
GpiQuerySegmentNames. This function returns an array of segment names for all 
retained segments, excluding zero segments, within a specified name range. 

Segments do not have to be named in consecutive order (although it is 
recommended for organizational purposes) because the segment order can be 
changed using GpiSetSegmentPriority. 


═══ 7.1.3. Filling a Graphics Segment ═══

After a graphics segment is opened, the GPI functions that follow become a part 
of a retained segment and are executed every time the segment itself is drawn. 

The typical GPI functions that would be called are those that: 

     Create graphics primitives-such as lines or markers 
     Assign attributes to those primitives-such as color or line type. 

 However, there are a few GPI functions that you cannot call while there is an 
 open segment-for example a second GpiOpenSegment. These functions are 
 identified in GPI Function Context. 

 A presentation space can contain many segments. Each time you open a new 
 segment, many attributes reset themselves to default values. Therefore, the 
 current position and attribute values that apply before you call 
 GpiOpenSegment cannot be guaranteed to be in effect after you call the 
 function. Beginning each segment with a number of attribute-setting requests 
 and, possibly, with GpiSetCurrentPosition, is recommended. Your application 
 also might take advantage of GpiSetDefAttrs, for example, to minimize the 
 number of attributes that must be dealt with upon opening a new segment. 


═══ 7.1.4. Closing a Graphics Segment ═══

When you have finished creating a graphics segment, close it using 
GpiCloseSegment. There can be only one open segment at a time in a single 
graphics presentation space, so you must close one segment before going on to 
the next. 

There is some degree of clean-up processing associated with using 
GpiCloseSegment, known as close-segment processing, that can make current 
attribute values unreliable. For more information about the effects of 
GpiOpenSegment and GpiCloseSegment on current attributes, see Graphics 
Attributes. 


═══ 7.1.5. Segment Attributes ═══

Each segment, whether retained or nonretained, has a number of characteristics, 
called attributes that you can set in accordance with your application's 
requirements. The attributes of a segment are quite different from those of a 
graphics primitive in that segment attributes have ON and OFF settings. There 
are seven segment attributes. However, only two are described in this chapter: 
chained (ATTR_CHAINED) and fast-chained (ATTR_FASTCHAIN). 

When an application creates a segment in a presentation space, the operating 
system assigns initial attributes to it. By default, five of the attributes 
will be set ON and two will be set OFF. The chained and fast-chained attributes 
are set ON. Your application can alter these values using 
GpiSetInitialSegmentAttrs or retrieve the values of the current initial 
attributes using GpiQueryInitialSegmentAttrs. 

The chain attribute tells the operating system to add each new segment in your 
application's presentation space to the segment chain. The fast-chained 
attribute tells the operating system to prevent the resetting of the primitive 
attributes to their default values before drawing the segment chain. 


═══ 7.1.5.1. Chained Attribute ═══

When you define a segment with the chained attribute switched ON, that segment 
becomes a part of the segment chain and is called a chained segment. The 
segment chain is composed of all chained segments defined in a single 
presentation space. Segments can be chained together so that they can be drawn 
as a group. By default, each new segment is chained to the previous segment. 

There can be only one segment chain at a time in a single presentation space, 
and all chained segments are chained to each other in the order in which you 
created them. Zero segments must have the chained attribute. 

Usually, a logical relationship exists between the segments in a segment chain, 
although this is not a requirement. The whole segment chain can be drawn using 
GpiDrawChain. Each segment in the chain is called a root segment. Root segments 
are affected by those GPI functions that act on the segment chain, but they 
also can be manipulated independently of the chain. 

Segments that are defined with the chained attribute switched OFF are called 
unchained segments. Your application can switch off the chain attribute using 
GpiSetInitialSegmentAttrs (hps, ATTR_CHAIN, ATTR_OFF). Unchained segments 
always are retained when they are created, regardless of the current 
drawing-mode parameter. An unchained segment must have a unique name. 

There are a number of reasons for defining a segment as unchained. For example, 
a particular segment might not belong to the picture that is defined by the 
segment chain. You also are likely to define as unchained any segment that 
belongs to the picture but that has no single, fixed place in the segment 
chain. A car wheel, for example, could be defined once but drawn four times in 
a picture of a car. It would have no single, fixed place in the segment chain, 
but would be included four times in the picture by being called from one or 
more root segments. 

A segment is called from another segment by including GpiCallSegmentMatrix in 
the calling segment. A segment and the segments it calls logically are one 
object. An important point about called segments is that they assume the 
primitive attribute settings of the calling segment. Of course, you can change 
the attribute settings within the called segment if the inherited values are 
inappropriate. 

A closed, unchained segment can be called from any other segment. Chained 
segments, however, cannot be called from other segments. 


═══ 7.1.5.2. Fast-Chained Attribute ═══

The fast-chained attribute applies only to chained segments. It prevents 
primitive attributes from being reset to their default values at the beginning 
of the segment, an aid to performance. There is unnecessary overhead in 
resetting attributes to their defaults if either of the following is true: 

     You are going to change the default values of the attributes at the start 
      of the segment. 

     You know that attributes have not been altered previously from their 
      default values. 

 The fast-chained attribute is switched ON by default, and you should leave it 
 on unless you specifically want attributes to be set to their default values. 
 To turn off the fast-chained attribute, call GpiSetInitialSegmentAttrs (hps, 
 ATTR_FASTCHAIN, ATTR_OFF). 


═══ 7.1.6. Actual Drawing Mode ═══

The drawing mode, as defined by GpiSetDrawingMode, works in conjunction with 
the segment status to produce the actual drawing mode. It is the actual drawing 
mode that determines whether graphics are: 

     Drawn directly to the output device 
     Retained in the segment store 
     Both drawn and retained 

 The actual drawing mode is summarized in the following table. 

 The Current Drawing Mode 

  ┌─────────────────┬───────────────┬──────────────┬──────────────┐
  │                 │               │Context       │              │
  ├─────────────────┼───────────────┼──────────────┼──────────────┤
  │GpiSetDrawingMode│Chained Segment│Unchained     │Outside of any│
  │parameter        │               │Segment       │segment       │
  ├─────────────────┼───────────────┼──────────────┼──────────────┤
  │DM_DRAWANDRETAIN │draw-and-retain│retain        │draw          │
  ├─────────────────┼───────────────┼──────────────┼──────────────┤
  │DM_RETAIN        │retain         │retain        │draw          │
  ├─────────────────┼───────────────┼──────────────┼──────────────┤
  │DM_DRAW          │draw           │retain        │draw          │
  └─────────────────┴───────────────┴──────────────┴──────────────┘

 As you can see in the preceding table, graphics within chained segments always 
 conform to the current drawing mode parameter. That is, they are drawn in 
 DM_DRAW mode, retained in DM_RETAIN mode, and both drawn and retained in 
 DM_DRAWANDRETAIN mode. 

 Graphics in unchained segments always are retained, regardless of the current 
 drawing-mode parameter. You cannot retain segments created when the current 
 drawing-mode parameter is DM_DRAW, unless they are unchained segments. 

 Similarly, graphics outside segments always are drawn without being retained. 
 You cannot retain primitives outside segments, regardless of the current 
 drawing mode. 

 Note:  A micro presentation space has no segment store. Therefore, you cannot 
 create graphics segments in a micro presentation space, nor can you change the 
 drawing mode, which is always DM_DRAW. 


═══ 7.1.7. Drawing a Retained Graphic ═══

Your application can draw a complete segment chain with GpiDrawChain. The 
segments are drawn in the order in which they appear in the chain. For example, 
the segments in the following figure are drawn in the following order: 

   1. Root segment 1 
   2. Unchained segment A 
   3. Unchained segment B 
   4. Root segment 2 
   5. Unchained segment B 
   6. Root segment 3. 

 Chained and Called Segments 

 Segment A is called by root segment 1, and segment B is called by both segment 
 A and root segment 2. Segment C calls segment D. Both C and D are unchained 
 segments that are not called from the segment chain, and consequently, are not 
 part of the segment chain. 

 GpiSetSegmentPriority changes the position of a root segment (which must not 
 be a zero segment) in the chain. As input to this function, you supply the 
 name of the segment you want to reorder and the name of a reference segment. 
 The reference segment is the segment that either will be immediately before, 
 or immediately after, the reordered segment's new position in the chain. 

 If the segment you are moving is to come after the reference segment in the 
 chain, it is said to have a higher priority (HIGHER_PRI). If it is to come 
 before the reference segment, it is said to have a lower priority (LOWER_PRI). 
 The nearer a segment is to the end of the chain, the higher its priority. 

 If you supply the name of an unchained segment as input to 
 GpiSetSegmentPriority, the segment is added to the chain in the position you 
 specify. To learn the position of a segment in the chain, use 
 GpiQuerySegmentPriority. 

 If your application called the following functions: 

  GpiSetSegmentPriority (hps, C, 2, LOWER_PRI)
  GpiSetSegmentPriority (hps, 3, 0, HIGHER_PRI)
  GpiSetSegmentPriority (hps, B, 0, LOWER_PRI)
 the segment chain in the previous figure would appear as in the following 
 figure; and GpiDrawChain would draw the segments in the following order: 

   1. Root segment 3 
   2. Root segment 1 
   3. Unchained segment A 
   4. Unchained segment B 
   5. Segment C 
   6. Unchained segment D. 
   7. Root segment 2 
   8. Unchained segment B. 
   9. Segment B 

 Chained and Called Segments Reordered Using GpiSetSegmentPriority 


═══ 7.1.7.1. Segment Priority ═══

The priority of a segment, in conjunction with the current foreground and 
background mix attributes, affects how the picture is presented to the user. 
The segment with the highest priority is drawn last, and appears on top of the 
previously drawn primitives. Picture components in segments with low priorities 
risk being drawn over and never seen by the user. The mix attributes affect the 
graphics functions within each segment. 


═══ 7.1.7.2. GpiDrawSegment ═══

GpiDrawSegment accepts as input any segment name greater than zero. 
GpiDrawSegment can draw individual segments both inside and outside the segment 
chain. Any segment that is called from the GpiDrawSegment-named segment also is 
drawn. 


═══ 7.1.7.3. GpiDrawFrom ═══

You can draw a smaller portion of the entire segment chain (but a larger 
portion than a single segment) using GpiDrawFrom. GpiDrawFrom, as input, a 
presentation space handle and two nonzero segment names, the first of which 
must be part of the segment chain. GpiDrawFrom then draws the segments, 
starting with the first and ending with the last, including all chained and 
called segments. 


═══ 7.1.8. Attribute Modes ═══

You can change primitive-attribute settings at any time. The new values you 
specify replace the existing values. For example, if the current foreground 
color is green and you change it to red, red replaces green as the foreground 
color attribute. 

When you set primitive attributes within a retained or nonretained segment, you 
can save the existing attribute values on a last-in-first-out (LIFO) stack, 
from where they can later be retrieved and made current again. You do this by 
selecting either of the two attribute modes: 

     AM_PRESERVE mode-Also known as push-and-set mode 
     AM_NOPRESERVE mode-Also known as set mode. 

 In AM_NOPRESERVE mode, which is the default setting, existing attribute values 
 are replaced by any new attribute values that you supply. In AM_PRESERVE mode, 
 the existing attribute values are stored on a LIFO stack, and then the new 
 values that you specify take effect. AM_PRESERVE mode also causes the current 
 position to be saved if the position was specified using 
 GpiSetCurrentPosition. If you use GpiMove to set the current position, the 
 position is not saved, regardless of the attribute mode. 

 To select a current attribute mode, use GpiSetAttrMode. The current attribute 
 mode affects subsequent attribute-setting requests in the presentation space. 
 Attribute modes are not applicable to micro presentation spaces, because 
 graphics segments can be created only in normal presentation spaces. 

 To retrieve an attribute value from the LIFO stack, use GpiPop, which pulls 
 back the attribute that was stored most recently on the stack. You can 
 retrieve more than one attribute value by supplying a number as an input 
 parameter of this function. For example, if you specify 4, GpiPop retrieves 
 the four attributes that were most recently stored on the stack. If each of 
 the values retrieved applies the same type of attribute to the same primitive 
 (for example, if all four are line-type settings), the last one to be 
 retrieved (and, therefore, the first one on the stack) becomes the current 
 setting. 

 If you save attribute values from any segment called from another segment, and 
 do not retrieve the values using GpiPop, the values are restored automatically 
 when the end of the segment is reached. If you save attribute values from any 
 segment that is not called from another segment and do not explicitly restore 
 those values using GpiPop, they are lost at the end of the segment. 

 The AM_PRESERVE mode is useful when you do not want attributes in calling 
 segments to be overwritten by attributes specified in the called segments. 
 This overwriting happens because a calling segment and the segments it calls 
 are logically one object. Attribute changes within a called segment remain 
 current upon return to the calling segment. If you set some attribute values 
 at the start of a called segment, and the current attribute mode is 
 AM_PRESERVE, the attribute values of the calling segment are stored on the 
 LIFO stack. At the end of the called segment, the values on the stack are 
 retrieved automatically so that the calling segment continues with its own 
 attribute values. 


═══ 7.1.9. Reusing the Presentation Space ═══

A normal presentation space with segments retained in the segment store can be 
costly in terms of storage. Therefore, delete any presentation space that you 
no longer need, using GpiDestroyPS. If, for example, your application is using 
a series of presentation spaces, each with a different format, the creation and 
deletion activity also can be costly. The PM provides the following functions 
that let you reuse or redefine an existing presentation space so you can create 
a presentation space once and use it any number of times. 

     GpiSavePS 
     GpiRestorePS 
     GpiResetPS 
     GpiSetPS 


═══ 7.1.9.1. GpiSavePS ═══

GpiSavePS saves presentation space information (such as current primitive 
attributes and the current position) on a dedicated LIFO stack. The 
presentation space itself is unchanged; that is, it still exists, has the same 
presentation space handle, and the presentation page dimensions and format are 
the same. 

Output from GpiSavePS is a number that identifies the saved information on the 
LIFO stack. An output of 3, for example, tells you that this is the third lot 
of presentation space data on the stack. 


═══ 7.1.9.2. GpiRestorePS ═══

GpiRestorePS retrieves the saved information from the LIFO stack and reapplies 
it to the presentation space. Input to this function can be either the 
identifier returned to you from GpiSavePS or a relative value. A relative value 
of -1, for example, retrieves the information most recently stored on the 
stack. You do not have to restore the information that was most recently saved. 
However, any data that you skip over is discarded. 

A LIFO Stack with Four Items 


═══ 7.1.9.3. GpiResetPS ═══

When a presentation space is first created, it is in a neutral state. Current 
attributes are set to their initial default values. The current position is 
(0,0). The segment store contains no segments, and there are no 
application-defined resources, such as logical color tables. 

You can return an existing presentation space to this state using GpiResetPS. 
GpiResetPS has three levels of reset activity, each more powerful than the 
last. These are: 

   1. GRES_ATTRS, which is equivalent to the processing done by 
      GpiCloseSegment. 

   2. GRES_SEGMENTS, which is equivalent to creating a new presentation space, 
      but without deleting any logical resources. All retained segments are 
      deleted from the segment store. 

   3. GRES_ALL, which is equivalent to creating a new presentation space. 

 GpiResetPS does not alter the size or format of the presentation page. 


═══ 7.1.9.4. GpiSetPS ═══

GpiSetPS redefines the size and format of the presentation page. The processing 
performed when you call GpiSetPS is similar to that performed by GpiCreatePS, 
except that the presentation space already exists. The presentation space is 
returned to a neutral state (which is the equivalent of requesting GRES_ALL 
using GpiResetPS), and the presentation page is redefined. For example, you can 
change a presentation page defined in 0.01mm units to one defined in pels. 
Essentially, this lets you work with a new presentation space without having to 
delete one and create another. 

You also can use GpiSetPS to change the current mapping mode of a presentation 
space. To do this, use the PS_NORESET flag, which is the equivalent of 
requesting GRES_SEGMENTS using GpiResetPS. This feature is particularly useful 
if you are designing an application that deals with page layout and drafting, 
or if you want the screen size to correspond to the page size for the printed 
output. 


═══ 7.1.10. Nonretained Graphic Segments ═══

It is valid segment construction to create a segment bracket while the drawing 
mode is DM_DRAW. The GPI functions contained within the bracket are drawn 
immediately rather than being retained for future use. This type of segment is 
called a nonretained segment. 

Because the usual reason for constructing segments is to take advantage of 
retained graphics, nonretained segments might appear as a contradiction in 
terms at first. However, there are four particular advantages in their use: 

     If ATTR_FASTCHAIN is set to OFF, the GpiOpenSegment implicitly resets all 
      attributes to their defaults. 

     The GpiOpenSegment and GpiCloseSegment initialize and reset the viewing 
      transform matrix, just as they do for retained segments. 

     Nonretained segments can be recorded in a metafile, just as a retained 
      segment can. 

     A graphic in a nonretained segment, with a unique name, can be converted 
      easily to a retained graphic for future use. 


═══ 7.2. Using Segment Creating and Drawing Functions ═══

You can use retained-drawing and segment functions to: 

     Create a chained or called segment 
     Draw the picture associated with one or more segments 


═══ 7.2.1. Creating a Chained Segment ═══

To create a chained segment, you must: 

   1. Set the drawing mode to DM_RETAIN. 

   2. Check to see if the chained attribute is one of the initial segment 
      attributes using GpiQueryInitialSegmentAttrs. 

   3. Set the chained attribute, if necessary, with GpiSetInitialSegmentAttrs. 

   4. Open the segment using GpiOpenSegment. 

   5. Perform the necessary drawing operations. 

   6. Close the segment using GpiCloseSegment. 

 The following figure is an example of a segment containing a box primitive and 
 calling another segment using GpiCallSegmentMatrix. 

  #define INCL_GPISEGMENTS
  #define INCL_GPITRANSFORMS
  #include <os2.h>
  void fncSEGS01(void){
      POINTL ptl;
      HPS hps;
      LONG idSegment    = 1;
      LONG idNonChained = 2;
      MATRIXLF matlfTransform = { MAKEFIXED(2,0), MAKEFIXED(0,0), 0,
                                  MAKEFIXED(0,0), MAKEFIXED(1,0), 0,
                                  0, 0, 1 };

      /************************************************************************/
      /* Turns chaining on. Adds the new segment to the segment chain.        */
      /* Segment idNonChained is called, whether chained or not.              */
      /************************************************************************/

      if (ATTR_OFF == GpiQueryInitialSegmentAttrs(hps, ATTR_CHAINED)
          GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_ON);
      GpiOpenSegment(hps, idSegment);
      ptl.x = 150; ptl.y = 150;
      GpiMove(hps, &ptl);
      ptl.x = 225; ptl.y = 225;
      GpiBox(hps, DRO_FILL, &ptl, 0L, 0L);
      GpiCallSegmentMatrix(hps, idNonChained, 9L, &matlfTransform,
          TRANSFORM_REPLACE);
      GpiCloseSegment(hps);
  } /* fncSEGS01 */


═══ 7.2.2. Creating a Called Segment ═══

To create a called segment, you must: 

   1. Set the drawing mode to DM_RETAIN. 

   2. Check to see whether the chained attribute is one of the initial segment 
      attributes using GpiQueryInitialSegmentAttrs. 

   3. Set the chained attribute, if necessary, with GpiSetInitialSegmentAttrs. 

   4. Open the segment using GpiOpenSegment. 

   5. Perform the necessary drawing operations. 

   6. Close the segment using GpiCloseSegment. 

 The following figure shows an example of how to draw a box in a called 
 segment. 

  #define INCL_GPISEGMENTS
  #define INCL_GPICONTROL
  #include <os2.h>
  void fncSEGS02(void){
      POINTL ptl;
      HPS hps;
      LONG idNonChained = 2;

      GpiSetDrawingMode(hps, DM_RETAIN);

      /* Creates a non-chained segment. */

      if (ATTR_ON == GpiQueryInitialSegmentAttrs(hps, ATTR_CHAINED))
          GpiSetInitialSegmentAttrs(hps, ATTR_CHAINED, ATTR_OFF);
      GpiOpenSegment(hps, idNonChained);
      ptl.x = 100;
      ptl.y = 100;
      GpiMove(hps, &ptl);
      ptl.x = 200;
      ptl.y = 200;
      GpiLine(hps, &ptl);
      GpiCloseSegment(hps);
  } /* fncSEGS02 */


═══ 7.2.3. Drawing a Segment Chain ═══

The following figure shows an example of how to draw a segment chain using 
GpiDrawChain. 

#define INCL_GPICONTROL
#include <os2.h>
void fncSEGS03(void){
    HPS hps;

    if (DM_DRAW != GpiQueryDrawingMode(hps))
        GpiSetDrawingMode(hps, DM_DRAW);
    GpiDrawChain(hps);
} /* fncSEGS03 */


═══ 8. Character String Primitives ═══

Character string primitives are printed or displayed text limited to a length 
of 256 characters by the PM. 

The following topics are related to information in this chapter: 

     Presentation spaces and device contexts 
     Color and mix attributes 
     Fonts 
     Coordinate spaces and transformations 


═══ 8.1. About Character String Primitives ═══

A PM application must make certain choices about fonts in preparation for text 
display or printing. Often these choices are driven by selections from a user. 
After the selections are made, as discussed in Fonts, the application can make 
additional decisions about the appearance of the individual characters within 
the font by setting attributes in the CHARBUNDLE data structure. CHARBUNDLE is 
the lowest of three levels of data structures that define the appearance of 
displayed or printed text. The other two, FONTMETRICS and FATTRS, are described 
in Fonts. 

A font family-for instance, Helvetica** or Courier-is a collection of fonts. 
Fonts within the same family share certain attributes such as stroke width and 
serif characteristics. Stroke width refers to the width of lines used to draw 
characters and symbols from a font. A serif is a short crossline drawn at the 
ends of the main strokes that form a character or symbol. 

Individual fonts within a family differ from each other in the following ways: 

     Height 
     Line weight 
     Appearance 

 Height refers to the point size of a font. A common example of line weight is 
 boldface. A common example of appearance is italic. 

 The most important factor that affects the CHARBUNDLE attributes is whether 
 the current font is an image or an outline font. The following figure shows an 
 example of the difference. 

 Image and Outline Fonts 

 Outline fonts are composed of characters drawn with straight and curved lines. 
 Image fonts, also called bit map fonts, are composed of pels arranged in 
 certain shapes. 


═══ 8.1.1. Attributes of Character String Primitives ═══

Attributes of the character string primitives contained in CHARBUNDLE are as 
follows: 

     Character set 
     Character mode 
     Character cell 
     Character angle 
     Character shear 
     Character direction 
     Character text alignment 
     Character extra 
     Character break extra 
     Foreground color 
     Background color 
     Foreground mix 
     Background mix 

 When an application creates a presentation space, the character string 
 attributes are set to the default values shown in the following table. 

 Character String Attribute Default Values 

  ┌────────────┬────────────────────────┬──────────────────────────────────┐
  │Attribute   │Default Value           │Function that Redefines Attribute │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Set         │LCID_DEFAULT            │GpiSetCharSet                     │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Mode        │CM_MODE1                │GpiSetCharMode                    │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Cell        │Outline font - Defined  │GpiSetCharBox                     │
  │            │by device               │                                  │
  │            │Image font - Defined by │                                  │
  │            │font                    │                                  │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Angle       │(1,0)                   │GpiSetCharAngle                   │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Shear       │(0,1)                   │GpiSetCharShear                   │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Direction   │Left to right           │GpiSetCharDirection               │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Text        │Left                    │GpiSetTextAlignment               │
  │alignment   │                        │                                  │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Extra       │0                       │GpiSetCharExtra                   │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Break extra │0                       │GpiSetCharBreakExtra              │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Foreground  │Black                   │GpiSetAttrs(CBB_COLOR)            │
  │color       │                        │                                  │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Background  │Clear                   │GpiSetAttrs(CBB_BACK_COLOR)       │
  │color       │                        │                                  │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Foreground  │Overpaint               │GpiSetAttrs(CBB_MIX_MODE)         │
  │mix         │                        │                                  │
  ├────────────┼────────────────────────┼──────────────────────────────────┤
  │Background  │Leave alone             │GpiSetAttrs(CBB_BACK_MIX_MODE)    │
  │mix         │                        │                                  │
  └────────────┴────────────────────────┴──────────────────────────────────┘

 Current character attributes take effect when you send graphics characters to 
 an output device. They have no effect at the time you define a logical font. 


═══ 8.1.1.1. Character Set ═══

Character set defines the local identifier, lcid, of the current font. The font 
lcid is set using GpiSetCharSet. GpiCreateLogFont associates the font with an 
lcid. 

The value of the current lcid is determined using GpiQueryCharSet. 


═══ 8.1.1.2. Character Mode ═══

Every presentation space has a current character mode, which determines the 
extent to which a font can be affected by the attributes defined in CHARBUNDLE. 
The mode affects compatibility issues that are invisible to both the user and 
the programmer. The following table describes the character modes and their 
influences on the current font. 

An application selects a character mode using GpiSetCharMode. When a mode is 
selected, it applies to any font (including the system font) used while the 
mode is current. The character mode takes effect when you draw character 
strings; it has no effect at the time you define a logical font. 

Character Mode Effects on Character Attributes 

┌──────────┬────────────────────────────┬──────────────────────┐
│Character │If Image Font...            │If Outline Font...    │
│Mode      │                            │                      │
├──────────┼────────────────────────────┼──────────────────────┤
│CM_MODE1  │Ignores all current         │Affected by all       │
│          │character attributes, except│current character     │
│          │character direction.        │attributes.           │
├──────────┼────────────────────────────┼──────────────────────┤
│CM_MODE2  │Uses the character shear,   │Affected by all       │
│          │box, angle, and direction   │current character     │
│          │attributes to position the  │attributes.           │
│          │character cell, but the     │                      │
│          │characters themselves are   │                      │
│          │not sheared, rotated,       │                      │
│          │scaled, or reversed.        │                      │
├──────────┼────────────────────────────┼──────────────────────┤
│CM_MODE3  │Raises an error if you try  │Affected by all       │
│          │to draw a character string. │current character     │
│          │Note:  Any font used when   │attributes.           │
│          │the current character mode  │                      │
│          │is CM_MODE3 must be an      │                      │
│          │outline font.               │                      │
└──────────┴────────────────────────────┴──────────────────────┘

The default character mode (CM_DEFAULT) is identical to CM_MODE1. 


═══ 8.1.1.3. Character Cell ═══

A character cell is an imaginary rectangular boundary that defines the 
horizontal and vertical space occupied by a single character from an outline 
character set. 

The PM calculates character cell width and height from the point size. The 
width value for the character cell is the nominal width of the lowercase 
characters in the character set. In a monospace font, the width of all 
character cells is identical. In a proportional font, the width of the 
character cells depends on the character. 

In an image font, the height of the character cell is the number of pels in the 
font. In an outline font, the height of the character cell is the point size of 
the font. 

The characters in a character string are positioned one character per cell. The 
spacing between adjacent characters in a string is affected by the character 
cell attribute, except for image characters in CM_MODE1. 

Cell width determines the spacing of consecutive characters along the baseline, 
as illustrated in the following figure. 

Character Cell Measurements 

Current cell size is specified using GpiSetCharBox. As input, this function 
accepts the desired height and width of the character cell in world 
coordinates. These values are related to certain dimensions in the FONTMETRICS 
structure that controls font attributes. Heights or widths of 0 are valid input 
and cause the outline character to be drawn as a point or straight line. 
Heights or widths of negative values cause certain special effects, for 
example, reversed lettering. 

The character cell value affects both the size and position of characters drawn 
from an outline font, regardless of the current character mode. Each character 
is scaled up or down to fit the cell size, as shown in the following figure. 

Effect of the Character Cell on an Outline Font 

The character cell value is ignored if the current font is an image font and 
the current character mode is CM_MODE1, as shown in the following figure. 

Note:  It is essential to code the character cell correctly, even if you 
anticipate using image fonts. In case of a font match failure, an outline font 
can be substituted for a image font. 

Effect of the Character Cell on an Image Font in CM_MODE1 

Although the character cell has been both increased and decreased, the 
character string is unaltered. 

The character cell value controls the positioning of image-font characters when 
the current character mode is CM_MODE2; but it cannot cause the characters to 
be scaled to fit the cell. This effect is shown in the following figure. 

Effect of the Character Cell on an Image Font in CM_MODE2 

If you increase the character cell size for an image font in CM_MODE2, the 
characters are more widely spaced, but their size is not changed. If you 
decrease character cell size, the space between the characters is reduced, and 
because the characters themselves cannot be scaled, they can overlap. 


═══ 8.1.1.3.1. Default Character Cell ═══

The default character-cell size is a device-dependent value. You do not need to 
know this value unless you want to switch back to the initial default value 
after having specified another value. It is recommended that you save initial 
default values using GpiSavePS. 

The default character cell, like other default attributes, can be set using 
GpiSetDefAttrs(CBB_BOX). If necessary, you can query the current default value 
using GpiQueryDefAttrs. 


═══ 8.1.1.3.2. Coding a Character Cell ═══

The dimensions that an application passes to GpiSetCharBox and that 
GpiQueryCharBox returns are fixed-point values. A fixed value is a 32-bit value 
whose high-order 16 bits contain the integral part of the floating-point number 
and whose low-order 16 bits contain the fractional part. The fractional part is 
the numerator of a fraction whose denominator is fixed at 65536. The MAKEFIXED 
macro provides a method for producing fixed values. If, for example, one of the 
character cell dimensions were 7.635 world units, an application could obtain 
the corresponding fixed value by using the MAKEFIXED macro, passing 7 as the 
first argument and 41615 as the second. 

The purpose of the character cell is to assist other font metrics to define 
text lines. For example, if you planned to have an average text line of 60 
characters, dividing your output width by 60 would provide your character cell 
width. 

DevQueryCaps can be used to provide information about suitable character cell 
values. DevQueryCaps returns two sets of values that can influence the 
character cell: 

     Default cell values 
        -  CAPS_GRAPHICS_CHAR_WIDTH 
        -  CAPS_GRAPHICS_CHAR_HEIGHT. 
     Device resolution 
        -  CAPS_HORIZONTAL_FONT_RES 
        -  CAPS_VERTICAL_FONT_RES. 

 The default cell values return the size of the default character cell in pels. 
 Convert the device resolution into character cell values by multiplying it by 
 the desired point size, then dividing by 72 (72.2818). 


═══ 8.1.1.4. Character Angle ═══

The character angle is defined by the x-axis and a vector drawn through the 
origin to a specified point in a Cartesian coordinate system. Neither (0,0) nor 
the specified point need have any relation to the current position. The 
operating system then aligns the baseline with this vector. 

An application can retrieve the point that defines the character angle vector 
using GpiQueryCharAngle. An application can set the character angle using 
GpiSetCharAngle. This function accepts as input the x- and y-coordinates of a 
point that defines the new vector. When you specify an angle, it becomes the 
current setting. To reset the character angle vector to its default value 
(parallel to the x-axis), call GpiSetCharAngle with both x and y equal to 0. 

The effects of the current character angle vary depending on the current 
character mode and the current font type. When the current font is an outline 
font, the current character angle determines the angle of both the whole string 
and the individual characters in the string, regardless of the current 
character mode. The baseline of each character cell is drawn parallel to the 
new baseline, as shown in the following figure. 

Effect of the Character Angle on an Outline Font 

The character string is drawn parallel to the vector drawn from the origin to 
(10,7). The baseline of each of the character cells also is drawn parallel to 
this vector. 

The character angle value is ignored if the current font is an image font and 
the current character mode is CM_MODE1, as shown in the following figure. 

Effect of the Character Angle on an Image Font in CM_MODE1 

The angle of the character string is unaltered by GpiSetCharAngle. 

When the current font is an image font and the current character mode is 
CM_MODE2, the current character angle determines the angle of the whole string 
but does not affect the individual characters in the string. The character 
reference point, which is the point at which the character baseline intersects 
the left edge of the character cell, is placed on a line parallel to the new 
baseline. The baseline of each character cell remains parallel to the x-axis, 
as shown in the following figure. 

Effect of the Character Angle on an Image Font in CM_MODE2 

The character string is drawn parallel to the vector from (0,0) to (10,7). 

Each of the characters in the string in the previous figure is drawn with the 
vertical sides of its character cell parallel to the y-axis, and with the 
horizontal sides of its character box parallel to the x-axis. 


═══ 8.1.1.5. Character Shear ═══

Character shear is the angle defined by the x-axis and a vector drawn through 
the origin to a specified point in a Cartesian coordinate system. Neither (0,0) 
nor the specified point need have any relation to the current position. The 
operating system then aligns the vertical sides of the character cell. If the 
font is an outline font, the operating system also aligns the vertical strokes 
of the characters with the vector, regardless of the current character mode, as 
shown in the following figure. 

An application can retrieve the point that defines the character shear vector 
using GpiQueryCharShear. An application can set the character shear using 
GpiSetCharShear, which accepts as input the x- and y-coordinates of a point 
that defines the new vector in a POINTL structure. 

The shear of a character is the angle formed by the vertical lines of the 
character cell, and it can affect both the positioning and shape of characters 
in the character string. By default, the vertical lines of a character cell are 
parallel to the y-axis of the presentation page. As input to GpiSetCharShear 
supply the coordinates of the end point of a vector drawn from the origin 
(0,0). The effects of the current character shear value vary, depending on the 
current character mode and font type. 

Effect of Character Shear on an Outline Font 

The character cell is drawn with its vertical lines parallel to the vector from 
the origin to (5,6). The character is sheared to the same degree. 

The character-shear value is ignored if the current font is an image font and 
the current character mode is CM_MODE1, as shown in the following figure. 

Effect of Character Shear on an Image Font in CM_MODE1 

The character string is unaffected by the character-shear value. 

The character-shear value affects the positioning of the characters from an 
image font in CM_MODE2 only if character direction is CHDIRN_TOPBOTTOM or 
CHDIRN_BOTTOMTOP. That is, characters drawn vertically do not appear in a 
vertical line for nonzero shear angle from the vertical. The characters 
themselves cannot be sheared, as shown in the following figure. 

Effect of Character Shear on an Image Font in CM_MODE2 

The character cell is sheared, and it controls the positioning of the 
characters; the characters themselves are unchanged. 

If the x- and y-coordinate values you specify in GpiSetCharShear are both 
positive and negative, the characters slant from lower left to upper right. If 
you supply one negative and one positive value, the characters slant from upper 
left to lower right, as illustrated in the following figure. 

Effect of X- and Y-Values on Character Shear 

Character shear, like other attributes, has a default value that can be changed 
using GpiSetDefAttrs (CBB_SHEAR). To reset the character shear to its default 
effect of drawing the vertical lines of the character cell parallel to the 
y-axis, supply a coordinate value of (0,1) on GpiSetCharShear. 


═══ 8.1.1.6. Character Direction ═══

Character direction is the direction in which the characters in a string are 
drawn in relation to the baseline. By default, the characters are drawn from 
left to right. An application can change the direction using 
GpiSetCharDirection. GpiSetCharDirection accepts as input one of the four 
values illustrated in the following figure. The value CHDIRN_DEFAULT is 
identical to CHDIRN_LEFTRIGHT. 


┌───┬───┬───┐            ┌───┬───┬───┐
│ A │ B │ C │            │ C │ B │ A │
└───┴───┴───┘            └───┴───┴───┘
                                  
start       end          end         start

CHDIRN_LEFTRIGHT         CHDIRN_RIGHTLEFT


start                    end
                          
┌───┐                    ┌───┐
│ A │                    │ C │
├───┤                    ├───┤
│ B │                    │ B │
├───┤                    ├───┤
│ C │                    │ A │
└───┘                    └───┘
                          
end                      start

CHDIRN_TOPBOTTOM         CHDIRN_BOTTOMTOP

An application can determine the current character direction using 
GpiQueryCharDirection. 


═══ 8.1.1.7. Character Text Alignment ═══

Character text alignment is the attribute that describes how the character 
strings are drawn with respect to the boundary of the output, either the 
current position or the starting position of the string, if a 
GpiCharString...At function draws the string. The alignment is set using 
GpiSetTextAlignment, which accepts as input a long value for horizontal and 
vertical alignment. 

The acceptable values for GpiSetTextAlignment depend on the direction of the 
current coordinate system, as follows: 

 Value          Corresponds to the direction of... 

 Left           The lowest x-coordinate value 

 Right          The highest x-coordinate value 

 Top            The highest y-coordinate value 

 Bottom         The lowest y-coordinate value 

 Internally, the PM determines a reference point within a character string that 
 is to be positioned over the starting point specified for the string. 

 If an application draws the string with either GpiCharString or 
 GpiCharStringPos, the starting point specified for the string is the current 
 position. If the application draws the string with either GpiCharStringAt or 
 GpiCharStringPosAt, the starting point specified for the string is accepted as 
 input by the function. 


═══ 8.1.1.7.1. Horizontal Alignment of a Character String ═══

When a horizontal character string does not fill the width of the output area, 
it can be positioned in one of the three ways shown in the following figure. 
All of these options can be set directly with the lHorizontal option of 
GpiSetTextAlignment. 

Horizontal Positioning of Text Strings 

Text justification requires an application to perform both queries and 
coordinate calculations. The following flags are used to specify types of 
horizontal alignment: 

Horizontal Alignment Values 

┌────────────────────────┬────────────────────────────────────┐
│Identifier              │Alignment                           │
├────────────────────────┼────────────────────────────────────┤
│TA_LEFT                 │On the left edge of the leftmost    │
│                        │character in the string             │
├────────────────────────┼────────────────────────────────────┤
│TA_RIGHT                │On the right edge of the rightmost  │
│                        │character in the string             │
├────────────────────────┼────────────────────────────────────┤
│TA_CENTER               │On the arithmetic mean of the       │
│                        │leftmost and rightmost characters in│
│                        │the string                          │
└────────────────────────┴────────────────────────────────────┘

There are two sets of default values for the lHorizontal option. They are 
provided for compatibility and map into the horizontal alignment values 
described above. 

GpiQueryGraphicsField, GpiQueryPageViewport, and GpiQueryViewingLimits all 
provide methods of determining the width of the output area so your application 
can specify coordinates properly for the current position. 


═══ 8.1.1.7.2. Vertical Alignment of a Character String ═══

When a character string is to be displayed vertically, it can be positioned in 
one of the four ways illustrated in the following figure. The vertical options 
all can be set directly using the lVertical option of GpiSetTextAlignment. 

Vertical Positioning of Text Strings 

The following flags are used to specify types of vertical alignment: 

Vertical Alignment Values 

┌────────────────────────┬────────────────────────────────────┐
│Identifier              │Alignment                           │
├────────────────────────┼────────────────────────────────────┤
│TA_TOP                  │On the top edge of the topmost      │
│                        │character in the string             │
├────────────────────────┼────────────────────────────────────┤
│TA_HALF                 │On the arithmetic mean of the       │
│                        │topmost and bottommost characters in│
│                        │the string                          │
├────────────────────────┼────────────────────────────────────┤
│TA_BASE                 │On the baseline of the bottommost   │
│                        │character in the string             │
├────────────────────────┼────────────────────────────────────┤
│TA_BOTTOM               │On the bottom edge of the bottommost│
│                        │character in the string             │
└────────────────────────┴────────────────────────────────────┘

There are two sets of default values for the lVertical option. They are 
provided for compatibility and map into the vertical alignment values described 
above. 


═══ 8.1.1.8. Character Extra and Break Extra ═══

Certain output devices permit you to specify extra space between character 
cells by using the character extra attribute. Sometimes the space between words 
can also be expanded by increasing the size of the break character, usually 
defined as the space character, by using the break extra attribute. If this 
adjustment to either attribute is permitted, the result will be in addition to 
the sizing effects caused by the following parameters: 

     Font kerning 
     Font proportional spacing 
     Width vectors 

 The break values you can specify create different effects, as follows: 

 Break Values and Their Effects 

  ┌────────────────────┬────────────────────────────────────────┐
  │Value               │Effect                                  │
  ├────────────────────┼────────────────────────────────────────┤
  │Positive            │Forces characters apart.                │
  ├────────────────────┼────────────────────────────────────────┤
  │0                   │Resumes the default spacing created by  │
  │                    │other parameters.                       │
  ├────────────────────┼────────────────────────────────────────┤
  │Negative            │Forces characters together, even        │
  │                    │overlapped characters.                  │
  └────────────────────┴────────────────────────────────────────┘

 These effects are illustrated in the following figure. 

 The Cumulative Effect of Break Values 

 The above are fixed integer values specified in world coordinates. Both the 
 character extra and break extra attributes have initial default values of 0, 
 which can be changed using GpiSetDefAttrs (CBB_EXTRA) and (CBB_BREAK_EXTRA). 
 These values can be changed using GpiSetCharExtra or GpiSetCharBreakExtra 
 respectively, and the values can be queried using GpiQueryCharExtra and 
 GpiQueryCharBreakExtra. 


═══ 8.1.1.9. Character Color and Mix ═══

The color attribute defines the color used to draw a primitive or an object. 
The mix attribute determines how the color of a primitive or an object is 
combined with the color of the drawing surface or any other objects on the 
surface. 

The character-string color defines the color used to draw the output from any 
of the draw-character-string functions. When a presentation space is created, 
the character-string color default is black. Character strings are one of the 
primitives that have both a foreground and a background color, as shown in the 
following figure. 

For image characters, colors are determined by setting pels. For outline 
characters, the foreground consists of arcs and lines that define the 
character; the background color appears between the foreground lines. The 
character can be solid or filled, in which cases the background color does not 
appear between the foreground lines. 

Character string primitives have a color attribute for both the actual 
character and its character cell, which surrounds the character. The 
character-cell color is the background color. 

The foreground mix attribute controls the combination of character-string color 
and drawing-surface color, while the background mix attribute controls the 
combination of the character-cell color and the drawing-surface color, as 
illustrated in the following figure. 

Character String Primitives 

When a presentation space is created, the character string mix attribute 
default is FM_OVERPAINT. The overpaint mix attribute specifies that the 
character-string color is not to be modified by the color of the drawing 
surface. If the character string mix attribute is changed, the character-string 
color is mixed with colors that are already on the drawing surface. 

The character string background color default is CLR_BACKGROUND, usually 
defined by the application as the same color as the drawing surface. The 
character string background mix attribute default is BM_LEAVEALONE. The 
leave-alone background mix attribute specifies that the character string 
background color not be drawn. The cell that surrounds the character string 
appears only if the background character-string color and mix attributes are 
changed. 

Use GpiSetAttrs to specify a new color or mix attribute. As input, this 
function accepts the following: 

     Type of primitive, for example, PRIM_CHAR 
     List of attributes to be changed 
     List of attributes to be set to their default values 
     Values for the attributes to be changed 

 GpiSetAttrs also is useful to specify color and mix attributes for a specific 
 data structure -for example, CHARBUNDLE. GpiSetAttrs provides some protection 
 against invalid colors. 

 To determine the current character-string color and mix attributes, call 
 GpiQueryAttrs, which accepts as input the primitive type and the attributes in 
 question. GpiQueryAttrs returns an array of values for the queried attributes. 

 To reset the default character-string color and mix attributes, as with all 
 attributes specified in CHARBUNDLE, call GpiSetDefAttrs, which accepts as 
 input the type of primitive, attributes to be changed, and values that will 
 become the new default values. Changing default values is especially important 
 when working with segments. Changing the default values during a series of 
 drawing functions is not recommended. 

 The character color and mix attributes also can be specified using the 
 following functions: 

     GpiSetColor 
     GpiSetMix 
     GpiSetBackColor 
     GpiSetBackMix 

 If the character color, character background color, mix, or background mix 
 attributes are specified individually, the following queries can return a 
 value inconsistent with the current character attributes: 

     GpiQueryColor 
     GpiQueryMix 
     GpiQueryBackColor 
     GpiQueryBackMix 


═══ 8.2. Using Character String Primitives ═══

You can use the character string primitive functions to perform the following 
tasks: 

     Draw a string of characters using the selected font. 

     Modify the string by using one or more of the following operations: 

           Scaling 
           Shearing 
           Rotating 
           Transforming 
           Changing the angle of the baseline 

     Aligning text 


═══ 8.2.1. Drawing Text ═══

The following figure shows how to select a Helvetica outline font, set the size 
of the character box, change the foreground color to red, set the character 
angle, and move the cursor to a specified location. Then, GpiCharString is used 
to write a string of characters with the specified size, color, angle, and 
location. 

#define INCL_GPIPRIMITIVES
#define INCL_GPILCIDS
#include <os2.h>
void fncFONT09(void){

    POINTL ptl = { 100, 50 };
    GRADIENTL grad = { 4, 1 };
    SIZEF sizfx;
    FATTRS fat;
    CHARBUNDLE cbnd;
    FONTMETRICS afm[80];
    HPS hps;
    HDC hdc;
    LONG cHelvFonts, i;
    LONG cFonts = 0;
    LONG lcid = 1;
    LONG devRes[2];               /* Horizontal, vertical font resolutions */

    cHelvFonts = GpiQueryFonts(hps, QF_PUBLIC, "Helv",
        &cFonts, sizeof(FONTMETRICS), NULL);

    GpiQueryFonts(hps, QF_PUBLIC, "Helv", &cHelvFonts,
        sizeof(FONTMETRICS), afm);
                                  /* Find an outline Helvetica font.       */

    for (i = 0; (!(afm[i].fsDefn & FM_DEFN_OUTLINE)) &&
               i < cHelvFonts; i++)    ;

    fat.usRecordLength = sizeof(FATTRS);
    fat.fsSelection = 0;
    fat.lMatch = afm[i].lMatch;
    StringCopy(fat.szFacename, afm[i].szFacename);
    fat.idRegistry = 0;
    fat.usCodePage = 0;
    fat.lMaxBaselineExt = 0;
    fat.lAveCharWidth = 0;
    fat.fsType = 0;
    fat.fsFontUse = FATTR_FONTUSE_OUTLINE;

    GpiCreateLogFont(hps, (PSTR8) NULL, lcid, &fat);
    GpiSetCharSet(hps, lcid);

    DevQueryCaps(hdc, CAPS_HORIZONTAL_FONT_RES, 2L, devRes);
    sizfx.cx = MAKEFIXED((afm[i].sNominalPointSize * devRes[0])/ 720, 0);
    sizfx.cy = MAKEFIXED((afm[i].sNominalPointSize * devRes[1])/ 720, 0);
    GpiSetCharBox(hps, &sizfx);

    cbnd.lColor = CLR_RED;
    GpiSetAttrs(hps, PRIM_CHAR, CBB_COLOR, NULLHANDLE, &cbnd);
    GpiSetCharAngle(hps, &grad);
    GpiMove(hps, &ptl);
    GpiCharString(hps, 11, "Vector Text");
} /* fncFONT09 */

Certain parameters in the above example are explained in Fonts. 


═══ 8.2.2. Formatting Text ═══

Graphics text, like all other graphics objects, has to be positioned correctly 
in the output area, which usually consists of one of the following: 

     Entire client area of a PM window 
     Part of a PM window 
     Addressable area of a printer 

 Unlike other graphics objects, however, text is governed by well-established 
 readability and usability rules. These rules apply generally to text output, 
 whatever its method of production. Following are some recommendations: 

     Lines of text from fonts with large point sizes must be more widely 
      spaced for maximum readability. 

     The longer the line of text, the greater the space between lines must be 
      to ensure that the lines do not appear to merge. 

     Very small text must be split into multiple columns rather than continued 
      across the page. 

 Some of these considerations are taken care of by the font designer. The PM 
 enables you to control both the horizontal and vertical positioning of text. 


═══ 8.2.3. Positioning Text in World Coordinates ═══

When considering text alignment, take the versatility of the coordinate systems 
into account. The following definitions depend on the current coordinate 
system: 

World Coordinate Values 

┌───────────────┬─────────────────────────────────────────────┐
│Value          │Corresponds to the direction of...           │
├───────────────┼─────────────────────────────────────────────┤
│Left           │The lowest x-coordinate value                │
├───────────────┼─────────────────────────────────────────────┤
│Right          │The highest x-coordinate value               │
├───────────────┼─────────────────────────────────────────────┤
│Top            │The highest y-coordinate value               │
├───────────────┼─────────────────────────────────────────────┤
│Bottom         │The lowest y-coordinate value                │
└───────────────┴─────────────────────────────────────────────┘

To position a character string horizontally, you must know the width of the 
output area and the length of the character string. The PM provides three 
different functions for determining the width of the output: 

┌──────────────────────────────┬──────────────────────────────┐
│Function Name                 │Description                   │
├──────────────────────────────┼──────────────────────────────┤
│GpiQueryGraphicsField         │Returns the bottom-left and   │
│                              │top-right corners of the      │
│                              │graphics field in presentation│
│                              │page units.                   │
├──────────────────────────────┼──────────────────────────────┤
│GpiQueryViewingLimits         │Returns the viewing limit.    │
├──────────────────────────────┼──────────────────────────────┤
│GpiQueryPageViewport          │Returns the page viewport in  │
│                              │device units.                 │
└──────────────────────────────┴──────────────────────────────┘

GpiConvert  changes coordinates into world coordinates. To calculate the width 
of the output area, subtract its left from its right. For example, if the left 
is 30, and right is 600, the width of the output area is 570 world coordinates. 

The PM provides three different functions for determining the length of the 
character string primitive: 

     GpiQueryTextBox 
     GpiQueryCharStringPos 
     GpiQueryCharStringPosAt 

 GpiQueryTextBox returns the relative coordinates of a parallelogram that 
 surrounds the character string. By subtracting the x-coordinate of 
 TXTBOX_BOTTOMRIGHT from the x-coordinate of TXTBOX_BOTTOMLEFT, an application 
 can determine the length of the string. 

 GpiQueryCharStringPos returns an array of points, in which the world 
 coordinate position of each character in the string is recorded. The last 
 value in the array becomes the new current position if the string is drawn 
 using GpiCharStringPos. By subtracting this position from the current position 
 (obtained using GpiQueryCurrentPosition), the length of the string can be 
 determined. 

 GpiQueryCharStringPosAt also returns an array of points, in which the world 
 coordinate position of each character in the string is recorded. The last 
 value of the array becomes the new current position if the string is drawn 
 using GpiCharStringPosAt. This function accepts a specified starting position 
 for the character string. By specifying a starting position of (0,0) for 
 example, an application can determine the length of the string without 
 subtraction. 

 The current position actually is not updated by either GpiQueryCharStringPos 
 or GpiQueryCharStringPosAt. 

 When a character string does not fill the width of the output area, it can be 
 positioned in one of the four ways illustrated in the following figure. 

 Horizontal Positioning of Text Strings 

 To left-align the text, set the x-coordinate of the current position to the 
 left of the output area before drawing the character string. 
 GpiSetCurrentPosition must be used to set the current position if your 
 application draws the string using either GpiCharString or GpiCharStringPos. 
 Both GpiCharStringAt and GpiCharStringPosAt accept a starting position as 
 input. 

 To right-align the text, subtract the length of the character string from the 
 width of the output area, then add the difference to the x-coordinate of the 
 current position before drawing the character string. If the output area is 
 570 world coordinates wide, for example, and the character string is 436 world 
 coordinates long, add 134 to the x-coordinate of the current position before 
 drawing the text. 

 To center the text, subtract the length of the character string from the width 
 of the output area, then divide the difference by 2 before adding it to the 
 x-coordinate of the current position. If the difference is 134, for example, 
 you add 67 to the x-coordinate of the current position. 

 To justify the text, so that the text string fills the width of the output 
 area, distribute the surplus space throughout the character string. For 
 example, you could add the extra space to the break characters only, or you 
 could share it equally among all characters in the string. Text justification 
 requires the individual positioning each character in the string using either 
 of the following calls: 

     GpiCharStringPos-draws at the current position and permits you to 
      position every character after the first. 

     GpiCharStringPosAt-permits you to position every character, including the 
      first. 

 Both functions enable you to specify a different character increment for each 
 character in the string. Distance is measured from the character reference 
 point of one character to the character reference point of the next character. 
 The values you specify apply only to the character string supplied at input; 
 they do not become current attribute values. 

 If you are formatting a block of text, the string might be wider than the 
 output area, or longer than 256 characters. In either case, your application 
 must separate the string into smaller groups of characters so that it fits 
 either criteria. A good starting point is to determine the number of 
 characters planned for each line. Dividing the output width by the character 
 cell width can provide a first estimate as to where to separate a character 
 string. An application can use this estimate to work through the string 
 looking for spaces. Each time you find a space, compare the length of the 
 string (up to the space) with the width of the output area. When the string is 
 longer than the output area, work back to the previous space and display or 
 print that part of the string. You can format the entire block of text for the 
 output area in this way. 

 When you are formatting a block instead of a single line of text, an 
 application must specify the vertical placement of each line. If you are using 
 an image font, you have the assurance that each character is the same height. 
 However, you do not have that assurance with an outline font, nor that the 
 text block is written in the same font. Therefore, when calculating the 
 separation of lines, avoid using complex combinations of font metrics values. 
 Instead, it is recommended that you multiply the desired point size, or 
 em-height metric, of the text by 1.2. 


═══ 9. Clipping and Boundary Determination ═══

Both clipping and boundary determination are graphics operations concerned with 
limiting the amount of graphics information passed between different coordinate 
spaces. The following topics are related to the information in this chapter: 

     Presentation spaces and device contexts 
     Coordinate spaces and transformations 
     Regions 
     Paths 


═══ 9.1. About Clipping ═══

Clipping enables the PM to discard parts of a picture that lie outside a 
specified clipping boundary. The parts of the picture enclosed by the boundary 
are said to be inside the clipping area. A clipping area might be a single 
rectangle or a complex shape, depending on the method used to define it. 

Note:  In this chapter, the word area does not refer to an area primitive; it 
describes the shape or shapes used for clipping graphics output. 

If an application attempts to draw outside of a clipping area, the operating 
system ensures that the output does not appear on the drawing surface of the 
output device. For example, if an application defined a triangular clipping 
area before drawing text output, all text outside of the triangle would be 
discarded, even though an entire page of text was defined. The following figure 
illustrates the result. 

Triangular Clip Path 

Clipping boundaries are defined by the application. The PM performs some 
clipping automatically when, for example, your application's graphic output is 
clipped to fit a client window area or the device's output area for a hardcopy 
device. 


═══ 9.1.1. Types of Clipping Areas ═══

The PM programming interface assembles the application's graphics output in a 
process that can use up to five coordinate spaces, known collectively as the 
viewing pipeline. Clipping can occur at each stage in the viewing pipeline. 
Objects in world coordinate, model, page, or device space can be clipped. When 
an application defines clipping areas in several coordinate spaces, the final 
result is similar to combining all the areas into a single clipping area. This 
single area is defined by the intersection of the areas in each coordinate 
space. 

Clipping in different coordinate spaces, however, is a means of conceptualizing 
the process to aid in its understanding. Clipping, like transformations, 
actually happens in one operation, with all the different types of clipping 
being performed on all primitives in the device space at once. 

The following table describes the different types of clipping areas associated 
with the different coordinate spaces. 

Clipping Areas and Coordinate Space Summary 

┌────────────────┬────────────────┬────────────────────────────┐
│Clipping Area   │Coordinate Space│Description                 │
├────────────────┼────────────────┼────────────────────────────┤
│Clip path       │World space     │Always inclusive/inclusive  │
│                │                │                            │
│                │                │Clipping area can have      │
│                │                │curved edges                │
│                │                │                            │
│                │                │Clipping area can be        │
│                │                │rotated.                    │
├────────────────┼────────────────┼────────────────────────────┤
│Viewing limit   │Model space     │Always a rectangular        │
│                │                │clipping boundary           │
│                │                │                            │
│                │                │Always inclusive/inclusive  │
│                │                │                            │
│                │                │Rotating clipping area      │
│                │                │results in larger rectangle.│
├────────────────┼────────────────┼────────────────────────────┤
│Graphics field  │Page space      │Always a rectangular        │
│                │                │clipping boundary           │
│                │                │                            │
│                │                │Always inclusive/inclusive  │
│                │                │                            │
│                │                │Rotating clipping area      │
│                │                │impossible. Cannot specify a│
│                │                │device transform with       │
│                │                │rotation.                   │
├────────────────┼────────────────┼────────────────────────────┤
│Clip region     │Device space    │Can be a single rectangle or│
│                │                │multiple rectangles that    │
│                │                │overlap or remain separate  │
│                │                │                            │
│                │                │Always inclusive/exclusive  │
│                │                │                            │
│                │                │Rotating the clipping area  │
│                │                │is impossible.              │
└────────────────┴────────────────┴────────────────────────────┘

Note:  Inclusive/inclusive means that the operating system includes the bottom 
and leftmost edges of the rectangle in the clipping area as well as the top and 
rightmost edges. Inclusive/exclusive means that the operating system includes 
the bottom and leftmost edges but excludes the top and rightmost edges. 

The following figure illustrates the differences between inclusive-inclusive 
and inclusive-exclusive clipping. 

Inclusive/Inclusive and Inclusive/Exclusive Clipping 


═══ 9.1.1.1. The Clip Path ═══

The clip path defines the clipping boundary in world coordinate space. Paths 
are graphic objects that serve many purposes, only one of which is to be used 
as a clipping mechanism. Paths are described in Paths. The recommended 
functional sequence for creating a clip path is as follows: 

 Function                 Effect 

 GpiBeginPath             Begins the path definition. 

 Line and arc GPIs        Gives the path shape. 

 GpiEndPath               Ends the path definition. 

 GpiModifyPath            An optional step explained below. 

 GpiSetClipPath           Converts the path to a clip path. 

 Before converting to a clip path, the path can be modified using 
 GpiModifyPath. If modified, the path is converted to a geometric (wide) line 
 using the current geometric width, line join, and line end attributes. The 
 shape defined by the geometric line then is used for the clip path. The clip 
 path can be a simple unmodified path. 

 GpiSetClipPath accepts two different path identifiers as input: 

     1SCP_RESET (default) 
     0SCP_AND 

 The default path identifier, SCP_RESET, resets the clip path to infinity, 
 which displays the picture without clipping. If this value is selected, the 
 current clip path definition is discarded instead of stored. 

 A path identifier of SCP_AND specifies that the clip path be redefined as the 
 mathematical intersection of the stored clip path and the current path 
 definition. 

 The only method of specifying the clip path to the current path, after 
 GpiSetClipPath has been called, is to call GpiSetClipPath twice:  the first 
 call with a path identifier of SCP_RESET, and the second with a path 
 identifier of SCP_AND. 

 The following figure shows a triangle shape that has been defined within a 
 path bracket and selected as the current clip path. The filled box shape is 
 drawn subsequently, and, therefore, is clipped to the triangle. 

 The Clipping Path 

 The broken lines show the area of the box that has been clipped. 

 Clip paths are most useful when you want to use an irregular clipping 
 boundary, or when the clipping boundary itself is an integral part of the 
 picture. Both are true of the clip path in the previous figure. 

 GpiSetClipPath also accepts one of two construction options as input: 

     SCP_ALTERNATE (default) 
     SCP_WINDING (must be selected if path has been modified). 

 Any drawing that is clipped to the current clip path must follow the alternate 
 or the winding rules as to whether that portion of a picture is included in 
 the clip area. The alternate and winding modes are described for paths in 
 Paths in Alternate Mode and Paths in Winding Mode. Any point on the boundary 
 of the path is considered within the path and is not clipped. 

 To end clipping to the current clip path, call GpiSetClipPath with an 
 identifier of 0. This function deselects the current clip path by setting it 
 to infinity. In some circumstances, the current clip path is deselected 
 automatically. 

 A path definition can be stored in a graphics segment, and if that segment is 
 retained, the path can be re-created as required when the segment is redrawn. 
 Clip path definitions can be stored in a retained segment also and redrawn 
 when required. In draw-and-retain mode (DM_DRAWANDRETAIN), the initial path or 
 clip path is created as the segment is constructed. If the current drawing 
 mode is retain (DM_RETAIN), however, the path or clip path is not created 
 until the first time the segment is drawn. 


═══ 9.1.1.2. The Viewing Window ═══

The viewing window defines a rectangular clipping boundary in model space. It 
is defined with GpiSetViewingLimits. As input to this function, you supply the 
model coordinates of the lower-left and upper-right corners of the viewing 
window. 

When a drawing primitive, such as a line, intersects a viewing window, any part 
of that line outside of the viewing window is clipped. Any point on the 
boundary of the viewing window is considered within the window, and is not 
clipped. By default, the viewing window performs no clipping. In this case, all 
graphics output in the model space is transformed. The following figure shows 
how the viewing window outlines a part of model space. The Viewing Window 

This example shows how a presentation page is constructed. The viewing window 
outlines the tail of the aircraft, which is scaled and translated when drawn in 
presentation-page space. The rest of the aircraft is clipped away during the 
drawing process. 


═══ 9.1.1.3. The Graphics Field ═══

The graphics field defines a rectangular clipping area in the presentation 
page. It is defined in GpiSetGraphicsField. 

Note:  If this clipping area is to be used, it must be defined before any 
drawing begins. 

Specify the size of the graphics field in presentation page coordinates as 
input to GpiSetGraphicsField. 

Only the graphic output contained in this clipping boundary is visible when the 
presentation page is transformed to device space. By default, the graphics 
field is infinitely large and therefore performs no clipping. If you do specify 
a graphics field, however, any point on its boundary is considered within the 
graphics field and is not clipped. When a drawing primitive, such as a line, 
intersects a graphic field, any part of the line outside the graphics field is 
clipped. The following figure shows how a graphics field could be defined for a 
presentation page. 

The Graphics Field 

The broken line shows an arbitrary graphics field that is smaller than the 
presentation page. The aircraft tail, a separate object in the presentation 
page, is outside the graphics field and is clipped away as it is drawn. 

The picture assembled in the graphics field is the picture that is displayed or 
printed. If you do not define a graphics field, the picture assembled in the 
presentation page is the picture that is displayed or printed. The presentation 
page is not a clipping boundary, and graphics in page coordinate space that are 
outside the presentation page boundary, therefore, might be visible. 


═══ 9.1.1.4. The Current Clipping Region ═══

Clipping regions are clipping areas defined (as regions) by one or more 
rectangles in device coordinates. Because they are defined in device 
coordinates, clipping regions do not suffer from the rounding errors associated 
with other types of clipping. Therefore, they are ideally suited to redraw part 
of the picture without boundary discontinuities, for example, after a BitBlt 
operation has been used to scroll a picture in a window. 

Regions are not available automatically for clipping. To select an existing 
region as the current clipping region, use GpiSetClipRegion. By default, the 
clipping region is the same size as the drawing surface. Only one clipping 
region can exist in the presentation space at one time. To end clipping to the 
current clipping region, deselect it by calling GpiSetClipRegion with a NULL 
region handle. A deselected clipping region retains the effects of any changes 
made to it while it was a clipping region and can be reselected. 

You do not have to deselect the current clipping region before selecting 
another. Each selected clipping region automatically replaces the one before 
it. If a clipping region exists when you call GpiSetClipRegion, the existing 
clipping region reverts to being a normal region, and its handle is returned. 

Clip paths and clip regions share a common implementation, but clip regions are 
faster to create than clip paths. This might be a performance factor when 
designing your application for repairing the screen or redrawing the picture in 
a client window after the display has changed. The following figure illustrates 
this use of regions. 

Screen Repairing 

Note:  GpiSetClipRegion does not cause graphics orders to be added to the 
current segment. Therefore, variations in the clip region must not be used to 
construct the picture. The clip region is intended to define a fixed clipping 
area for the entire picture. 

When you select the current clipping region, none of the region-related GPI 
functions can be used for that region. The PM provides a series of functions 
that mirror the region-related functions. However, all of these functions work 
in world coordinates rather than device coordinates, and, therefore, are 
subject to current transformations. 

Any of the following functions can be used to get information about or to 
redefine the current clipping region. 

     GpiQueryClipBox 

      You can request the dimensions of the smallest rectangle that encloses 
      all current clipping boundaries by calling GpiQueryClipBox. The following 
      boundaries are included in this calculation: 

        -  Current clip path 
        -  Current viewing window 
        -  Current graphics field 
        -  Current clipping region 
        -  Visible region of the window 

     GpiIntersectClipRectangle 

      GpiIntersectClipRectangle redefines the current clipping region to the 
      intersection of the existing clipping region with the rectangle whose 
      dimensions you supply in this function. This has the same effect as 
      CRGN_AND in GpiCombineRegion. 

     GpiExcludeClipRectangle 

      You also can redefine the current clipping region using 
      GpiExcludeClipRectangle. This function excludes a specified rectangle 
      from the current region and has the same effect as CRGN_DIFF on 
      GpiCombineRegion. 

     GpiOffsetClipRegion 

      The current clipping region can be moved from its current position using 
      GpiOffsetClipRegion. 

     GpiPtVisible 

      GpiPtVisible tells you whether a point, expressed in world coordinates, 
      is visible on the screen. A point is visible if it is within all current 
      clipping boundaries and is in the visible region of the window. 

     GpiRectVisible 

      GpiRectVisible tells you whether any part or the whole of a rectangle, 
      whose dimensions you supply in world coordinates, is visible on the 
      screen. The rectangle is visible if it intersects both the visible region 
      of the window and all current clipping boundaries. 


═══ 9.1.2. How Clipping Is Implemented ═══

The rules by which the PM implements clipping are as follows: 

     Any primitive completely outside the clipping boundary is discarded. 

      When a primitive crosses a clipping boundary, any part outside the 
      boundary is discarded. 

     Any primitive completely within the clipping boundary is retained. 

      When a primitive crosses a clipping boundary, any part within the 
      boundary is retained. 

     When the clipping boundary is a clip path, viewing window, or graphics 
      field, any point that falls on the boundary is considered within the 
      clipping boundary. 

      When the clipping boundary is a clipping region, any point on the top or 
      right boundaries of a rectangle is discarded; and any point on the bottom 
      or left boundaries of a rectangle, that is not on the right or top 
      boundaries also, is included in the region. 


═══ 9.1.3. Redrawing Nondynamic Graphics ═══

An interactive graphics application usually permits changes to the displayed 
picture. For example, an object can be moved or sized, and you can plan for 
this by defining particular segments as dynamic. Dynamic segments are described 
in Editing Retained Graphics and Graphics Segments. 

If dynamic segments are inappropriate (when you are using nonretained graphics, 
for example), you can repair the picture using a clipping region, for example, 
a picture of a hexagon and a circle as shown in the following figure. 

A Hexagon and Circle 

If the circle is moved to another screen position by the use of an input 
device, you must repair its original location and redraw it in its new 
location. The following figure shows this sequence of events. Following are the 
steps required to do this: 

   1. Determine the size of the smallest rectangle that contains the circle in 
      its current position using a process called boundary determination. 

   2. Switch off the DCTL_DISPLAY flag of GpiSetDrawControl, apply a 
      translation transformation to the circle, and redraw it in its new 
      position. 

   3. Determine the size of the smallest rectangle that contains the circle in 
      its new position using boundary determination. 

   4. Use GpiConvert to convert the model-space coordinates provided by the 
      boundary-determination process to device-space coordinates. 

   5. Use the device-space coordinates of the two rectangles to create a 
      region, and select it as the current clipping region. 

   6. Switch on the DCTL_DISPLAY flag of GpiSetDrawControl. 

   7. Call GpiErase (or set the erase-before-draw control) to erase the current 
      contents of the clipping region. 

   8. Redraw the picture with the circle in its new position. Any part of the 
      picture within the clipping region is redrawn. That part of the hexagon 
      that is outside the clipping region is unaffected by the change and does 
      not have to be redrawn. 

 Defining a Clipping Region 

 The broken circle shows the position to which the circle is to be moved.  The 
 two bounding rectangles overlap, and produce a complex region.  If the circle 
 were to be moved much farther away from its start position, the region would 
 comprise two disjoint rectangles. 


═══ 9.2. About Boundary Determination ═══

Boundary determination is an operation to compute the size of the smallest 
rectangle that encloses a graphics output in model space. One use of boundary 
determination is to enable you to repair only the affected parts of the screen, 
when a graphics object is moved, for example, or when a graphics object is 
changed some other way. Dynamic segments are not included in 
boundary-determination operations. 

Boundary determination can be performed on both retained and nonretained 
graphics. In both instances, you request boundary data to be calculated by 
setting the boundary data flag (DCTL_BOUNDARY) in GpiSetDrawControl. If you do 
not set this flag (for example, if you do not want to collect boundary data 
unnecessarily) and later find that you need boundary data for a particular 
object, you can do the following: 

   1. Switch on the boundary-data flag, and switch off the display flag, using 
      GpiSetDrawControl. 

   2. Redraw the object in its current location. Boundary data is collected, 
      but the object is unaltered. 

 If you are drawing retained graphics, each drawing request (GpiDrawSegment, 
 GpiDrawFrom, and GpiDrawChain) causes the boundary data resulting from the 
 drawing to be made available. The application must request this data 
 explicitly by calling GpiQueryDeviceBitmapFormats after each drawing request 
 for which it wants to examine boundary data. Boundary data is returned to the 
 application in model space coordinates. The boundary data is reset before each 
 retained drawing operation, so there is no risk of accumulating data from 
 separate operations. 

 If you are drawing nonretained graphics, boundary data is accumulated for each 
 GpiPutData and for each individual primitive drawing function. The application 
 can request the accumulated boundary data at any time by calling 
 GpiQueryBoundaryData. Data continues to accumulate unless you call the 
 GpiResetBoundaryData; it is not reset automatically. 

 The boundary data returned to you is in the form of four model-space 
 coordinates, which are the lowest (x,y) positions and the highest (x,y) 
 positions of the bounding rectangle in model space as illustrated in the 
 following figure. 

 The Bounding Rectangle 


═══ 9.3. Using Clipping and Boundary Determination ═══

This section explains how to use clipping functions to: 

     Create a clip path or clip region 
     Exclude a rectangular area from a clip region 
     Add a rectangular area to a clip region 
     Set the clip region to the intersection of the current clip region and a 
      specified rectangle 
     Determine the size of the smallest rectangle that will surround the 
      intersection of the current clipping areas completely 


═══ 9.3.1. Creating a Clip Path ═══

A drawing and computer-aided-design (CAD) application may require the ability 
to clip to curved edges. If so, it must use a clip path to define a curved 
clipping area in world coordinates. Because clip paths (especially ones that 
clip to curved edges) require considerable memory and processing time, use them 
only when necessary. Whenever possible, your application must use a clip 
region, graphics field, or viewing limit. 

To create a clip path, do the following: 

   1. Determine the clip path's shape and size (in world coordinates). 

   2. Use GpiBeginPath to begin defining the path. 

   3. Create the path. 

   4. Close the path definition with GpiEndPath. 

   5. Create a clip path from the path definition with GpiSetClipPath. 

 The following figure uses this procedure to create an elliptical clip path. 

  #define INCL_GPIPATHS
  #include <os2.h>
  void fncCLIP01(void){
      HPS    hps;                      /* Presentation-space handle */
      POINTL ptl1;                     /* Point structure           */
      FIXED  fxArc;                    /* Multiplier for arc        */
      LONG idPath;                     /* Path identifier           */
          .
          .           /* Load ptl1 with coordinates of clip path.   */
          .
      idPath = 1;
      GpiBeginPath(hps, idPath);       /* Begins path               */
      GpiMove(hps, &ptl1);             /* Sets current position     */
      fxArc  = MAKEFIXED(50, 0);       /* Sets arc multiplier       */
      GpiFullArc(hps, DRO_OUTLINE, fxArc);  /* Defines ellipse      */
      GpiEndPath(hps);                 /* Ends path                 */
      GpiSetClipPath(hps, idPath, SCP_ALTERNATE | SCP_AND);
  } /* fncCLIP01 */


═══ 9.3.2. Creating a Clip Region ═══

To create a clip region, first determine its size and shape (in device 
coordinates). Load the coordinates for the rectangles that define the clip 
region into an array of RECTL structures. Then create the region and set it to 
a clip region with GpiCreateRegion and GpiSetClipRegion respectively. 

The following figure shows how to create a clip region. 

#include <os2.h>
void fncCLIP02(void){
    HPS  hps;
    HRGN hrgn;
    RECTL arcl[3];
        .
        .  /* Load array of RECTL structures with coordinates.       */
        .
    hrgn = GpiCreateRegion(hps, sizeof(arcl) / sizeof(RECTL), arcl);
    GpiSetClipRegion(hps, hrgn, NULL);
} /* fncCLIP02 */


═══ 9.3.3. Excluding a Rectangular Area from a Clip Region ═══

Some applications let you prepare output in multiple stages. For example, a 
word processing application might permit you to prepare your text first and 
then add bit maps that enhance and support the text. These applications can use 
GpiExcludeClipRectangle to exclude an area from a clip region, preventing the 
user from deleting output that already exists. 

To exclude an area from a clip region, first determine the dimensions (in 
device coordinates) of the smallest rectangle that completely surrounds the 
area to exclude from the clip region. Then call GpiExcludeClipRectangle, 
including as input the dimensions of the area to exclude. The following figure 
illustrates these steps. 

#include <os2.h>
void fncCLIP03(void){
    HPS   hps;
    RECTL rcl;
        .
        .  /* Set rectangle coordinates here. */
        .
    GpiExcludeClipRectangle(hps, &rcl);
} /* fncCLIP03 */


═══ 9.3.4. Adding a Rectangular Area to a Clip Region ═══

Some applications might need to increase the size of a clip region. For 
example, a user might request that a desktop publishing application extend a 
column of text on a page. 

To add a rectangular area to a clip region, follow these steps: 

   1. Determine the dimensions (in device coordinates) of the rectangular area 
      to add to the current clip region. 

   2. Release the current clip region using GpiSetClipRegion. GpiCombineRegion 
      cannot combine regions if either of the regions is a clip region. 

   3. Call GpiCreateRegion and pass it the dimensions of the rectangle that you 
      defined in Step 1. This creates a second region that you can combine with 
      the first. 

   4. Call GpiCreateRegion again and create a third region that will be the 
      final destination region. 

   5. Call GpiCombineRegion to create a region that combines the original 
      region and the region you created in Step 2. It is not essential to 
      create a third region because GpiCombineRegion can use one of the 2 
      source regions being combined for a target region. 

   6. Call GpiSetClipRegion and pass it the handle returned by 
      GpiCombineRegion. 

 The following figure illustrates these steps. 

  #define INCL_GPIREGIONS
  #include <os2.h>
  void fncCLIP04(void){
      HPS   hps;
      RECTL rcl1, rcl2, rcl3;
      HRGN  hrgn1, hrgn2, hrgn3;

      hrgn1 = GpiCreateRegion(hps, sizeof(rcl1) / sizeof(RECTL), &rcl1);
      GpiSetClipRegion(hps, hrgn1, NULL);       /* Creates first clipping region */
          .
          .  /* Compute coordinates of second region here.                       */
          .
      GpiSetClipRegion(hps, NULLHANDLE, NULL);  /* Releases first clipping region*/
      hrgn2 = GpiCreateRegion(hps, sizeof(rcl2) / Sizeof(RECTL), &rcl2);
      hrgn3 = GpiCreateRegion(hps, sizeof(rcl3) / Sizeof(RECTL), &rcl3);
      GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_OR);
      GpiSetClipRegion(hps, hrgn3, NULL);       /* Creates second clipping region*/
  } /* fncCLIP04 */


═══ 9.3.5. Setting the Clip Region to a Region Intersection ═══

Your application might require the ability to set the clip region to the 
intersection of the current clip region and another region. Do this with 
GpiIntersectClipRectangle, as shown in the following: 

#include <os2.h>
void fncCLIP05(void){
    RECTL rcl;
    HPS hps;
        .
        . /* Load rcl with coordinates of rectangle to intersect. */
        .
    GpiIntersectClipRectangle(hps, &rcl);
} /* fncCLIP05 */


═══ 9.3.6. Determining the Size of a Clipping Area ═══

If an application is able to specify a clip path in world space, a viewing 
limit in model space, a graphics field in page space, and a clip region in 
device space, it might be necessary for your application to determine the size 
of the clipping area formed by the intersection of the four. GpiQueryClipBox 
returns the dimensions (in world coordinates) of the smallest rectangle that 
completely surrounds the intersection of all the defined clipping areas, 
including the visible region. 

The following figure shows how to use GpiQueryClipBox to fill a RECTL structure 
with the desired coordinates. 

#include <os2.h>
void fncCLIP06(void){
    HPS   hps;
    RECTL rclClip;
    GpiQueryClipBox(hps, &rclClip);
} /* fncCLIP06 */


═══ 10. Color and Mix Attributes ═══

This chapter describes color and mix attributes and their use in OS/2 
applications. The following topics are related to information in this chapter: 

     Presentation spaces and device contexts 
     Line and arc primitives 
     Marker primitives 
     Area primitives 
     Character string primitives 
     Bit maps and images primitives 


═══ 10.1. About Color and Mix Attributes ═══

Color and mix are two attributes of graphics primitives. They can be specified 
by an application in a number of ways, and are specified in the ...BUNDLE data 
structures associated with the five graphics primitives and in bit maps. Bit 
maps and some of the primitives have both foreground and background color 
attributes. For example, a character string primitive has a foreground color 
attribute that specifies the color of the character and a background color 
attribute that specifies the color of the character cell surrounding the 
character. 

The mix attribute controls how each primitive is combined with the existing 
drawing. Among other things, it affects the color that results when primitives 
of different colors overlap. Primitives with foreground and background color 
attributes also have foreground and background mix attributes. 


═══ 10.2. Color Implementation ═══

Understanding how colors are implemented can assist in understanding how the 
color and mix attributes work. 

The pel is the smallest element of the display screen that can be addressed. 
For monochrome displays, pels are either turned off or turned on. For color 
displays, each pel contains a red, green, and blue section, each of which is 
called a phosphor. 

The display has color guns of red, blue, and green light that illuminate the 
phosphors in a single pel. By switching these color guns on and off in 
different combinations, eight standard colors can be produced. By varying the 
intensities of the color guns, additional colors can be produced. The following 
table shows the eight standard colors that can be generated from the three 
color guns. 

┌───────────────┬───────────────┬───────────────┬───────────────┐
│Pel appears... │Red            │Green          │Blue           │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Red            │ON             │OFF            │OFF            │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Green          │OFF            │ON             │OFF            │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Blue           │OFF            │OFF            │ON             │
├───────────────┼───────────────┼───────────────┼───────────────┤
│White          │ON             │ON             │ON             │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Black          │OFF            │OFF            │OFF            │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Cyan           │OFF            │ON             │ON             │
│(Turquoise)    │               │               │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Pink           │ON             │OFF            │ON             │
├───────────────┼───────────────┼───────────────┼───────────────┤
│Yellow         │ON             │ON             │OFF            │
└───────────────┴───────────────┴───────────────┴───────────────┘

Each pel is described internally by a number of bits of storage. In a 
monochrome display, only one bit per pel is required, and that bit is either on 
or off. In an eight-color system, three bits per pel are necessary. Each of 
those three bits records the on or off setting of one color gun. 

To be able to control the intensity of a color and obtain more than eight 
colors, more than three bits per pel are needed. For example, six bits per pel 
provide 32 different combinations. 

The wider the range of available colors, the more bits per pel required for 
each color. This storage issue is resolved by keeping a wide choice of colors 
but restricting the number of colors available at any given time. Applications 
define the colors that they want to use in a logical color table. Selecting a 
color defined in the logical color table produces the nearest available color 
in the hardware palette. 


═══ 10.2.1. RGB Color Encoding ═══

The red, green, and blue (RGB) components of a color are stored in either an 
RGB or RGB2 data structure, or as a long integer (32-bit) value. The color 
fields in the RGB2 structure and in the long integer follow the same rules. 

If stored as a long integer, the RGB value has the first 8 bits reserved for a 
flag value and the remaining 24 bits reserved for color intensity. The flag 
byte must be set to 0. Each of the last three bytes specifies a color 
intensity, in the range 0 through 255, for a single primary color. 

If a byte contains 0, the corresponding primary color is not present. As the 
value in the byte increases, the intensity of the primary color increases. For 
example, if the byte contains 128, the primary color is pale; if the byte 
contains 255, the primary color is as intense as the device permits. 

The RGB value is determined by the following equation: 

    RGB Value = (R * 65536) + (G * 256) + B

    Where:
        R is the red intensity
        G is the green intensity
        B is the blue intensity

If all three bytes are set to 0, the resulting color is black; if they all are 
set to 255, the resulting color is white. The RGB value associated with each of 
the standard eight colors is in the following table. 

┌────────────────────┬────────────────────┐
│Color               │RGB value           │
├────────────────────┼────────────────────┤
│Black               │0x00000000          │
├────────────────────┼────────────────────┤
│Red                 │0x00FF0000          │
├────────────────────┼────────────────────┤
│Green               │0x0000FF00          │
├────────────────────┼────────────────────┤
│Blue                │0x000000FF          │
├────────────────────┼────────────────────┤
│Pink                │0x00FF00FF          │
├────────────────────┼────────────────────┤
│Cyan                │0x0000FFFF          │
├────────────────────┼────────────────────┤
│Yellow              │0x00FFFF00          │
├────────────────────┼────────────────────┤
│White               │0x00FFFFFF          │
└────────────────────┴────────────────────┘


═══ 10.2.2. Color Tables ═══

A color table is an array of RGB values. There are two kinds of color tables: 
logical and physical. The logical color table is a list of colors specific to a 
presentation space. An application typically uses a logical color table to 
define colors specific to that application. 

The physical color table specifies colors the device can generate currently. 
These device colors are shared by every application on the system. Because some 
display adapters cannot generate every possible device color at the same time, 
the physical color table can be a subset of the full range of possible device 
colors. The operating system maps the RGB values specified in the logical color 
table to device colors in the physical color table. 


═══ 10.2.3. Logical Color Table ═══

A logical color table contains a variable number of entries, each of which 
describes a different RGB (Red, Green, Blue) combination that produces a color. 
The principle of the color table is illustrated in the following figure. 

Logical Color Table 

This simplified example demonstrates that to produce yellow on the computer 
screen, red and green are mixed in equal intensities, and no blue is used at 
all. In this example, yellow is addressed in the color table by index 21. 
Notice that this is not the same index number used in the default logical color 
table, which indicates that this color table has been changed by the 
application. 

A logical color table is stored in a presentation space and is specific to that 
presentation space. A logical color table enables applications to specify 
colors as indexes rather than explicit RGB values. 

The colors displayed are likely to vary from one output device to another so 
the definitions in the color table can be fine-tuned to get the best results. 
Any color can be made more or less intense by altering its definition in the 
logical color table. 


═══ 10.2.3.1. Default Logical Color Table ═══

The PM provides a default logical color table, which defines the colors and the 
indexes that retrieve them, as shown in the following table. 

Default Logical Color Table 

┌────────────────┬──────┬──────────────────────────────────────┐
│Color Index     │Index │Effect                                │
│                │Number│                                      │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_FALSE       │-5    │All bits are set to 0.                │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_TRUE        │-4    │All bits are set to 1.                │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DEFAULT     │-3    │Default value                         │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_WHITE       │-2    │White                                 │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_BLACK       │-1    │Black                                 │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_BACKGROUND  │0     │Natural background color for the      │
│                │      │device                                │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_BLUE        │1     │Blue                                  │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_RED         │2     │Red                                   │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_PINK        │3     │Pink                                  │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_GREEN       │4     │Green                                 │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_CYAN        │5     │Cyan                                  │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_YELLOW      │6     │Yellow                                │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_NEUTRAL     │7     │Neutral - The contrasting color to    │
│                │      │CLR_BACKGROUND                        │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKGRAY    │8     │Dark gray                             │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKBLUE    │9     │Dark blue                             │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKRED     │10    │Dark red                              │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKPINK    │11    │Dark pink                             │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKGREEN   │12    │Dark green                            │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_DARKCYAN    │13    │Dark cyan                             │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_BROWN       │14    │Brown                                 │
├────────────────┼──────┼──────────────────────────────────────┤
│CLR_PALEGRAY    │15    │Pale gray                             │
└────────────────┴──────┴──────────────────────────────────────┘

Note:  Entries after CLR_PALEGRAY have device-dependent defaults. 

PM maps the color index name to the index number (shown in the second column of 
the previous table), then uses that number to address the appropriate color. 


═══ 10.2.3.2. Device-Independent Color Indexing ═══

Three of the index names provide a level of device independence in choosing 
colors:  CLR_DEFAULT, CLR_BACKGROUND, and CLR_NEUTRAL. These indexes enable an 
application to select colors according to their purpose, and thus build device 
independence into your applications. The purpose of a color does not vary from 
one device to another, although the actual color used to implement that purpose 
might. The following table describes these indexes and the purpose of each: 

┌────────────────────┬────────────────────────────────────────┐
│Index               │Purpose                                 │
├────────────────────┼────────────────────────────────────────┤
│CLR_BACKGROUND      │The natural background color for the    │
│                    │device. This is the color of the paper  │
│                    │on a printer, and the window background │
│                    │color (white, by default) on a display. │
├────────────────────┼────────────────────────────────────────┤
│CLR_NEUTRAL         │The contrast color to CLR_BACKGROUND.   │
│                    │This is usually black on a printer, and │
│                    │the default window text color (black, by│
│                    │default) on a display.                  │
├────────────────────┼────────────────────────────────────────┤
│CLR_DEFAULT         │Unless redefined, this has the same     │
│                    │effect as CLR_NEUTRAL.                  │
└────────────────────┴────────────────────────────────────────┘

The colors produced by CLR_DEFAULT, CLR_BACKGROUND, and CLR_NEUTRAL in the 
default logical color table depend on the output device. For example, 
CLR_NEUTRAL could produce black on a device with a white background or white on 
a device with a black background. 


═══ 10.2.4. Defining a Logical Color Table ═══

To change the values in the default logical color table (that is, to load a new 
logical color table), use GpiCreateLogColorTable. Using this function, an 
application can do the following: 

     Replace part or all of the default color table. 
     Add color definitions to the default color table. 
     Reset the logical color table to its default values. 

 There are two methods of making changes: 

     To add to a table or change some of its  contents, rather than replace 
      the table completely, supply an array of color indexes and their 
      associated RGB values. 

     To load a consecutive sequence of index values, supply only an array of 
      RGB values without index values. 


═══ 10.2.4.1. Color Tables in Index Mode ═══

The default logical color table is defined as an array of color indexes and 
their associated RGB values. A table in this format is in index mode. 

To alter a logical color table in index mode, specify either LCOLF_INDRGB or 
LCOLF_CONSECRGB as the format value in GpiCreateLogColorTable. If an 
application uses the color index names to address the contents of a loaded 
color table in index mode, the color identified by the associated index number 
is retrieved. For example, CLR_NEUTRAL produces the color addressed by index 
number 7. If CLR_NEUTRAL must be blue, the application must define the color 
table so that index number 7 addresses the RGB definition of the appropriate 
shade of blue. 

If an application uses the format LCOLF_INDRGB when calling 
GpiCreateLogColorTable, the application supplies an array of index and RGB 
pairs to update the table. These values do not have to be consecutive. An 
application can change the contents of an existing table and add entries to the 
end of the table. 

If an application calls GpiCreateLogColorTable using the LCOLF_CONSECRGB 
format, the application supplies an array of RGB values and a starting index. 
When using this format, the RGB values must be consecutive. You cannot use a 
single call to GpiCreateLogColorTable to redefine CLR_BLUE and CLR_PINK without 
also specifying an RGB value for CLR_RED. As with LCOLF_INDRGB, this format can 
be used to change the contents of the existing table and to add entries to the 
end of the table. 

When an application calls GpiSetAttrs to put a value into the color field of a 
graphics primitive attribute structure, the value is an index into the logical 
color table. When the operating system draws the primitive, it uses this index 
to determine the RGB value specified in the logical color table by the 
application. It then searches the physical color table for the color closest to 
this RGB value. The operating system then draws the primitive, using the color 
from the physical color table. How closely the drawn colors match the colors in 
the logical color table depends on the device colors in the physical color 
table. 


═══ 10.2.4.2. Color Tables in RGB Mode ═══

The color values specified with GpiSetAttrs  and GpiSetColor also can be 
specified directly as RGB values rather than as indexes. To enable this, the 
logical color table must be switched into RGB mode by calling 
GpiCreateLogColorTable, specifying a format of LCOLF_RGB. (No color array is 
passed.) 

If the color table is in RGB mode, it can be switched back to index mode and 
reset to its original default values by specifying either LCOLF_INGRGB or 
LCOLF_CONSECRGB in GpiCreateLogColorTable. 


═══ 10.2.5. Querying the Available Colors ═══

Several query functions are provided for applications to get information about 
the current logical and physical color tables before defining a logical color 
table. 

Applications use GpiQueryColorData to determine whether the default logical 
color table is in effect. If it is not, the following information about the 
loaded logical color table is returned: 

     Format of the current logical color table 

     Smallest and largest color indexes (if the table is in index mode) 
      supported in this color table. The smallest color index is always 0, and 
      the largest color index is never less than 15, because deleting entries 
      from the default logical color table is not permitted. 

 GpiQueryRealColors returns the RGB values of each of the distinct colors 
 defined in the physical color table of the current device. It also can return 
 the index in the current logical color table that references each of the 
 colors in the physical table. 

 To determine the available colors nearest to a specified color on a particular 
 device, call GpiQueryNearestColor, which accepts as input the RGB value of the 
 desired color. The function returns the RGB value of the nearest available 
 color in the physical color table of the associated device. 

 Applications can use GpiQueryRGBColor to determine the RGB value of a 
 particular color. GpiQueryRGBColor accepts as input the index to the logical 
 color table entry of the color in question. Output from this function is the 
 RGB value that the index would reference in the physical color table. If a 
 logical color table is loaded in RGB mode, GpiQueryRGBColor returns the same 
 results as GpiQueryNearestColor. 

 Conversely, to determine the index value that references a given RGB color (or 
 the closest match to that color) in the physical color table, an application 
 uses GpiQueryColorIndex. The application can determine which colors are in the 
 current logical color table by calling GpiQueryLogColorTable. To determine 
 which colors are in the physical color table, call GpiQueryRealColors. 


═══ 10.2.6. Physical Color Table ═══

Each output device has its own physical color table, which is organized like a 
logical color table. The physical color table contains the RGB color 
definitions of the distinct colors that the device can produce, while a logical 
color table contains the definitions of the colors as chosen by an application. 
When an application draws on an output device, the PM maps the index value that 
addresses the current color in the logical color table to the index that 
retrieves the closest match for the current color in the physical color table. 

Because this substitution occurs when the graphics are drawn, the presentation 
space can be associated with a number of different device contexts without 
invalidating the logical color definitions. For example, an application can 
create a picture on the screen using a wide range of colors, then direct that 
drawing to an eight-pen vector plotter. The drawing is reproduced without 
having to be re-created. Although the picture, as drawn by the plotter, does 
not have the variety of colors displayed on the screen, the substitution 
process selects the nearest match for each color on the screen from the eight 
available colors on the plotter. 


═══ 10.2.7. Palette Manager ═══

Applications can use GpiCreatePalette to change the physical color palette by 
creating a new palette. This function is used if the application has specific 
color needs and must ensure that the color is part of the physical color 
palette. GpiCreatePalette also enables an application to prevent dithering of 
the 16 default colors by setting the flag parameter to LCOL_PURECOLOR. If the 
full 256 colors in the palette are needed, the application can set the flag to 
LCOL_OVERRIDE_DEFAULT_COLORS. It is recommended that the palette manager 
functions be used only when really necessary because the operating system 
cannot guarantee consistent colors in other windows and the ability to change 
the physical palette is device dependent. 

After the palette is created, an application can set or change any of the 
values in the palette by calling GpiSetPaletteEntries. To delete the palette, 
applications use GpiDeletePalette, passing the handle of the palette to be 
deleted. (The handle is returned by GpiCreatePalette when the palette is 
created.) 

GpiQueryPalette enables applications to determine the palette currently 
selected for a given presentation space. A palette can be used by more than one 
presentation space at the same time. The operating system maintains a count of 
the number of presentation spaces using a specific palette. Complete 
information on the current palette can be accessed by GpiQueryPaletteInfo. 

Palettes also can be shared by using a palette handle. 

When coding an application, color table functions and color palette functions 
must not be mixed. The application can call DevQueryCaps to determine whether 
the hardware supports palettes, then call the appropriate functions. 


═══ 10.2.7.1. Realizing a Color Palette ═══

WinRealizePalette maps the colors requested by the application into the color 
palette for the system. When the application's window is activated, the palette 
changes are transferred, or realized, into the physical palette for the system. 

When a palette is realized, there might not be enough empty palette entries to 
accommodate the additional palette changes (a maximum of 256 entries). For 
example, it is possible that some of the colors changed in the physical palette 
are being used by another application. In this situation, a WM_REALIZEPALETTE 
message is posted to all the applications running on the desktop. 

On receiving the WM_REALIZEPALETTE message, applications using palette manager 
functions must repaint their screens. The original application colors are 
mapped to the closest matching color in the new palette. Applications that do 
not use palette manager functions normally perform default processing within 
their applications causing a repaint of their windows with the closest match 
from the palette. If there are no changes, just additions, to the physical 
palette, no message is sent. 

Note:  The palette manager maps a window's colors to the closest available 
value in the palette when the physical palette has to be changed, but this does 
not guarantee that the color will be a close match to the original color used. 

As the focus changes from window to window, the physical palette changes 
according to the activated window. Notification messages are sent as necessary 
to other applications. 

If the physical color values in the palette have to change to accommodate the 
number of palette entries passed from the application when a palette is 
realized, the number of altered entries in the physical palette is returned by 
WinRealizePalette. 

Color palette realization is available only to systems that have a minimum of 
256 colors. 


═══ 10.2.8. Color Attribute ═══

The PM graphic interface uses a variety of colors. These colors are referred to 
as the system colors, and they are defined in the system color table, which is 
separate from an application's logical color table. To find out the RGB values 
of the system colors, call WinQuerySysColor. 

The colors of graphic primitives are specified separately from the system 
colors. Every primitive has a foreground color, and some also have a background 
color. 


═══ 10.2.8.1. Primitive Foreground ═══

The foreground of a primitive is the primitive itself. For example, the 
foreground of a full arc primitive is the full arc, as shown in the following 
figure. 

Foreground of a Primitive 

The full arc primitive is drawn in a different color from the window 
background. 

By default, the foreground color of all primitives is the color addressed by 
the index CLR_DEFAULT. In the default color table, this produces black on a 
graphics display. If the application replaces the default logical color table, 
CLR_DEFAULT produces the color addressed by index number 7 (CLR_NEUTRAL). 


═══ 10.2.8.2. Primitive Background ═══

The following primitives have a background: 

     Areas 
     Character strings 
     Images 
     Markers 

 The background of any character or marker primitive, whether the primitive is 
 from an image or an outline font, is the entire character or marker box. First 
 the background is drawn, then the foreground is drawn on top of it. Similarly, 
 the background of an area primitive is the entire area to be filled. The 
 background of an image primitive, however, is that part of the primitive in 
 which the pels are not set. The following figure shows the background of a 
 primitive. 

 Background of a Primitive 

 The background of this character-string primitive is the entire character box. 

 The index to the default background color is CLR_BACKGROUND, which provides a 
 background color appropriate for the device. On a printer, CLR_BACKGROUND is 
 the color of the paper. On a display screen, CLR_BACKGROUND is the default 
 window background color. 


═══ 10.2.8.3. Changing the Foreground and Background Colors of Primitives ═══

To change the current foreground color, use GpiSetColor. As input, the 
application supplies either the index to the required color in the current 
logical color table or the RGB value of the color, depending on the mode of the 
table. Color indexes higher than those supplied in the default color table must 
be loaded explicitly before they can be used. 

It is possible to specify one of the system colors (for example, 
SYSCLR_ACTIVEBORDER) as the current foreground (or background) color of a 
primitive. The color appears as defined in the system color table, and the 
logical color table is not used. 

The specified color becomes the current color, and the foreground of any 
primitive drawn subsequently is drawn in that color. The current foreground 
color for a particular primitive type is set by calling GpiSetAttrs. For 
example, if an application sets the current foreground color to CLR_RED by 
calling GpiSetColor, and sets the current foreground color for marker 
primitives to CLR_CYAN by calling GpiSetAttrs, all subsequent markers are cyan, 
and all other primitives are red. 

To change the current primitive background color, call GpiSetBackColor. To 
ensure that this color is different from the background color of the output 
area (so that the entire primitive background is visible), the current window 
background color must not be the same as the current primitive background 
color. Also, select an appropriate background mix attribute. 

GpiQueryBackColor returns the current background color setting for a character 
primitive. To learn the current foreground color setting, use GpiQueryColor. 
GpiQueryAttrs can be used to determine the current foreground and background 
color values for a single primitive type. 


═══ 10.2.9. Color Output and Mix Attributes ═══

A mix attribute is a bitwise operation on the color indexes in a device's 
logical color table. Mix attributes enable colors to be specified in relation 
to other colors. When an application draws a graphics primitive, the operating 
system uses a mix attribute to determine the color that appears on the output 
device. 

For example, instead of specifying that a line should be black and, therefore, 
invisible if the background also is black, an application can use a mix 
attribute of FM_XOR to specify that the line always should be drawn the inverse 
of the background color. 

Suppose an application has set the lColor field in the LINEBUNDLE structure to 
CLR_RED and the usMixMode field in the same structure to FM_OR. The current 
color of the drawing surface is CLR_GREEN. To determine the color of a line, 
the operating system performs a bitwise OR operation on the indexes of these 
colors, as follows: 

          0010  (the default index for red)
          0100  (the default index for green)
         ------
          0110  (result of bitwise OR)

In this case, the result is 6-the index for yellow. This means that even though 
the application specified CLR_RED in the LINEBUNDLE structure, a yellow line 
appears when the application calls any of the functions that draw a line 
primitive. 


═══ 10.2.10. Mix Attribute ═══

The mix attribute determines how each primitive an application draws is 
combined with any existing drawing. In color applications, the mix attribute 
determines the color that results when one primitive is drawn on top of 
another. There are two forms of the mix attribute:  foreground mix and 
background mix. 

The foreground mix attribute governs how the foreground of a primitive is 
combined with the existing drawing, and it applies to all primitive types. The 
background mix attribute governs how the background of a primitive is combined 
with the existing drawing, and it is applicable only to those primitives that 
have a background. Primitives that can be affected by the background mix 
attribute are areas, character strings, images, and markers. The primitive 
attribute data structures contain fields for both foreground and background 
color and mix attributes. 

There are 17 foreground mix attributes. For each mix attribute, the indexes of 
the foreground and current drawing-surface colors are combined by using one of 
the bitwise operators. The available foreground mix settings are listed in the 
following table. 

Foreground Mix Attributes 

┌───────────────┬───────────────┬──────────────────────────────┐
│Mix Attribute  │Effect         │Description                   │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_DEFAULT     │Default        │Default foreground mix        │
│               │               │attribute (overpaint).        │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_OR          │OR             │Index value of the final color│
│               │               │is determined by a bitwise OR │
│               │               │operation on the index of the │
│               │               │foreground color and the index│
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_OVERPAINT   │Overpaint      │Index value of the final color│
│               │               │is that of the foreground     │
│               │               │color. This is the default    │
│               │               │foreground mix attribute.     │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_XOR         │Exclusive-OR   │Index value of the final color│
│               │(XOR)          │is determined by a bitwise XOR│
│               │               │operation on the index of the │
│               │               │foreground color and the index│
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_LEAVEALONE  │Leave-alone    │Index value of the final color│
│               │(Invisible)    │is that of the index of the   │
│               │               │color of the drawing surface. │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_AND         │AND            │Index value of the final color│
│               │               │is determined by a bitwise AND│
│               │               │operation on the index of the │
│               │               │foreground color and the index│
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_SUBTRACT    │(Inverse       │Index value of the final color│
│               │Source) AND    │is determined by inverting the│
│               │Destination    │index of the foreground color │
│               │               │and performing a bitwise AND  │
│               │               │operation on this value and   │
│               │               │the index of the color of the │
│               │               │drawing surface.              │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_MASKSRCNOT  │Source AND     │Index value of the final color│
│               │(Inverse       │is determined by inverting the│
│               │Destination)   │index value of the            │
│               │               │drawing-surface color and     │
│               │               │performing a bitwise AND      │
│               │               │operation on this value and   │
│               │               │the index value of the        │
│               │               │foreground color.             │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_ZERO        │All zeros      │RGB value of the final color's│
│               │               │is always 0x00000000.         │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_NOTMERGESRC │Inverse (Source│Index value of the final color│
│               │OR Destination)│is always the inverse of the  │
│               │               │FM_OR result.                 │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_NOTXORSRC   │Inverse (Source│Index value of the final color│
│               │XOR            │is always the inverse of the  │
│               │Destination)   │FM_XOR result.                │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_INVERT      │Inverse        │Index value of the final color│
│               │(Destination)  │is always the inverse of the  │
│               │               │index of the color of the     │
│               │               │drawing surface.              │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_MERGESRCNOT │Source OR      │Index value of the final color│
│               │(Inverse       │is determined by performing a │
│               │Destination)   │bitwise OR operation on the   │
│               │               │index of the foreground color │
│               │               │and the inverse of the index  │
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_NOTCOPYSRC  │Inverse        │Index value of the final color│
│               │(Source)       │is the inverse of the index of│
│               │               │the foreground color.         │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_MERGENOTSRC │(Inverse       │Index value of the final color│
│               │Source) OR     │is determined by performing a │
│               │Destination    │bitwise AND operation on the  │
│               │               │index of the drawing surface's│
│               │               │color and the inverse of the  │
│               │               │index of the foreground color.│
├───────────────┼───────────────┼──────────────────────────────┤
│FM_NOTMASKSRC  │Inverse (Source│Index value of the final color│
│               │AND            │is the inverse of the FM_AND  │
│               │Destination)   │result.                       │
├───────────────┼───────────────┼──────────────────────────────┤
│FM_ONE         │All 1's.       │RGB value of the final color  │
│               │               │is always 0x00FFFFFF.         │
└───────────────┴───────────────┴──────────────────────────────┘

There are five background mix attributes. For each mix attribute, the index 
value for the background color and the current drawing-surface color (in the 
device's physical color table) are combined using one of the bitwise operators. 

The RGB values are those from the physical color table. When the result of the 
mix attribute's bitwise operation defines a color different from that of both 
the drawing surface and the drawing attribute, the resulting index accesses an 
RGB color in the physical table. The color, therefore, is unpredictable unless 
the logical color table has been realized (using the palette manager). 

The first five of the foreground mix attributes also are available as 
background mix attributes. The background mix attributes are listed in the 
following table. 

Background Mix Attributes 

┌───────────────┬───────────────┬──────────────────────────────┐
│Mix Attribute  │Effect         │Description                   │
├───────────────┼───────────────┼──────────────────────────────┤
│BM_DEFAULT     │Default        │Default background mix        │
│               │               │attribute (Leave-alone).      │
├───────────────┼───────────────┼──────────────────────────────┤
│BM_OR          │OR             │Index value of the final color│
│               │               │is determined by a bitwise OR │
│               │               │operation on the index of the │
│               │               │background color and the index│
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│BM_OVERPAINT   │Overpaint      │Index value of the final color│
│               │               │is that of the background     │
│               │               │color.                        │
├───────────────┼───────────────┼──────────────────────────────┤
│BM_XOR         │Exclusive-OR   │Index value of the final color│
│               │(XOR)          │is determined by a bitwise XOR│
│               │               │operation on the index of the │
│               │               │background color and the index│
│               │               │of the color of the drawing   │
│               │               │surface.                      │
├───────────────┼───────────────┼──────────────────────────────┤
│BM_LEAVEALONE  │Leave-alone    │Index value of the final color│
│               │(Invisible)    │is that of the drawing-surface│
│               │               │color.                        │
└───────────────┴───────────────┴──────────────────────────────┘

The most frequently used foreground mix attributes are FM_OVERPAINT, which is 
the default value, FM_OR, and FM_XOR. The most frequently used background mix 
attributes are BM_LEAVEALONE, which is the default value, and BM_OVERPAINT. 


═══ 10.2.10.1. Overpaint Mix Attribute ═══

When using FM_OVERPAINT, the foreground of the primitive replaces any existing 
drawing in the same area of the presentation page. If the existing drawing is 
yellow, for example, and the new drawing is red, the drawing is red at the 
points of overlap. (This is the default foreground mix attribute.) Because one 
color is replacing another and no color mixing is being performed, the effects 
of the overpaint mix attribute are entirely predictable. This is shown in the 
following figure. 

Overpaint Foreground Mix Attribute 

The circle is drawn on top of the square. At the points of overlap, the output 
is the color of the circle. 

When using BM_OVERPAINT, the primitive background replaces the existing 
drawing. drawing, as shown in the following figure. 

Overpaint Background Mix Attribute 

Using BM_OVERPAINT, the background of the primitive is apparent only if it is 
drawn in a different color from the output-area background. Notice that, in 
this example, the foreground mix attribute is FM_OVERPAINT. 


═══ 10.2.10.2. OR Mix Attribute ═══

When using FM_OR, the foreground of the new primitive is merged with the 
existing drawing at the points of overlap. This is effected by ORing the 
indexes of the overlapping colors to produce a third color. The resulting color 
is unpredictable if the logical color table has not been realized (using the 
palette manager). The OR mix attribute is useful for making the common points 
of two graphics distinct from the points belonging to one of the graphics only, 
as shown in the following figure. 

OR Mix Attribute 

The circle is drawn on top of the square. At the points of overlap, indexes are 
OR'd to produce a new index referencing a new RGB color in the physical color 
table. 

When using the BM_OR attribute, the background of the primitive is merged with 
the existing drawing according to the same rules that apply to the FM_OR 
attribute. 


═══ 10.2.10.3. Exclusive-OR (XOR) Mix Attribute ═══

The FM_XOR attribute enables objects to be drawn in such a way that they can be 
removed easily by simply drawing them a second time using the FM_XOR attribute. 
The FM_XOR attribute is available on display devices only and is useful for 
graphics animation when an application must move an individual graphic and 
completely restore the graphics that it originally overlapped. Typically, an 
application would do the following: 

   1. Draw the graphics object using the FM_XOR attribute. 

   2. Calculate the object's next position. 

   3. Draw the object again in its current position, still using the FM_XOR 
      attribute. This effectively erases it from its current position without 
      destroying the graphics with which it overlaps. 

   4. Draw the object in its new position using the FM_XOR mix attribute. 

 For retained graphics, this sequence can be automated to some extent by 
 defining specific graphics segments as dynamic. Dynamic graphics always are 
 drawn using the FM_XOR attribute, regardless of the current mix attributes. 

 The effects of the FM_XOR attribute are shown in the following figure. 

 Exclusive-OR (XOR) Mix Attribute 

 The circle is drawn on top of the square. At the points of overlap, graphics 
 are not drawn if the two overlapping figures are an identical color. 

 When using the BM_XOR attribute, the background of the primitive is merged 
 with the existing picture according to the same rules that apply to the FM_XOR 
 attribute. 


═══ 10.2.10.4. Leave-Alone Mix Attribute ═══

The leave-alone mix attribute most often is used as a background mix attribute. 
When using the FM_LEAVEALONE attribute, the foreground of the primitive is not 
drawn. When using the BM_LEAVEALONE attribute, the background of the primitive 
is not drawn, as shown in the following figure. 

Leave-Alone Background Mix Attribute The leave-alone background mix attribute 
is the background mix attribute that most often is used for character strings 
and marker primitives. It is generally used with a foreground mix value of 
FM_OVERPAINT. 


═══ 10.2.10.5. Specifying Foreground and Background Mix Attributes ═══

Specify the current foreground mix value for all primitives using GpiSetMix. To 
learn the current foreground mix setting, use GpiQueryMix, which returns the 
current foreground mix setting for a character string primitive. GpiQueryAttrs 
can be used to determine the current foreground and background mix values for a 
single primitive type. 

To specify a background mix value for all primitives, use GpiSetBackMix. 
GpiQueryBackMix returns the current background mix value for a character-string 
primitive. To specify the current foreground and background mix values for a 
single primitive type, call GpiSetAttrs. 

Note:  Not all devices support all of the background and foreground mix 
attributes described. When a device does not support the mix attribute chosen 
by an application, the default mix attribute is used; no error condition is 
raised. DevQueryCaps can be used to determine whether a mix attribute is 
supported on a specific device. 


═══ 10.2.11. Color on Advanced Display Devices ═══

Some devices can display simultaneously a fixed number of colors (typically 
156), chosen from a much larger number of colors (often more than 256000). An 
application can use the palette manager functions to take advantage of the 
extra capabilities of these devices. These functions enable an application to 
change the colors in a device's physical color table and the displayed colors 
rapidly without explicitly redrawing the screen. 

An application can use the CAPS_ADDITIONAL_GRAPHICS option of DevQueryCaps to 
determine whether the display device supports palette functions. 


═══ 10.2.12. Dithering ═══

If an application requests a color not available in the physical color table, 
the operating system can approximate the color by a process called dithering. 
For example, if the physical color table does not contain a light green color 
but does contain a yellow and a green, the operating system can create what 
appears to be light green by mixing yellow pels and green pels. Dithering is a 
variation on the way red, green, and blue color guns illuminate the phosphors 
in a single pel to produce a color that is not pure red, green, or blue (for 
example, yellow). 

The dithering process takes advantage of the way the human eye interprets 
color. If every other pel is set to one color, and all the intermediate pels to 
a different color, together they produce the effect of a third color at normal 
viewing distances. 

The checkerboard effect is just one of the ways in which dithering can be 
implemented. Dithering works only when producing a solid mass of color, such as 
an area fill pattern. It does not have the desired effect on line primitives. 

Dithering is especially important on monochrome devices. By combining various 
combinations of black pels with white pels, the operating system can create 
numerous shades of gray. 

To use only the pure colors defined in the physical color table, that is, to 
prevent color dithering, set LCOL_PURECOLOR in GpiCreateLogColorTable. When 
LCOL_PURECOLOR is set, the nearest available color to the one selected is used. 


═══ 10.2.13. Considerations When Using Monochrome Displays ═══

When a graphic primitive that is drawn in color is displayed on a monochrome 
display, the operating system maps the colors that the application uses to the 
colors supported by the monochrome display. 


═══ 10.2.13.1. Drawing Color Graphics on Monochrome Devices ═══

When mapping color graphics to a monochrome device (screen, printer, or bit 
map), the monochrome device has a reset color and a contrast color. The reset 
color is the color GpiErase clears to and is either black or white. If the 
reset color is black, the contrast color is white, and if the reset color is 
white, the contrast color is black. 

To determine whether the reset color is to be black or white, the color 
retrieved by the index CLR_BACKGROUND from the current logical color table is 
examined. If a logical color table has not been loaded, CLR_BACKGROUND is 
either the paper color on a printer or SYSCLR_WINDOW on a display. If a logical 
color table has been loaded, CLR_BACKGROUND is the color addressed by color 
index 0 on any device. 

If the color retrieved by CLR_BACKGROUND is either white or black, that color 
becomes the reset color. For example, if an application is drawing to a screen, 
has not loaded a color table, and the system colors have not been altered, the 
background color is white, because SYSCLR_WINDOW produces a white background by 
default. In this instance, the contrast color is black. 

If the color retrieved by CLR_BACKGROUND is neither white nor black, the color 
translates to whichever of black and white it is nearest to. As a rule, dark 
colors produce a black background, and pale colors produce a white background. 
For example, if an application is using a loaded color table, or if the color 
retrieved by SYSCLR_WINDOW has been altered (either interactively or by 
WinSetSysColors), CLR_BACKGROUND could be dark gray. In this instance, the 
reset color would be black, and the contrast color would be white. 

When the reset color has been established, the PM applies the following rules 
when mapping color graphics to a monochrome device: 

     Any color graphics drawn in CLR_BACKGROUND, and any graphics defined in 
      the actual reset color (which is either black or white), are drawn in the 
      reset color. Any other graphics are drawn in the contrast color. 

     The index CLR_WHITE produces white, and the index CLR_BLACK produces 
      black, regardless of whether the reset color is black or white. 

     If no color table is loaded and CLR_DEFAULT or CLR_NEUTRAL are used as 
      the foreground color, they produce the contrast color. If they are used 
      as the background color, they produce the reset color. 

     If an application calls GpiQueryNearestColor for a monochrome device, one 
      of the following occurs: 

        -  If the color supplied on input is the reset color, the reset color 
           is returned. 
        -  If the color supplied on input is not the reset color, the contrast 
           color is returned. 


═══ 10.2.13.2. Drawing Color Area Fill Patterns on Monochrome Devices ═══

An area primitive is drawn according to the current foreground and background 
mix attributes and in the current area foreground and area background colors. 

When an application draws a monochrome pattern on a color device, the bits of 
the pattern set to 1 translate to the current area foreground color, and the 0 
bits translate to the current area background color. When the application draws 
a color pattern on a monochrome device, and if the current pattern is anything 
other than PATSYM_DEFAULT or PATSYM_SOLID from the default pattern set, the 
color closest to white is translated into 1 bits. For example, if a pattern of 
diagonal lines is being drawn in which the foreground color is red and the 
background color is cyan, the cyan is translated to white (1 bits) because cyan 
is closer than red is to white. Red, therefore is translated to black (0 bits). 
The effect of translating this color pattern to a monochrome surface is 
summarized as follows: 

Pattern      As 1s and     Color       Monochrome
                0s        Surface       Surface

\   \        10001000     RcccRccc     01110111
 \   \       01000100     cRcccRcc     10111011
  \   \      00100010     ccRcccRc     11011101
   \   \     00010001     cccRcccR     11101110
\   \        10001000     RcccRccc     01110111
 \   \       01000100     cRcccRcc     10111011
  \   \      00100010     ccRcccRc     11011101
   \   \     00010001     cccRcccR     11101110

The original pattern of 1's and 0's is used, however, when deciding which part 
of the pattern is the background and which part is the foreground. Thus, if the 
background mix attribute is BM_LEAVEALONE, the following occurs: 

Pattern      As 1s and     Color      Monochrome
                0s        Surface      Surface

\   \        10001000     R...R...     0...0...
 \   \       01000100     .R...R..     .0...0..
  \   \      00100010     ..R...R.     ..0...0.
   \   \     00010001     ...R...R     ...0...0
\   \        10001000     R...R...     0...0...
 \   \       01000100     .R...R..     .0...0..
  \   \      00100010     ..R...R.     ..0...0.
   \   \     00010001     ...R...R     ...0...0

The 1 bits on the monochrome surface still are interpreted as the background of 
the primitive and are not drawn when the BM_LEAVEALONE attribute is specified. 

When a bit map is used as an area fill pattern, any bit drawn in the current 
area background color is set to 0, and all other bits are set to 1 on a 
monochrome surface. Thus, if the current area background color is blue, all 
blue bits in the bit map are set to 0, and all other bits are set to 1. The 0 
bits constitute the background of the primitive. 

If the pattern is solid (PATSYM_DEFAULT or PATSYM_SOLID in the supplied pattern 
set), the following occurs: 

     If color dithering is switched off, and the application is drawing a 
      color pattern to a color surface, the color nearest the color specified 
      is used. 

     If color dithering is switched on, and the application is drawing a color 
      pattern to a color surface, a combination of colors can be used to 
      achieve the effect of the requested color. For example, if the 
      application chooses pink on a surface where pink is not available, a 
      combination of red and white pels can be used to achieve the effect of 
      the color. 

     If color dithering is switched on, and the application is drawing a color 
      pattern to a monochrome surface, sufficient pels are set to suggest the 
      intensity of the requested color. 

 Dithering can be enabled and disabled using LCOL_PURECOLOR in 
 GpiCreateLogColorTable. 


═══ 10.3. Using Color and Mix Attributes ═══

The color- and mix-attribute functions can be used to perform the following 
tasks: 

     Create a logical color table 

     Determine the format and the starting and ending index values of the 
      current logical color table 

     Determine the index value for an entry in the logical color table that is 
      the closest match to an RGB value 

     Determine the RGB value associated with a particular entry in the logical 
      color table 

     Determine and set the current foreground and background colors 

     Determine and set the current foreground and background mix attributes 


═══ 10.3.1. Creating a Logical Color Table ═══

To create a logical color table, the application creates an array of RGB values 
that replace the existing logical color table, then calls 
GpiCreateLogColorTable, using the LCOL_RESET and LCOLF_CONSECRGB flags. The 
following figure demonstrates this process. 

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR01(void){
    HPS hps;
    LONG alTable[] = {
        0xFFFFFF,        /* White */
        0xFF88FF,
        0xFF8800,
        0xFF8888,
        0xFF0088,
        0x880088,
        0x008888,
        0x00FF88,
        0x00F800,
        0x008800,
        0x000088,
        0x0000F8,
        0x0800F8,
        0x888888,
        0x080808,
        0x000000 };      /* Black */

    GpiCreateLogColorTable(hps,
       LCOL_RESET,                      /* Start with the default      */
       LCOLF_CONSECRGB,                 /* Consecutive RGB values      */
       0,                               /* Starting index in table     */
       sizeof(alTable) / sizeof(LONG),  /* Number of elements in table */
       alTable);
} /* fncCOLR01 */


═══ 10.3.2. Determining the Color-Table Format and Index Values ═══

To determine the format and the starting and ending index values of the current 
logical color table, applications call GpiQueryColorData. The following figure 
is an example of using GpiQueryColorData to determine whether the default 
logical color table is loaded. If so, the code fragment loads a new table. 

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR02(void){
    HPS hps;
    LONG        aClrData[3];
    LONG alTable[16];

    GpiQueryColorData(hps, 3, aClrData);

    if (aClrData[QCD_LCT_FORMAT] == LCOLF_DEFAULT)
        GpiCreateLogColorTable(hps,
           LCOL_RESET,                      /* Start with the default      */
           LCOLF_CONSECRGB,                 /* Consecutive RGB values      */
           0,                               /* Starting index in table     */
           sizeof(alTable) / sizeof(LONG),  /* Number of elements in table */
           alTable);
} /* fncCOLR02 */


═══ 10.3.3. Determining the Index Value of an RGB Value ═══

Applications call GpiQueryColorIndex to find the closest match in a logical 
color table to an RGB value. This function finds the closest match for this RGB 
value in the physical color table, then finds the color in the logical color 
table closest to the color in the physical color table. The function returns 
the index value of that entry in the logical color table. The followiing figure 
is an example of how to determine which index value in the logical color table 
matches the RGB value for pink (0x00FF00FF), then uses that index entry to set 
the foreground color to pink for each of the primitive attributes. 

#define INCL_GPILOGCOLORTABLE
#include <os2.h>

void fncCOLR03(void){
    LONG lIndex;                             /* Logical-color-table index */
    HPS hps;

    lIndex = GpiQueryColorIndex(hps, LCOLOPT_REALIZED, 0x00FF00FF);

    if ((lIndex >= 0) && (lIndex <= 15))     /* Check for valid index     */
        GpiSetColor(hps, lIndex);
} /* fncCOLR03 */


═══ 10.3.4. Setting the Primitive Color Attributes ═══

To set the color attributes for one type of graphics primitive, an application 
uses GpiSetAttrs. To set the color attributes for each type of primitive in a 
presentation space, use GpiSetColor and GpiSetBackColor. The following figure 
shows how to use GpiSetAttrs to set the color attribute of line primitives to 
dark gray. 

#define INCL_GPIPRIMITIVES
#include <os2.h>

void fncCOLR04(void){
    LINEBUNDLE lbnd;     /* Line-primitive attribute structure */
    HPS hps;

    lbnd.lColor = CLR_DARKGRAY;

    GpiSetAttrs(hps, PRIM_LINE, LBB_COLOR, 0, &lbnd);
} /* fncCOLR04 */

The following figure is an example of how to use GpiSetColor to set the 
foreground color attribute to dark gray in all of the primitives. 

#include <os2.h>

void fncCOLR05(void){
    HPS hps;

    GpiSetColor(hps, CLR_DARKGRAY);
} /* fncCOLR05 */


═══ 10.3.5. Creating a Palette ═══

To create a palette, an application must first call DevQueryCaps with the 
CAPS_ADDITIONAL_GRAPHICS option to determine whether the device supports 
palette functions. Next the application creates an array of RGB values or an 
array of RGB2 structures, then calls GpiCreatePalette. Next the applications 
calls GpiSelectPalette to select the palette for the presentation space and 
calls WinRealizePalette to map the RGB values to device colors for subsequent 
drawing. When the application is finished drawing, it calls GpiSelectPalette to 
disassociate the presentation space and the palette. Then it deletes the 
palette by calling GpiDeletePalette. 

The following figure demonstrates these steps. 

#define INCL_GPILOGCOLORTABLE
#define INCL_GPIBITMAPS
#include <os2.h>
void fncCOLR06(void){
    COLOR clrCurrent;
    HPAL hpal;
    HDC hdc;
    HPS hps;
    HAB hab;
    HWND hwnd;
    POINTL aptl[2], ptl;
    LONG cSimulColors, lPalSupport;
    SHORT j;
    RGB2 *prgb2ColorData;

    /* Determine how many colors the device can display at once.              */
    DevQueryCaps(hdc, CAPS_COLORS, 1, &cSimulColors);

    /* Determine if the device supports palette manager functions.            */
    DevQueryCaps(hdc, CAPS_ADDITIONAL_GRAPHICS, 1, &lPalSupport);

    /* Allocate space for the array of RGB2 structures.                       */
    DosAllocMem((PPVOID)&prgb2ColorData, cSimulColors * sizeof(RGB2), fALLOC);

    /* Fill the array of RGB2 structures with as many different               */
    /*    shades of blue as the device will support.                          */

    clrCurrent = 0x000000FF;
    for (j = 0; j < cSimulColors; j++) {
        prgb2ColorData[j].bRed = 0;
        prgb2ColorData[j].bGreen = 0;
        prgb2ColorData[j].bBlue = clrCurrent;
        prgb2ColorData[j].fcOptions = 0;
        clrCurrent = clrCurrent > 0 ? --clrCurrent : 0x000000FF;
    }

    if (lPalSupport & CAPS_PALETTE_MANAGER) {
        hpal = GpiCreatePalette(hab,       /* Create palette                  */
               0L,
               LCOLF_CONSECRGB,            /* Format of color table entries   */
               cSimulColors,               /* Number of entries in table      */
               (PULONG) prgb2ColorData);   /* Pointer to color table          */
    }

    GpiSelectPalette(hps, hpal);
    WinRealizePalette(hwnd, hps);
    GpiSelectPalette(hps, NULLHANDLE);     /* Restore default physical colors */
    GpiDeletePalette(hpal);                /* Delete palette                  */
} /* fncCOLR06 */