set_extent(3G)

NAME

set_extent, set_extent_displacements − set and test an extent for pruning and culling

SYNOPSIS

C Syntax:

void set_extent(fildes, mc_extent)
int fildes;
float mc_extent[2][3];
void set_extent_displacements(fildes, vdc_displacements, dc_displacements)
int fildes;
float vdc_displacements[2][3], dc_displacements[2][3];

FORTRAN77 Syntax:

subroutine set_extent(fildes, mc_extent)
integer*4 fildes
real mc_extent(3,2)
subroutine set_extent_displacements(fildes, vdc_displacements, dc_displacements)
integer*4 fildes
real vdc_displacements(3,2), dc_displacements(3,2)

Pascal Syntax:

type
      extent_diagonal = array[1..2,1..3] of real;
      extent_displacements = array[1..2,1..3] of real;
procedure set_extent(fildes:integer; var mc_extent: extent_diagonal);
procedure set_extent_displacements(fildes:integer; var vdc_displacements,
    dc_displacements: extent_displacements );

DESCRIPTION

Input Parameters

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

mc_extent Endpoints of a diagonal of a three-dimensional bounding box in Modeling Coordinates (MC’s).

vdc_displacements Supplemental data to handle attributes expressed in Virtual Device Coordinates (VDC’s). Only the magnitude of the numbers is considered. The array data is organized by subscripts as follows:

C	FORTRAN	Pascal	Displacement Direction
[0][0]	(1,1)	[1,1]	Negative X (left)
[0][1]	(2,1)	[1,2]	Negative Y (bottom)
[0][2]	(3,1)	[1,3]	Negative Z (front)
[1][0]	(1,2)	[2,1]	Positive X (right)
[1][1]	(2,2)	[2,2]	Positive Y (top)
[1][2]	(3,2)	[2,3]	Positive Z (back)

dc_displacements Supplemental data to handle attributes expressed in Device Coordinates (DC’s). The array is organized in the same manner as vdc_displacements.

Discussion

Set_extent computes the prune and cull condition index values used by cond_call_segment, cond_execute_segment and cond_return. It also determines the set of clip planes these functions can disable under the optimization provided by adapt_clip_to_extent. Set_extent_displacements is an optional function that provides supplementary data for use by set_extent. The first part of this discussion considers the simpler case in which set_extent_displacements has not been called or has been called with zero values.

Mc_extent contains the extreme endpoints of an orthogonal three-dimensional box in Modeling Coordinate space. The edges of the box are orthogonal to the MC space axes (hence, the other endpoints of the box are permutations of the coordinates of mc_extent). Set_extent transforms this extent box to the coordinate system. The X and Y coordinates are Device Coordinates and the Z is device dependent. Set_extent forms a bounding box encompassing the transformed extent. This bounding box is orthogonal and has edges parallel to the coordinate axes. If it were drawn on the screen in DC’s, it would appear as a rectangle and would surround the extent defined by mc_extent.

After forming the bounding box, set_extent compares it against the current clip limits to set the prune condition and determine which clip planes can be disabled, if any. The current clip limits are the planes set by clip_rectangle and clip_depth, intersected with the current pick window (see set_pick_window(3G)) or by the z-strip boundaries (see zbuffer_switch(3G)), when these are in effect. Any clip planes inactivated by calls to clip_indicator, depth_indicator or adapt_clip_to_extent are not considered. The prune condition is set TRUE if the computed bounding box lies entirely outside any clip plane. If it lies inside any clip plane, the prune condition is set FALSE and the clip planes that the box crosses are determined. These planes may later be disabled if adapt_clip_to_extent is called with a TRUE value.

Set_extent next sets the cull condition using the computed bounding box as follows. The bounding box is projected onto the XY Device Coordinate plane. The result if a finite rectangular region, except for a special case described below. A diagonal of this rectangle is chosen and its length computed, in DC’s. This value is compared to the current cull size specified by set_cull_size. If the diagonal length is less than the current cull size, the cull condition is set TRUE; otherwise it is set FALSE. A special case exists when the extent box specified by mc_extent crosses the eyeplane and perspective viewing is in effect. The projection of the bounding box onto the XY DC plane results in a region of infinite size. The diagonal is thus infinite and the cull condition is always set FALSE.

The way mc_extent is used implies that it should surround the primitives in the section of the display list that a cond_call_segment, cond_execute_segment or cond_return function will conditionally traverse. If the extent does not, set_extent may set the prune condition incorrectly or choose an incorrect set of clip planes to disable. During display traversal, these errors can cause anomalies near the clip borders or z-strip boundaries. During pick traversal, they can result in the wrong set of primitives being picked.

In most cases, an accurate extent can be defined via the mc_extent parameter of set_extent. This is true when the geometry and attributes of primitives are entirely described in Modeling Coordinate space. For example, the extents for polygons and polylines drawn with nominal line widths, text drawn under the WORLD_COORDINATE_TEXT option, and polymarkers drawn as a dot can all be described through mc_extent. However, primitives whose attributes are expressed in VDC units or DC units cannot be adequately described by an extent in Modeling Coordinates. For instance, consider polymarkers whose size has been set by marker_size to be 8 VDC units. An extent expressed solely in MC’s would not surround the rendered polymarkers under all MC transformations. In particular, if a scaling were applied to shrink the locations of the polymarkers to a single screen location, the MC extent would also shrink to a single pixel; however, the rendered polymarkers would still occupy 8 VDC units on the screen. To accommodate primitives with VDC and DC attributes, the function set_extent_displacements is provided. Note however that this function need not be used if the extent is only used for culling based on the geometry of the primitives and not their rendered attributes.

