overview.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
About Color and Mix Modes (1.2)
Using Section  Function Group                     Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
                         About Color and Mix Modes
 
This topic describes color and mix modes and their use in MS OS/2
applications. You should also be familiar with the following topics:
 
    Presentation spaces and device contexts
    Line and arc primitives
    Area primitives
    Fonts and character primitives
    Marker primitives
 
Color and mix modes are two primitive attributes. The color attribute
describes a line, arc, character, marker, area, or image color before it is
combined with the color on the drawing surface. The mix-mode attribute
describes how the system combines a primitive's color with the color of the
drawing surface. Some primitives have foreground and background color
attributes. For instance, the character primitive has a foreground color
attribute that specifies the color of the character and a background color
attribute that specifies the color surrounding the character. The primitives
that have foreground and background attributes also have foreground and
background mix modes.
 
To understand color, it is important to understand several principles of
color devices. Most color devices can generate three fundamental colors:
red, green, and blue. On some devices, each of these three colors
corresponds to a color plane──for example, a red pel is visible when a pel
in the red plane is on and the corresponding pels in the green and blue
planes are off. On other devices, there is only one color plane, and each
pel contains a red, a green, and a blue section──for example, a red pel is
visible when the red section of that pel is on and the green and blue
sections are off. By combining the three fundamental colors, a device can
obtain five additional colors, for a total of eight. These eight colors, and
the combinations that produce them, are as follows:
 
Resulting color  Combined colors
────────────────────────────────────────────────────────────────────────────
Black            Red, green, and blue are off.
Red              Red is on; green and blue are off.
Green            Green is on; red and blue are off.
Blue             Blue is on; red and green are off.
Pink             Red and blue are on; green is off.
Cyan             Blue and green are on; red is off.
Yellow           Red and green are on; blue is off.
White            Red, green, and blue are on.
 
Color and RGB Values
 
In MS OS/2, the red, green, and blue components of a color are either stored
in an RGB structure or stored as a long integer (32-bit) value. The RGB
structure has the following format:
 
typedef struct _RGB {     /* rgb */
    BYTE bBlue;
    BYTE bGreen;
    BYTE bRed;
} RGB;
 
The RGB value has the following format:
 
0x00RRGGBB.
 
Each field in the RGB structure and each of the last three bytes in the RGB
value specify a color intensity, in the range 0 through 255, 0 being the
lowest intensity, 255 the highest. If a field or byte contains 0, its
corresponding color is not visible; if a field or byte contains 128, the
color is pale; and if a field or byte contains 255, the color is as intense
as the device allows. If all the fields or bytes are set to 0, the
corresponding color is black. Similarly, if all the fields or bytes are set
to 255, the corresponding color is white.
 
The following list shows the RGB value associated with each of the eight
fundamental colors:
 
Color   Associated RGB value
────────────────────────────────────────────────────────────────────────────
White   0x00FFFFFF
Yellow  0x00FFFF00
Pink    0x00FF00FF
Cyan    0x0000FFFF
Blue    0x000000FF
Green   0x0000FF00
Red     0x00FF0000
Black   0x00000000
 
Color Tables
 
A color table is an array of RGB values. There are two kinds of color
tables: physical (used by device drivers) and logical (used by
applications). The physical color table contains RGB values representing the
available colors on a device. The logical color table contains RGB values
representing the colors that an application would prefer to use. You can
determine which colors are in the physical color table by calling the
GpiQueryRealColors function. You can determine which colors are in the
current logical color table by calling the GpiQueryLogColorTable function.
 
The following list contains the index values and colors found in a logical
color table:
 
Index  Color
────────────────────────────────────────────────────────────────────────────
0      Device's background color (white)
1      Blue
2      Red
3      Pink
4      Green
5      Cyan
6      Yellow
7      Neutral color (black)
8      Dark gray
9      Pale blue
10     Pale red
11     Pale pink
12     Dark green
13     Dark cyan
14     Brown
15     Pale gray
 
The value you place in the color field of a primitive-attribute structure
(by using GpiSetAttrs) is an index into the logical color table. When MS
OS/2 draws the primitive, it searches the physical color table for a color
that is the closest approximation to this color index. MS OS/2 then uses
this approximate color to draw with.
 
You can replace the default logical color table with a new color table by
calling the GpiCreateLogColorTable function. You can also use this function
to reset the logical color table to its original values. Either way, once
you create a new logical color table (or reset it to its original values),
it becomes part of the application's presentation space.
 
For a given device, you can determine the maximum size of the logical color
table by using the DevQueryCaps function. This function also returns the
maximum number of distinct colors available on a particular device.
 
Color Output and Mix Modes
 
