Software Collection (I)/TOOLS.iso/d07/18.img/DDHELP.DAT

Text File | 1992-03-31 | 26.6 KB | 628 lines

(C) Copyright Microsoft Corporation 1981-1990.  All rights reserved.

         DEVICE DRIVER GUIDANCE FOR Microsoft OS/2 VERSION 1.3
         ===============================================

*****************************************************************
* The following term, used in this file, is the trademark of the *
* IBM Corporation in the United States and/or other countries:  *
*                                                               *
*      IBM                                                      *
*                                                               *
*****************************************************************

This document contains programming information on the following
topics:

 -  Improvements to the color palette with IBMBGA.DLL
 -  8514 bit map performance
 -  Changes to the canceling of print jobs
 -  Printing using an OD_DIRECT device context
 -  Writing device drivers to handle monochrome bit maps.

*****************************************************************
*                                                               *
*       IMPROVEMENTS TO THE COLOR PALETTE WITH IBMBGA.DLL       *
*                                                               *
*****************************************************************

The IBMBGA.DLL driver now has improved support for displaying
color and gray-level images.  This section describes how the
changes affect the programmer, and gives information about the
redesign of the color palette.

The changes made to IBMBGA.DLL are:

1. Thirty two 'pure' gray-levels are available in the 256-
   color palette of an IBM 8514/A display adapter with
   extended memory.

2. The range of red hues is reduced to make room for the
   gray-levels.

3. The metrics of the logical color table is changed from
   'Linear RGB' to 'Psychometric RGB'.

4. The GpiRealizeColorTable function is supported.

These changes will make icons that were designed for the old
color table appear darker.  Tables 1 and 2 below show the mapping
from (1) the old 8-bit color values to the new and (2) the new
8-bit color values to the old.  Use these tables to determine
which colors your icons should use to map into the new color
table.


COLOR PALETTE
-------------

The 8514/A display adaptor, with its full memory, allows a
palette of 256 entries at its maximum resolution.  Each
entry has 18-bits of color information, 6-bits each for the
red, green, and blue primary colors, so each entry can be
set to any one of the 256K values (64 x 64 x 64) in the
logical color table.

In previous versions of IBMBGA.DLL, the default palette used
a permutation of pure colors (8 reds, 8 greens, and 4 blues)
that gave only two pure grays.  The actual values used for
each pure color were chosen to give a linear progression
of measured intensity from minimum to maximum (Linear RGB).

In this version of IBMBGA.DLL, the default palette contains
32 different pure grays and a range of colors derived from
permutations of 7 reds, 8 greens, and 4 blues.  The actual
values used for each pure color are chosen to give a linear
progression of perceived intensity from minimum to maximum
(Psychometric RGB).

Color-mapping from a logical color table, or from a bit-map
color table, to the default palette has been changed so that
all colors that have equal red, green, and blue values map
directly into the most appropriate pure grey.


GpiRealizeColorTable
--------------------

The GpiRealizeColorTable function has been implemented in
IBMBGA.DLL so that an application program can achieve the
highest possible color accuracy in its screen presentation.
Because calls to this function affect everything on the screen,
the calling application must ensure that:

1. If you realize the RGB value at index 0 or 255, you must
   ensure that 0 and 255 have different RGB values.  These
   are the pointer outline and interior; they must be different
   to ensure that the pointer is visible against any color.
   (Note that color tables with format=LCOLF_RGB cannot
   be realized.)

2. The call to GpiRealizeColorTable is made only when the
   application's window is maximized and has the focus.

3. The screen is repainted after making the call to
   GpiRealizeColorTable.  (Note that repainting the screen
   will not change the colors of icons and other bit maps;
   bit-map colors are not remapped by the system.)

4. GpiUnrealizeColorTable is called when the application's
   window is no longer maximized or loses the focus.

5. The screen is repainted after making the call to
   GpiUnRealizeColorTable.

If an application that calls GpiRealizeColorTable does not
follow these guidelines, the end-user may have to reboot
the system to restore the normal colors.

The GpiRealizeColorTable function does not simply scale down
the logical color values into the physical color palette,
it makes corrections as appropriate to give consistent results
according to the degree of accuracy allowed by the rendering
technique:

   'Pure' Color - The system renders the color using the nearest
    color found in the default physical palette.

   'Dithered' Color - The system will, if there is no matching
    pure color, render the dithered color by mixing proportions
    of suitable physical colors.

   'Realizable' Color - The system renders the color as it is
    defined in the 'realized' physical palette.


