## Presentation Device Driver Reference for OS/2

[prev][next][parent][TOC]

### Dithering / Color Mapping Interface

This is the interface to let devices provide their own color mapping and dithering routines, that is, override the graphic system's defaults or provide routines for formats not supported by the graphics system (for example, a 32-bit 10R 10G 10B format for instance).

Notes

1.A device can specify a logical color format (via Device Capabilities) which is different from their physical color format (Device Surface ulBpp).

2.External format is the format in which an OS/2 application provides images. 1/4/8/24 Bpp, BGR, doubleword aligned. Internal format is the format that the application image is converted into relative to the device' s logical format.

A device has the option to dither at external to internal conversion time ( this is the only option for color conversion) or at logical to physical.

Note: A device can specify KEEP_EXTERNAL_FORMAT, in which case an external to physical conversion could take place. This should not matter to the conversion-handling routine because all the information in the image information structure should suffice in performing the conversion.

You can:

Select dithering.

Modify system dithering routines.

Provide your own dithering routines.

Provide support for unsupported system formats.

Selecting Dithering

Dithering is selected via:

GDM_EXT2INT_DITHER

GDM_LOG2PHY_DITHER

Add the appropriate GDM_DITHER flag into the fExt2IntSup and/or fLog2PhysSup fields (dither could be done at both levels).

Modifying System Dithering Routines

You can change just the dithering defaults for that requested type of dithering without providing funtion. To accomplish that, provide either a pExt2IntDI or a pLog2PhysDI structure.

Note: The whole structure must be filled out.

Below are two currently used system dither structures:

      MATRIXDITHERINFO                  System Default Values

        ULONG       ulLength           sizeof(MATRIXDITHERINFO)

        ULONG       ulType             GDM_MATRIX_DITHER

        ULONG       fOptions           00

        ULONG       ulIntensity        00

        BYTE        bRedWt             25

        BYTE        bGreenWt           60

        BYTE        bBlueWt            15

        BYTE        bPad               00

        SIZEL       szMatrix           N/A

        BYTE        bHalftone[1]       N/A

      DIFFUSIONDITHERINFO

        ULONG       ulLength           sizeof(DIFFUSIONDITHERINFO)

        ULONG       ulType             GDM_ERRORDIF_DITHER

        ULONG       fOptions           JJN_DIF

        ULONG       ulIntensity        00

        BYTE        bRedWt             25

        BYTE        bGreenWt           60

        BYTE        bBlueWt            15

        BYTE        bPad               00

        PBYTE       pBuffer            N/A

        SIZEL       szFilter           N/A

        BYTE        bFilterArry[1]     N/A

      JJN_DIF        Currently only one supported

Providing Your Own Dithering Routines

To provide your own dither routines, place the GDM_USERDEF_DITHER in either the fExt2IntSup and/or fLog2PhysSup fields. Then provide a function for pfnDither:

      pfnDither(PDITHERINFO pdi, PIMAGEINFO pii, ULONG ulFlags);

Where pdi = either pExt2IntDI or pLog2PhysDI. This should be your own allocated structure. For pii, see the detailed information about the IMAGEINFOS structure which follows.

Providing Support for Unsupported System Formats

To provide your own color conversion routines, place the GDM_COLOR_CONVERT in the fExt2IntSup field, and provide the three required functions in the COLORCONVERTINFO structure:

      pfnRGB2ToPhyIndex  (ULONG ulClr)

      pfnPhyIndexToRGB2  (ULONG ulClr)

      pfnConvert         (PIMAGEINFO pimginfo)

