double_buffer(3G)

NAME

double_buffer − enable/disable double buffering

SYNOPSIS

C Syntax:

int double_buffer(fildes,mode,planes);
int fildes, mode,planes;

FORTRAN77 Syntax:

integer∗4 function double_buffer(fildes,mode,planes)
integer∗4 fildes, mode, planes

Pascal Syntax:

function double_buffer(fildes,mode,planes:integer):integer;

DESCRIPTION

Input Parameters

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

mode Specifies whether double buffering is on or off.

0 - double buffering off.
1 - double buffering on.

See the discussion below for details on how to specify whether to update the color map and whether to draw to the same buffer that is displayed.

planes Specifies the number of planes in each buffer for input. Allowable requests are 1, 2, 3, 4, 6, 8 and 12. (hardware dependent)

Discussion

double_buffer is used to enable/disable double buffering and define buffering parameters. It is also used to enter 12 bit (double buffered) indexing mode on devices that support a 12 bit color table. In addition to the device file descriptor, this function accepts two parameters: mode and planes.

• If the least significant bit of mode is set to TRUE (1), double buffering is enabled and the display and write enable registers are set up according to the hardware configuration and planes parameter. In double buffer mode, the write enable and display enable masks as set by write_enable and display_enable are applied individually to each of the buffers. For example, if bit 1 of the write enable mask is clear, then plane 1 of both buffers will be disabled for writing.

• mode | INIT - If INIT is ORed with mode, the color map is properly initalized and color indices are correctly interpreted.

• mode | DFRONT - If DFRONT is ORed with mode, when mode is set to TRUE (1), then the buffer that is enabled for display will also be enabled for writing. This makes it much easier to effectively switch in and out of double buffering.

• mode | SUPPRESS_CLEAR - If SUPPRESS_CLEAR is OR ed with mode , then the buffer that is enabled for writing will not be cleared by subsequent calls to dbuffer_switch .

• The planes parameter specifies the number of planes to be used for each buffer. Legal values for this parameter are 1, 2, 3, 4, 6, 8, or 12. The number of planes actually being used for double buffering is returned by this function. Obviously an application must not request more than half the number of planes installed on the graphics device being used. If this occurs, Starbase sets the number of planes used to the maximum legal value. Conversely, if an application requests fewer than the maximum number of planes, the uppermost planes are used. Unused planes are write disabled and display enabled. Note that if fewer than 3 planes are requested for each buffer, the color map mode should be set to CMAP_NORMAL or CMAP_MONOTONIC (see shade_mode).

On devices that support a 12 bit color table, double_buffer can be used to enable 12 bit indexing. Double buffering 12 planes when in CMAP_MONOTONIC or CMAP_NORMAL mode enables 12 bit (double buffered) indexing. Single buffered 12 bit indexing mode can only be accomplished by enabling 12 bit double buffering with mode ORed with DFRONT and never switching the buffers via dbuffer_switch. When double buffering is disabled from 12 bit indexing mode, Starbase returns to 8 bit indexing mode.

After double buffering has been set up with double_buffer, the buffers can be switched using dbuffer_switch.

If only one plane is available on the device or the color map mode is CMAP_FULL and there are fewer than 6 planes available on the device, double buffering cannot be enabled and an error is generated, if requested. Subsequent calls to dbuffer_switch result in only a clear_view_surface. The clear_view_surface will be suppressed if SUPPRESS_CLEAR was ORed with mode in the call to double_buffer.

When double buffering is disabled, Starbase returns the display and write enable registers to their current values and/or resets the bank_select to its current value.

If 6 planes are requested when 8 are available, all 8 will actually be used.

Double buffering 12 planes in CMAP_MONOTONIC or CMAP_NORMAL mode is not possible on devices that do not support 12 bit indexing. Double buffering 12 planes is available in CMAP_FULL mode (4:4:4).

A call to double_buffer does not perform switching between buffers (activated by dbuffer_switch).

Refer to the Starbase Graphics Techniques chapter,
Using Starbase with the X Window System, for details regarding double_buffering.

RETURN VALUE

Upon completion of this function, a non-negative number is returned that is the actual number of planes being used for double buffering. This number is the number requested unless the device cannot support that many planes.

DEFAULTS

mode = 0:double buffering off.

Museum