Realizable Color Tables
-----------------------

Note that the realizable (LCOL_REALIZABLE) property of a
logical color table is lost if the presentation space is
reassociated.  It is necessary to create the logical color
table again in order to re-establish the realizable
property.  This is only necessary if the presentation space
is associated with a device that supports realization.

Also, GpiUnrealizeColorTable should be issued before a
presentation space (that currently has a realized logical
color table) is dissociated or reassociated, that is before
any GpiAssociate call referencing that presentation space.

For example, the following sequence of calls could be used:

   GpiAssociate            .. with a screen device context
   GpiCreateLogColorTable  .. with LCOL_REALIZABLE
   GpiRealizeColorTable
     .
     .                     .. draw to display
     .
   GpiUnrealizeColorTable
   GpiAssociate            .. with a printer device context
     .
     .                     .. draw to printer
     .
   GpiAssociate            .. with a screen device context
   GpiCreateLogColorTable  .. with LCOL_REALIZABLE
   GpiRealizeColorTable
     .
     .                     .. draw to display
     .


GpiPlayMetafile
---------------

To ensure compatibility with existing applications, and
to adequately enable the function for new applications, the
options for GpiPlayMetafile have been changed; the
CREA_REALIZE option is, and will continue to be, ignored and
a CREA_DOREALIZE has been added.  When CREA_DOREALIZE is
specified, the color table is loaded with the realizable
option and then realized.  Note that the application must
subsequently unrealize the color table as per the above
guidelines.


INCLUDE and HEADER FILES
------------------------

The definition of CREA_DOREALIZE should be added to the
PMGPI.INC and PMGPI.H header files.

In PMGPI.INC, insert the following line immediately
after the line defining CREA_REALIZE:

CREA_DOREALIZE;EQU;3

In PMGPI.H, insert the following line immediately
after the line defining CREA_REALIZE:

#define CREA_DOREALIZE 3L


CONVERSION TABLES
-------------------

The following tables show the mapping between the old and
new values for the 256 values in the 8-bit fields of the
logical color table.  Because of the change from Linear-RGB
to Psychometric-RGB, this mapping is not always one-to-one.

-------------------------------------------------------------
Table 1.  Linear to Psychometric

 Lin  Psy        Lin  Psy        Lin  Psy        Lin  Psy
 ---  ---        ---  ---        ---  ---        ---  ---
   0    0         64  146        128  194        192  228
   1    6         65  147        129  195        193  229
   2   18         66  148        130  196        194  229
   3   26         67  149        131  196        195  230
   4   33         68  150        132  197        196  230
   5   39         69  151        133  197        197  231
   6   44         70  151        134  198        198  231
   7   48         71  152        135  198        199  232
   8   52         72  153        136  199        200  232
   9   56         73  154        137  200        201  232
  10   60         74  155        138  200        202  233
  11   63         75  156        139  201        203  233
  12   66         76  157        140  201        204  234
  13   69         77  158        141  202        205  234
  14   72         78  159        142  203        206  235
  15   74         79  159        143  203        207  235
  16   77         80  160        144  204        208  236
  17   79         81  161        145  204        209  236
  18   81         82  162        146  205        210  236
  19   84         83  163        147  205        211  237
  20   86         84  163        148  206        212  237
  21   88         85  164        149  206        213  238
  22   90         86  165        150  207        214  238
  23   92         87  166        151  208        215  239
  24   94         88  167        152  208        216  239
  25   96         89  167        153  209        217  240
  26   97         90  168        154  209        218  240
  27   99         91  169        155  210        219  240
  28  101         92  170        156  210        220  241
  29  103         93  171        157  211        221  241
  30  104         94  171        158  211        222  242
  31  106         95  172        159  212        223  242
  32  107         96  173        160  212        224  242
  33  109         97  174        161  213        225  243
  34  110         98  174        162  213        226  243
  35  112         99  175        163  214        227  244
  36  113        100  176        164  215        228  244
  37  115        101  176        165  215        229  245
  38  116        102  177        166  216        230  245
  39  117        103  178        167  216        231  245
  40  119        104  179        168  217        232  246
  41  120        105  179        169  217        233  246
  42  121        106  180        170  218        234  247
  43  123        107  181        171  218        235  247
  44  124        108  181        172  219        236  247
  45  125        109  182        173  219        237  248
  46  126        110  183        174  220        238  248
  47  128        111  183        175  220        239  249
  48  129        112  184        176  221        240  249
  49  130        113  185        177  221        241  249
  50  131        114  185        178  222        242  250
  51  132        115  186        179  222        243  250
  52  133        116  187        180  223        244  251
  53  134        117  187        181  223        245  251
  54  136        118  188        182  224        246  251
  55  137        119  189        183  224        247  252
  56  138        120  189        184  225        248  252
  57  139        121  190        185  225        249  253
  58  140        122  191        186  225        250  253
  59  141        123  191        187  226        251  253
  60  142        124  192        188  226        252  254
  61  143        125  192        189  227        253  254
  62  144        126  193        190  227        254  255
  63  145        127  194        191  228        255  255