Data Structures

     COLORCONVERTINFO

       ULONG       ulLength                           sizeof ( COLORCONVERTINFO )

        ULONG         ulType                                GDM _ COLOR _ CONVERT

        ULONG         ulOptions                             00

        ULONG         ( *   APIENTRY   pfnRGB2ToPhyIndex )   ( )   N / A   -   Mapping   from   RGB   to   Phy   index

        ULONG         ( *   APIENTRY   pfnPhyIndexToRGB2 )   ( )   N / A   -   Mapping   from   Phy   index   to   RGB

        ULONG         ( *   APIENTRY   pfnConvert )          ( )   N / A   -   Actual   Convert   Bits   Function

      IMAGEINFOS

        PPOINTL       pptlSrc

        PPOINTL       pptlDst

        ULONG         ulSrcBpp                  Source   image   bits   per   pixel

        ULONG         ulSrcBytesPerLine        Count   of   bytes   per   scan   line   ( includes   padding )

        PBYTE         pbSrcBits                 Pointer   to   source   data

        ULONG         ulcSrcClrs                Count   of   source   colors

        ULONG         ulSrcClrType              Source   color   format   see   below

        PRGB2         pargb2Src                 Pointer   to   source   color   table

        ULONG         ulTrgBpp                  Target   image   bits   per   pixel

        ULONG         ulTrgBytesPerLine        Count   of   bytes   per   scan   line   ( includes   padding )

        PBYTE         pbTrgBits                 Pointer   to   target   data

        ULONG         ulcTrgClrs                Count   of   target   colors

        ULONG         ulTrgClrType              Source   target   format   see   below

        PRGB2         pargb2Trg                 Pointer   to   target   color   table

        ULONG         ulOptions                 see   below

IMAGEINFOS Color Types

When ulBpp <= 8:

      COLOR_RGB2            Color is in RGB2  (default)

      COLOR_RGB             Color is in RGB

When ulBpp = 24:

      COLOR_24BIT_BGR       1st byte=blue, 2nd byte=green 3rd byte=red  (default)

      COLOR_24BIT_RGB       1st byte=red,  2nd byte=green 3rd byte=blue

When ulBpp = 16:

      COLOR_16BIT_565_BGR   blue - 5 bits, green - 6 bits, red - 5 bits   (default)

                            ---------------------------------

                            |b|b|b|b|b|g|g|g|g|g|g|r|r|r|r|r|

                            ---------------------------------

      COLOR_16BIT_565_RGB   red - 5 bits, green - 6 bits, blue - 5 bits

                            ---------------------------------

                            |r|r|r|r|r|g|g|g|g|g|g|b|b|b|b|b|

                            ---------------------------------

      COLOR_16BIT_1555_BGR  overlay - 1, red - 5 bits, green - 5 bits, blue - 5 bits

                            ---------------------------------

                            |o|b|b|b|b|b|g|g|g|g|g|r|r|r|r|r|

                            ---------------------------------

      COLOR_16BIT_1555_RGB  overlay - 1, red - 5 bits, green - 5 bits, blue - 5 bits

                            ---------------------------------

                            |o|r|r|r|r|r|g|g|g|g|g|b|b|b|b|b|

                            ---------------------------------

When ulBpp = 32:

      COLOR_32BIT_BGR       1st byte=blue, 2nd byte=green 3rd byte=red,  4th byte=not used

      COLOR_32BIT_RGB       1st byte=red,  2nd byte=green 3rd byte=blue, 4th byte=not used

IMAGEINFO Options

      IMAGEINFO_CLR_TO_MONO_BG_EXACT     Src pels that are trg BG clr -> 1

                                         all other pels               -> 0

      IMAGEINFO_CLR_TO_MONO_BG_EXACT_INV Src pels that are trg BG clr -> 0

                                         all other pels               -> 1

                                         Nearest color match.

                                           Source pels that are close to target BG

                                           color become target BG color.

                                           All other pels become target FG color.

      IMAGEINFO_CLR_TO_MONO_BG_MAP       Src pels that are close to trg BG clr -> 1

                                         all other pels                        -> 0

      IMAGEINFO_CLR_TO_MONO_BG_MAP_INV   Src pels that are close to trg BG clr -> 0

                                         all other pels                        -> 1

      IMAGEINFO_SRC_Y_FLIP               Source is going Y negative direction

                                            i.e. second line = first line - ulBytesPerLine.

      IMAGEINFO_TRG_Y_FLIP               Target is going Y negative direction