When set_extent_displacements has been called with non-zero values, set_extent behaves as follows. An orthogonal bounding box in coordinates is computed as before from the extent in mc_extent. Set_extent, however, enlarges the box in a special way before setting the prune and cull conditions. Each distance in vdc_displacements is transformed from VDC units to DC units and compared to the corresponding value in dc_displacements. The larger value is chosen and the corresponding side of the computed bounding box displaced outward in that direction. The prune and cull conditions and clip planes to disable are then computed in the same manner as before using this enlarged bounding box.

If accurate values have been passed to set_extent_displacements and set_extent, the resulting enlarged bounding box will completely encompass the primitives and their VDC or DC attributes under all transformations. The prune and cull conditions and the set of clip planes to disable will be based on the region of the screen occupied by the primitives when drawn.

The values to use with vdc_displacements and dc_displacements can be determined as follows. Consider an MC transformation having zero scaling and no translation or rotation. Under this transformation, the positional geometry of the primitives will lie at the origin. However, any VDC or DC attributes will still occupy space in the Device Coordinate space. Dc_displacements can be set to the size of this region when primitives having only DC attributes are considered. Likewise, vdc_displacements is set to the size of this region in VDC units when primitives having only VDC attributes are considered. The units of Z coordinate DC displacements are device dependent.

The call to set_extent need not occur immediately before a call to cond_call_segment, cond_execute_segment or cond_return. Because of the pipelined architecture of various high-speed devices, performance may improve if set_extent is separated from these conditional functions by as many Starbase functions as possible. Clipping and transformations, however, should be set to their desired values at the time that set_extent is called.

EXAMPLES

The following C program section creates a segment that draws one of two segments according to the size of area that a transformed MC unit square occupies on the screen. If the unit square transforms to a DC region whose diagonal is less than 10 pixels, segment 2 will be drawn. Otherwise, segment 3 will be drawn. Segment 2 typically would contain a less detailed representation of the contents of segment 3.

static float mc_extent[2][3]={0.0, 0.0, 0.0, 1.0, 1.0, 1.0};
open_segment(fildes,1,FALSE,FALSE);
set_cull_size(fildes,10.0);
set_extent(fildes,mc_extent);
cond_execute_segment(fildes,CI_CULL,TRUE,2);
cond_execute_segment(fildes,CI_CULL,FALSE,3);
close_segment(fildes);

The following C program section creates a segment that is not traversed if it lies totally off-screen. If it does not, it is drawn with clipping disabled for those planes that the picture does not cross. Set_extent_displacements is called so that set_extent takes into account the DC marker size and the VDC text attributes when computing the extent. Note that the mc_extent parameter passed to set_extent is formed from the polymarker positions and the text initial position.

In choosing the values for array dc_disp below, a screen size of 1024 by 1280 is assumed. The default device-dependent marker height is 1/12 the screen height, or 86 pixels in this case. Hence the call to marker_size with a size parameter of 1.5 and a mode parameter of TRUE for scaled markers results in markers 129 pixels high. Markers drawn with these values therefore extend 64.5 pixels in each of the X and Y direction from their modeling coordinate center. Thus the X and Y displacements in dc_disp are set to 64.5 units. This size is constant regardless of the vdc to dc transform that is in effect.

static float dc_disp[2][3]={64.5, 64.5, 0.0, 64.5, 64.5, 0.0 };
static float mc_extent[2][3]={-1.0, -1.0, 2.0, 2.0, 1.0, 5.0};
static float pm_clist[9]={-1.0, 1.0, 3.0, -2.0, 0.0, 3.0, 2.0, 0.5, 2.0 };
float text_extent[12], vdc_disp[2][3];
/* Compute VDC displacements based on text that will be put in segment. The */
/* vdc-to-dc transform is pushed on the stack so that inquire_text_extent */
/* returns VDC units. */
push_vdc_matrix(fildes);
character_height(fildes,0.5);
inquire_text_extent(fildes,"Example",ANNOTATION_TEXT,text_extent);
pop_matrix(fildes);
vdc_disp[0][0] = text_extent[3]; /* X coordinate of lower left corner */
vdc_disp[0][1] = text_extent[4]; /* Y coordinate of lower left corner */
vdc_disp[0][2] = text_extent[5]; /* Z coordinate of lower left corner */
vdc_disp[1][0] = text_extent[9]; /* X coordinate of upper right corner */
vdc_disp[1][1] = text_extent[10]; /* Y coordinate of upper right corner */
vdc_disp[1][2] = text_extent[11]; /* Z coordinate of upper right corner */
open_segment(fildes,10,FALSE,FALSE);
/* Control to skip segment if it is outside clip boundaries, or if inside */
/* to disable unnecessary clip planes as the segment is drawn */
set_extent_displacements(fildes,vdc_disp,dc_disp);
set_extent(fildes,mc_extent);
adapt_clip_to_extent(fildes,TRUE);
cond_return(fildes,CI_PRUNE,TRUE);
character_height(fildes,0.5);
marker_size(fildes, TRUE, 1.5 ); /* 129 DC units */
polymarker3d(fildes,pm_clist,2,0);
text3d( fildes, 0.0, -1.0, 5.0, "Example", ANNOTATION_TEXT, FALSE );
close_segment(fildes);

ERRORS

1 Graphics device is not initialized for this operation.

DEFAULTS

When a device is opened, the prune condition index and cull condition index values are FALSE. Vdc_displacements and dc_displacements are initialized to zero.

WARNINGS

Set_extent and set_extent_displacements cannot be used to describe extents for primitives whose drawing positions are not subject to the modeling coordinate transformation. These primitives include block_write, text2d or text3d using the VDC_TEXT option, and all dc primitives (e.g. dctext), as well as others. Cond_call_segment, cond_execute_segment and cond_return should not conditionally traverse segments containing these types of primitives.

Museum

Related Articles