-------------------------------------------------------------
Table 2.  Psychometric to Linear

 Psy  Lin        Psy  Lin        Psy  Lin        Psy  Lin
 ---  ---        ---  ---        ---  ---        ---  ---
   0    0         64   11        128   47        192  124
   1    1         65   12        129   48        193  126
   2    1         66   12        130   49        194  128
   3    1         67   12        131   50        195  129
   4    1         68   13        132   51        196  131
   5    1         69   13        133   52        197  132
   6    1         70   13        134   53        198  134
   7    1         71   14        135   54        199  136
   8    1         72   14        136   54        200  138
   9    1         73   15        137   55        201  139
  10    1         74   15        138   56        202  141
  11    1         75   15        139   57        203  143
  12    1         76   16        140   58        204  145
  13    2         77   16        141   59        205  146
  14    2         78   17        142   60        206  148
  15    2         79   17        143   61        207  150
  16    2         80   17        144   62        208  152
  17    2         81   18        145   63        209  154
  18    2         82   18        146   64        210  155
  19    2         83   19        147   65        211  157
  20    2         84   19        148   66        212  159
  21    2         85   20        149   67        213  161
  22    2         86   20        150   68        214  163
  23    3         87   21        151   70        215  165
  24    3         88   21        152   71        216  167
  25    3         89   22        153   72        217  169
  26    3         90   22        154   73        218  171
  27    3         91   23        155   74        219  173
  28    3         92   23        156   75        220  175
  29    3         93   24        157   76        221  177
  30    3         94   24        158   77        222  179
  31    4         95   25        159   79        223  181
  32    4         96   25        160   80        224  183
  33    4         97   26        161   81        225  185
  34    4         98   26        162   82        226  187
  35    4         99   27        163   83        227  189
  36    4        100   28        164   85        228  191
  37    5        101   28        165   86        229  193
  38    5        102   29        166   87        230  196
  39    5        103   29        167   88        231  198
  40    5        104   30        168   90        232  200
  41    5        105   31        169   91        233  202
  42    6        106   31        170   92        234  204
  43    6        107   32        171   94        235  207
  44    6        108   32        172   95        236  209
  45    6        109   33        173   96        237  211
  46    6        110   34        174   98        238  214
  47    7        111   34        175   99        239  216
  48    7        112   35        176  100        240  218
  49    7        113   36        177  102        241  220
  50    7        114   37        178  103        242  223
  51    8        115   37        179  105        243  225
  52    8        116   38        180  106        244  228
  53    8        117   39        181  108        245  230
  54    8        118   39        182  109        246  232
  55    9        119   40        183  110        247  235
  56    9        120   41        184  112        248  237
  57    9        121   42        185  113        249  240
  58   10        122   43        186  115        250  242
  59   10        123   43        187  116        251  245
  60   10        124   44        188  118        252  247
  61   10        125   45        189  120        253  250
  62   11        126   46        190  121        254  252
  63   11        127   47        191  123        255  255

-------------------------------------------------------------
*****************************************************************
*                                                               *
*                   8514 BIT MAP PERFORMANCE                    *
*                                                               *
*****************************************************************

