cond_return(3G)

NAME

cond_return − insert a conditional return element into the currently open segment

SYNOPSIS

C Syntax:

void cond_return(fildes, cond_index_select, comp_flag)
int fildes, cond_index_select, comp_flag;

FORTRAN77 Syntax:

subroutine cond_return(fildes, cond_index_select, comp_flag)
integer*4 fildes, cond_index_select, comp_flag

Pascal Syntax:

procedure cond_return(fildes, cond_index_select, comp_flag:integer);

DESCRIPTION

Input Parameters

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

cond_index_select
Condition to test. One of

CI_FALSE (0): constant value test always equal to FALSE.
CI_PRUNE (1): prune condition, set by set_extent.
CI_CULL (2): cull condition, set by set_extent.

comp_flag Comparison flag against which the value of the condition index selected by cond_index_select is tested. Either TRUE (1) or FALSE (0).

Discussion

Cond_return inserts a cond_return element into the currently open segment of the specified graphics device.

When a cond_return element is encountered during display list traversal, the value of the condition index selected by cond_index_select is compared against the value of comp_flag. If they differ, traversal continues to the next element in the current segment. If they are equal, traversal of the current segment terminates and traversal returns to the calling segment.

If adapt_clip_to_extent has been called with mode set to TRUE (1), cond_return may cause some or all clipping planes to be disabled while the remainder of the current segment is traversed, thereby improving performance. The conditions under which this disabling can occur are i) cond_index_select is CI_PRUNE (1), ii) comp_flag is TRUE (0) and iii) set_extent has set the prune condition FALSE. Under these conditions, while the remainder of the current segment is traversed, clipping may be disabled for the planes that set_extent determined were not crossed by the bounding box of the extent specified in that call. If that extent surrounds all primitives encountered during traversal of the remainder of the current segment, clip-plane disabling will have no visual effect on the drawing of the segment, nor will it affect which primitives are picked in the segment. However, any disabling performed will improve drawing or picking speed within that part of the traversal. If subsequent cond_return elements are encountered in the current segment, additional clip planes may be disabled. All clip planes disabled because of calls to cond_return are reenabled when traversal exits from the segment containing the cond_return element.

EXAMPLES

Typical uses of cond_return are illustrated by the following examples.

1. cond_return( fd, CI_FALSE, FALSE );

During traversal, the above element will always end traversal of the segment in which it is located. Traversal will continue in the calling segment.

  2.      adapt_clip_to_extent( fd, TRUE );
        set_extent( fd, mc_extent );
        cond_return( fd, CI_PRUNE, TRUE );

When encountered in a segment, the above elements will result in the remainder of the current segment being traversed if and only if set_extent sets the prune condition to FALSE. Assuming that the extent described by mc_extent surrounds the primitives in the remainder of the current segment, the remainder of the current segment is not drawn needlessly if it is outside the clip boundaries. Furthermore, because adapt_clip_to_extent was called with a TRUE value, unnecessary clipping is disabled, thereby further improving performance.

  3.      set_cull_size( fd, 10.0 );
        set_extent( fd, mc_extent );
        cond_return( fd, CI_CULL, TRUE );

When the above elements are traversed, if the length of the diagonal computed from mc_extent is less than 10 DC units, the remainder of the current segment is not drawn. The visual effect is that as the picture shrinks during zooming, parts of the scene disappear when their sizes on the screen drop below a threshold.

ERRORS

1 Graphics device is not initialized for this operation.

20 Parameter value is out of range.

24 Segment not open.

WARNING

During traversal, if a pop_state element appears after a cond_return and the cond_return is taken, the pop_state will not be executed. This can lead to an inconsistent state if a push_state appeared in the segment before the cond_return. The problem can be solved by rearranging the push_state and pop_state elements so that they are always executed in pairs. Alternatively, the elements can be replaced by appropriate calls to execute_segment or cond_execute_segment. The implicit pop_state action of these functions always occurs regardless of whether cond_return causes an early return.

A similar problem occurs for matrix stack functions such as push_matrix3d and pop_matrix. These elements need to be appropriately placed so they are executed in pairs regardless of actions by cond_return, cond_call_segment or cond_execute_segment.

Museum

Related Articles