adapt_clip_to_extent(3G)

NAME

adapt_clip_to_extent − control the disabling and enabling of clip planes based on extent testing

SYNOPSIS

C Syntax:

void adapt_clip_to_extent(fildes, enable)
int fildes, enable;

FORTRAN77 Syntax:

subroutine adapt_clip_to_extent(fildes, enable)
integer*4 fildes, enable

Pascal Syntax:

procedure adapt_clip_to_extent(fildes, enable:integer);

DESCRIPTION

Input Parameters

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

enable Flag indicating whether or not to disable clip planes for conditionally executed elements.

Discussion

Adapt_clip_to_extent provides a performance optimization in which unnecessary clipping is disabled during display list traversal. This optimization benefits programs that keep clipping on even though most primitives drawn are not clipped or are only clipped against a few clip planes.

Initially the optimization is off. Calling adapt_clip_to_extent with a TRUE (1) value enables the optimization. Calling it with a FALSE (0) value disables it. While the optimization is on, cond_call_segment, cond_execute_segment and cond_return disable clip planes when testing the prune condition index , if certain requirements are met. For these requirements, see cond_call_segment(3G), cond_execute_segment(3G) and cond_return(3G).

Clip planes are disabled for the section of the display list that cond_call_segment, cond_execute_segment and cond_return conditionally traverse. If other conditional elements are encountered while this display list section is being traversed, additional planes may be disabled. The clip planes are reenabled at the end of each level of conditional traversal in which they were disabled.

The clip planes that cond_call_segment, cond_execute_segment and cond_return disable are those that the most recent set_extent determined were not crossed by a bounding box. This bounding box is formed from the extent information passed to set_extent and set_extent_displacements. (For more information on the computation of the bounding box and the determination of the clip planes see set_extent(3G).) Not all clip planes that set_extent determines can be disabled will necessarily be disabled; the actual planes disabled are a function of a device’s capability.

If clip planes are inactive due to prior calls to clip_indicator or depth_indicator, the optimization will still work: cond_call_segment, cond_execute_segment and cond_return will not reenable any inactive clip plane. On the other hand, once the optimization is in effect and clip planes have been disabled through the conditional elements, calling clip_indicator or depth_indicator is not permitted and will lead to unpredictable results. It is, however, permissible to call adapt_clip_to_extent with either a TRUE or FALSE value during traversal of a conditional section of the display list even if clip planes are disabled. Adapt_clip_to_extent will neither enable clip planes, disable clip planes or affect the reenabling of already disabled clip planes. Instead, it will only affect the future disabling of clip planes by cond_call_segment, cond_execute_segment and cond_return.

If adapt_clip_to_extent is enabled, the extents specified in set_extent and set_extent_displacements should surround the primitives in the section of the display list that cond_execute_segment, cond_call_segment or cond_return conditionally traverse. Otherwise, parts of the picture may be drawn outside the clip boundaries, resulting in inconsistent pictures and incorrect picking results. For the extent to be accurate under all views and transformations, it may be necessary to call the supplementary function set_extent_displacements.

If all extents are correct, calling adapt_clip_to_extent with enable set to TRUE will produce the same picture and pick results as calling it with a FALSE value. If all extents are accurate in an entire display list, adapt_clip_to_extent can be called once with a TRUE value after a gopen. Otherwise, adapt_clip_to_extent calls can be interspersed throughout the display list to selectively control clip plane disabling.

Adapt_clip_to_extent permits a greater speed improvement through extents than that provided by ordinary pruning and culling. The actual improvement depends on several factors including the type of primitive being drawn, the capabilities of the device, and the location of the extents relative to the clip boundaries. Best performance gains come from fast primitives such as polylines, fast graphics devices and pictures with parts lying entirely inside or outside the clip boundaries.

ERRORS

1 Graphics device is not initialized for this operation.

DEFAULTS

Adapt_clip_to_extent has a FALSE mode when the device is opened.

Museum

Related Articles