To obtain fast setting of 8 bit per pel bit-map data into 8 bit
per pel bit maps when using the 8514 display driver, preprocess
the bit-map data to use a logical color table that exactly
matches that of the default PM palette for the driver.  This
logical color table for the default palette can be constructed
using GpiQueryRealColors with a start value of 0 and a count of
256, leaving the ordering of the RGB values and the values
themselves unchanged.

*****************************************************************
*                                                               *
*           CHANGES TO THE CANCELING OF PRINT JOBS              *
*                                                               *
*****************************************************************

This section describes the interaction between a device driver
and the spooler when a print job is canceled.

A print job can be canceled either by the end-user or by an
application.  The processing for each case is described below.

Note: Some output may be printed after the canceled job is
      removed from the Print Manager list.  In previous versions
      of OS/2, no output was sent to the printer after the job
      was removed from the Print Manager list.

The following sections describe the processing carried out by
the device driver when a print job is ended.

The application ends a job while spooling
-----------------------------------------

1.   The application calls DevEscape(DEVESC_ABORTDOC).

2.   The device driver calls SplQmAbortDoc and flags that the
     device context has been aborted (SplQmAbort should not be
     called).

3.   The application calls either DevEscape(DEVESC_STARTDOC)
     to start another job on the same device context, or
     DevCloseDC to close the device context.

When DevEscape(DEVESC_ABORTDOC) is issued, the spooler sets
a flag and returns immediately.  The spooler then cancels the
job when a Prt... call returns.  In previous versions of OS/2,
the spooler waited until the job had been canceled before
returning.

The end-user cancels a job
--------------------------

1.   The spooler calls SplQpControl(SPLC_ABORT).

2.   The print processor calls DevEscape(DEVESC_ABORTDOC)
     (the device driver must be able to accept DEVESC_ABORTDOC
     while processing DEVESC_RAWDATA).

3.   The device driver sets a flag to show that the job should
     be stopped.

If the next Prt... call returns without an error, the device
driver sends a form feed and calls PrtClose.  To ensure that
the printer is not in graphics mode, the device driver can also
send some null data.

If the next Prt... call returns with an error, the device
driver behaves in the same way as it does when the printer
runs out of paper, or is not online (see below).

The printer runs out of paper or is not online
----------------------------------------------

1.    PrtWrite fails and returns an error to the device driver.

2.    After the specified timeout, the device driver calls:

        SplMessageBox(LogAddr,
           SPLINFO_DDERROR | SPLINFO_ERROR | SPLINFO_USERINTREQD,
             SPLDATA_PRINTERJAM, NULL, NULL, 0, MB_RETRYCANCEL)

     This produces a message box to warn the end-user:

     -  If the user selects Cancel, the driver calls PrtAbort and
        PrtClose.

     -  If the user selects Retry, the driver calls PrtWrite
        again, unless the job has been canceled since the error.

Note: The spooler ignores all PrtWrite operations after PrtAbort
      is called.  After the device driver has called PrtClose,
      it returns the errors to the caller (the graphics
      programming interface for PM_Q_STD data, or the print
      processor for PM_Q_RAW data) until the device context is
      closed.

*****************************************************************
*                                                               *
*          PRINTING USING AN OD_DIRECT DEVICE CONTEXT           *
*                                                               *
*****************************************************************

Applications that use an OD_DIRECT printer device context to
print data must issue a pair of escape functions to "bracket"
each print job.

Note: Queue drivers are special applications that must
      always print data using an OD_DIRECT device context.

The escape functions are:

     DevEscape(DEVESC_STARTDOC)
     DevEscape(DEVESC_ENDDOC)

The sequence of calls that you must use is:

GpiCreatePS        /* Create a presentation space.             */
DevOpenDC          /* Create an OD_DIRECT device context.      */
GpiAssociate       /* Associate the presentation space with    */
                   /* the device context.                      */
DevEscape(DEVESC_STARTDOC)
                   /* Start the print job.                     */
     .
     .
     .
Gpixxxxxx calls    /* Draw the output data.                    */
     .
     .
     .
DevEscape(DEVESC_ENDDOC)
                   /* End the print job.                       */
GpiAssociate(hps,NULL)
                   /* Disassociate the presentation space from */
                   /* the device context.                      */
GpiDestroyPS       /* Destroy the presentation space.          */
DevCloseDC         /* Close the device context.                */

The sequence of calls is the same when you print using an
OD_QUEUED device context.


