shade_mode(3G)

NAME

shade_mode − enable/disable light source polygon shading.

SYNOPSIS

C Syntax:

void shade_mode(fildes,mode,shading);
int fildes,mode,shading;

FORTRAN77 Syntax:

shade_mode(fildes,mode,shading)
integer*4 fildes,mode,shading

Pascal Syntax:

procedure shade_mode(fildes,mode,shading:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

mode Specifies Starbase color map setup: CMAP_NORMAL, CMAP_MONOTONIC, and CMAP_FULL. Can be ORed with INIT to initialize color map.

shading
If TRUE (1), filled polygons are processed through the light source equations.

Discussion

The mode parameter specifies how the color map is interpreted:

CMAP_NORMAL
This is the default mode. The color table is searched for the color closest to the one requested for procedures such as fill_color and line_color. CMAP_NORMAL cannot be used if shading or depth cueing is on, or color coordinates are being used for output primitives. If INIT is ORed with CMAP_NORMAL, the color map is initialized to its default state. In this mode, a 24-plane graphics device behaves as a standard 8-plane device (for the HP 98735 and HP 98736 devices with 24-planes, 12-bit indexing is possible).

CMAP_MONOTONIC
This mode assumes a monotonically increasing intensity between the color map indices set by shade_range. All color values are converted to intensities by the equation:
I = 0.30 * red + 0.59 * green + 0.11 * blue
This intensity value is then mapped to an index using the min and max specified by shade_range. If INIT is ORed with CMAP_MONOTONIC, the color map is initialized to a linear grayscale between the lowest index and the highest index. A 24-plane graphics device behaves like a standard 8-plane device (for the HP 98735 and HP 98736 devices with 24-planes, 12-bit indexing is possible).

CMAP_FULL In this mode, color mapping is assumed as follows:

(8-plane) or (16-plane double-buffered) device:
3 bits red, 3 bits green, and 2 bits blue.

(4-plane) or (8-plane double-buffered) device:
1 bit red, 2 bits green, and 1 bit blue.

(3-plane) or (6-plane double-buffered) device:
1 bit red, 1 bit green, and 1 bit blue.

(6-plane) device:
2 bits red, 2 bits green, and 2 bits blue.

(24-plane) device:
8 bits red, 8 bits green, and 8 bits blue or
if double-buffered
4 bits red, 4 bits green, and 4 bits blue.

CMAP_FULL can be specified only if the graphics device has 3 or more planes. CMAP_FULL requires at least 3 planes per buffer when double-buffering is used. If INIT is ORed with CMAP_FULL, the color map is initialized according to the above assumptions.

(Note: all drivers which support lighting require at least 8 planes in the CMAP_FULL mode, or at least 16 planes if double-buffered).

When shading is FALSE (0), light sources are not applied to polygons. When shading is TRUE (1), the light source equations, as defined by surface_model are used to determine the polygon colors. Note that if all the lights are disabled by light_switch, polygons will not be seen. The vertex_format procedure is used to obtain various shading effects such as constant (faceted) shading and RGB interpolation (smooth or Gouraud) shading.

Current colors are recalculated using the current color map mode.

shade_mode may change current bank usage (see bank_switch). Since unused banks are sometimes used for the Z-buffer when hidden surface removal is enabled, changing the color map mode when hidden surface removal is enabled is not permitted. For example, if the color map mode is CMAP_NORMAL when hidden surface removal is turned on, no more than two banks will be in use. If additional banks are available in the device, they may be allocated for Z-buffer usage. This means that if the color map mode were later changed to CMAP_FULL, up to three banks could be used for image space, resulting in a collision if the third bank was being used for the Z-buffer. Such a change could also increase the number of passes needed to fully render an image, so simply recalculating the Z-buffer allocation would not produce a satisfactory solution. For this reason, the color map mode should be set before hidden surface removal is enabled. If the color map mode needs to be changed, hidden surface removal should be disabled before the change is made.

For grayscale devices, the color map is conceptually initialized, based on the current color map mode, the same as it is for color devices. However, each (red, green, blue) value is transformed into a grayscale intensity using the formula:

I = 0.30 * red + 0.59 * green + 0.11 * blue

This allows color applications to run acceptably, without modification, on grayscale devices.

Devices with 16 or more planes will always require at least 8 planes when the color map mode is CMAP_FULL or CMAP_MONOTONIC. When double-buffering, the 16 planes will be split into two banks of 8 planes. A request for 1, 2, 3, 4, or 6 planes in a single buffer will return a value of 8, which is the actual number of planes used for double-buffering on such devices.

Performance Note: Color calculations for fill_color, line_color, perimeter_color, background_color, text_color, and marker_color are much faster for the CMAP_FULL and CMAP_MONOTONIC modes than the CMAP_NORMAL mode. This is because the colors can be calculated as opposed to searching the color map for the closest colors.

See the Starbase Graphics Techniques chapter, Using Starbase with the X Windows System for more information about performance in a window system.

DEFAULTS

mode = CMAP_NORMAL,
shading = FALSE (0).

Museum

Related Articles