When an application draws a line, arc, character, marker, area, or image, MS
OS/2 uses a mix mode to determine the color that appears on a video display,
printer, or plotter. A mix mode is a bitwise operation on the color indices
in a device's physical color table. For example, suppose an application has
set the lColor field in the LINEBUNDLE structure to CLR_BLUE and the
usMixMode field in the same structure to FM_OR. The current drawing-surface
color is CLR_BACKGROUND. The CLR_BLUE entry corresponds to the color blue in
both the presentation space's logical color table and the device's physical
color table. The CLR_BACKGROUND entry corresponds to the color white in both
the presentation space's logical color table and the device's physical color
table. The index value for blue in the device's table is 0x0001, and the
index value for white in the device's table is 0x0000. To determine the
color of a line, MS OS/2 performs a bitwise OR operation on the two index
values, as follows:
 
      0x0001
      0x0000
      ------
      0x0001  (Result of bitwise OR)
 
In this case, the result is 0x0001, the index value for blue in the device's
color table. This means that a blue line appears when the application calls
the GpiLine or GpiPolyLine function.
 
Some of the primitive bundles contain foreground and background colors and
mix modes. For instance, the AREABUNDLE structure contains a foreground
color that corresponds to the foreground color of the area fill pattern. The
AREABUNDLE structure also contains a background color that corresponds to
the background color that appears behind the area fill pattern. AREABUNDLE
also contains foreground and background mix modes that specify bitwise
operations on index values in the device's physical color table.
 
There are 16 foreground mix modes. For each mix mode, the index value for
the foreground and current drawing-surface colors (in the device's physical
color table) are combined by using one of the bitwise operators. The
different foreground mix modes are described in the following list:
 
Mix mode        Description
────────────────────────────────────────────────────────────────────────────
FM_AND          Final color's index value is determined by a bitwise AND
                operation on the foreground color's index value and the
                drawing surface's index value.
 
FM_INVERT       Final color's index value is always the inverse of the
                drawing surface's index value.
 
FM_LEAVEALONE   Final color's index value is that of the drawing-surface
                color.
 
FM_MASKSRCNOT   Final color's index value is determined by inverting the
                drawing surface's index value and performing a bitwise AND
                operation on this value and the foreground color's index
                value.
 
FM_MERGENOTSRC  Final color's index value is determined by performing a
                bitwise AND operation on the drawing surface's index value
                and the inverse of the foreground color's index value.
 
FM_MERGESRCNOT  Final color's index value is determined by performing a
                bitwise AND operation on the foreground color's index value
                and the inverse of the drawing-surface color's index value.
 
FM_NOTCOPYSRC   Final color's index value is the inverse of the foreground
                color's index value.
 
FM_NOTMASKSRC   Final color's index value is the inverse of the FM_AND
                result.
 
FM_NOTMERGESRC  Final color's index value is always the inverse of the FM_OR
                result.
 
FM_NOTXORSRC    Final color's index value is always the inverse of the
                FM_XOR result.
 
FM_ONE          Final color's index value is always 1.
 
FM_OR           Final color's index value is determined by a bitwise OR
                operation on the foreground color's index value and the
                drawing surface's index value.
 
FM_OVERPAINT    Final color's index value is that of the foreground color.
 
FM_SUBTRACT     Final color's index value is determined by inverting the
                foreground color's index value and performing a bitwise AND
                operation on this value and the drawing surface's index
                value.
 
FM_XOR          Final color's index value is determined by a bitwise XOR
                operation on the foreground color's index value and the
                drawing surface's index value.
 
FM_ZERO         Final color's index value is always zero.
 
There are four background mix modes. For each mix mode, 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
different background mix modes are described in the following list:
 
Mix mode       Description
────────────────────────────────────────────────────────────────────────────
BM_LEAVEALONE  Final color's index value is that of the drawing-surface
               color.
 
BM_OR          Final color's index value is determined by a bitwise OR
               operation on the background color's index value and the
               drawing surface's index value.
 
BM_OVERPAINT   Final color's index value is that of the background color.
 
BM_XOR         Final color's index value is determined by a bitwise XOR
               operation on the background color's index value and the
               drawing surface's index value.
 
Dithering
 
If you request a color that isn't available in the physical color table, MS
OS/2 obtains the closest match by a process called dithering. For example,
if the physical color table does not contain a certain shade of gray, MS
OS/2 can create what appears to be a gray by mixing black pels and white
pels. Similarly, if the physical color table does not contain a light green
color but does contain a yellow and a green, MS OS/2 can create what appears
to be light green by mixing yellow pels and green pels.
 
Dithering is especially important on monochrome devices. By combining
various combinations of black pels with white pels, MS OS/2 can create
numerous shades of gray.
 
 
                                      ♦