*****************************************************************
*                                                               *
*     WRITING DEVICE DRIVERS TO HANDLE MONOCHROME BIT MAPS      *
*                                                               *
*****************************************************************

This section describes the rules for handling monochrome bit
maps in printer drivers and display drivers.  To ensure that the
images produced from the same sequence of bit-map actions do not
vary from driver to driver, they must follow the behavior of the
Video Graphics Adapter (VGA) display driver.

Monochrome bit maps can be regarded as:

 - References to a color table
 - Logic values
 - References to the current image attributes
   foreground/background colors (see GpiSetAttrs).


BIT MAPS AND COLOR TABLES
-------------------------
Device drivers must be consistent in the way they deal with the
GpiSetBitmapBits, GpiQueryBitmapBits, and GpiCreateBitmap calls.

When you use the GpiCreateBitmap or GpiSetBitmapBits calls to
create a bit map, you specify a color table.  The device driver
adjusts the internal bit-map data structure to reflect the image
defined by the supplied pel values and the corresponding color
table.

The VGA display driver represents white by the value 1 and black
by the value 0 in its internal monochrome bit-map data structure.
If you specify a color table that defines white as 0 and black as
1, the display driver complements the bit values before it stores
them in its bit-map structure.  A subsequent call to
GpiQueryBitmapBits returns a set of pel values together with a
color table.  Thus the returned values may not match those
supplied by GpiSetBitmapBits or GpiCreateBitmap.  Taken together
with the color tables however, the complete return value matches
the supplied data.  Therefore, the color table returned by the
GpiQueryBitmapBits call with a monochrome bit map always
represents white by the value 1 and black by the value 0.


BIT MAPS AS LOGIC VALUES
------------------------
When you use the GpiBitBlt call to copy data between a source and
a destination bit map with the same number of bits per pel, the
pel values in the internal bit-map structures are treated as
logic values.  For example, the ROP_SRCAND raster operation
combines the pel values using the AND machine instruction.

This aspect of the GpiBitBlt call forces a common representation
value for white and black; therefore all device drivers must
follow the VGA display driver and represent the color white by
the value 1 and the color black by the value 0.

A ROP_SRCAND function issued to the VGA display driver maps:

 - White and white to white
 - White and black to black
 - Black and white to black
 - Black and black to black

If this rule is not followed, the various raster operations
(ROP_SRCAND for example) generate different results in the memory
bit maps supported by different device drivers.


BIT MAPS AND THE IMAGE ATTRIBUTES
---------------------------------
When a GpiBitBlt operation occurs between source and destination
bit maps that differ in the number of bits per pel, color
conversion occurs.  For a monochrome source bit map, the color
conversion maps 1-bits in the source bit map into the foreground
color of the image attributes, and 0-bits to the background color
of the image attributes.

Because the VGA display has a 16-color surface, the VGA display
driver performs color conversion when you use the GpiBitBlt call
to copy a monochrome bit map to it.  Printer drivers must follow
this behavior when a monochrome bit map is copied to their
display surface.  Thus color conversions must always use the
current image attribute colors, even when the display surface is
another monochrome bit map.

Note: This rule applies only to GpiBitBlt operations to the image
      surface of the device driver, not to operations to a memory
      bit map.


SUMMARY OF RULES FOR DEVICE DRIVERS
-----------------------------------
To make the image behavior of device drivers conform to that of
the VGA display driver:

 - Device drivers must represent the color white by the value 1
   and the color black by the value 0 in their internal bit-map
   representations.

 - Device drivers must always color-convert the source bit map
   according to the current image attributes when a GpiBitBlt
   operation is done from a monochrome memory bit map to a
   display surface bit map.

Exceptions
----------
The following device drivers do not follow these rules:

 IBMNULL.DRV           IBM52011.DRV
 IBM3852.DRV           IBM52012.DRV
 IBM5152.DRV           IBM5216.DRV
 IBM5182.DRV


SUMMARY OF RULES FOR APPLICATIONS
---------------------------------
 - Applications must supply correct color tables for the
   GpiCreateBitmap and GpiSetBitmapBits calls.

 - Applications must ensure that the foreground and background
   colors of the image attributes are set for GpiBitBlt
   operations from monochrome memory bit maps to the display
   surface of a device.

Note: Applications that do not follow these rules may give
      unpredictable output.

                     ----- End of document -----