inq_extent_info(3G)

NAME

inq_extent_info − inquire supplementary information about an extent test

SYNOPSIS

C Syntax:

void inq_extent_info(fildes, dc_extent, clip_mask, diagonal_length)
int fildes, clip_mask[2][3];
float dc_extent[2][3], *diagonal_length;

FORTRAN77 Syntax:

subroutine inq_extent_info(fildes, dc_extent, clip_mask, diagonal_length)
integer*4 fildes, clip_mask(3,2)
real dc_extent(3,2), diagonal_length

Pascal Syntax:

type
extent_diagonal = array[1..2,1..3] of real;
extent_clip_mask = array[1..2,1..3] of integer;
procedure inq_extent_info(fildes:integer; var dc_extent: extent_diagonal;
var clip_mask:extent_clip_mask; var diagonal_length: real );

DESCRIPTION

Input Parameters

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

Output Parameters

dc_extent Endpoints of a diagonal of the three-dimensional bounding box formed during the last call to set_extent.

clip_mask Array of integers indicating which clip planes were intersected by the bounding box computed at the last call to set_extent. A value of TRUE (1) indicates intersection, FALSE (0) otherwise. The array data is organized by subscripts as follows:

C	FORTRAN	Pascal	Clip Plane
[0][0]	(1,1)	[1,1]	Left
[0][1]	(2,1)	[1,2]	Bottom
[0][2]	(3,1)	[1,3]	Hither
[1][0]	(1,2)	[2,1]	Right
[1][1]	(2,2)	[2,2]	Top
[1][2]	(3,2)	[2,3]	Yon

diagonal_length Length, in Device Coordinates, of the diagonal of the projection of the bounding box onto the XY DC plane.

Discussion

Inq_extent_info is primarily a debugging aid for extents.

Set_extent transforms an extent box from Modeling Coordinates to a pre-perspective-divide coordinate space and computes an orthogonal bounding box surrounding the transformed extent. It compares this bounding box against the current clip limits to set the prune condition value and compares the size of the box against the current cull size to set the cull condition value. The values of these condition indices can be inquired through inq_cond_index. This function, inq_extent_info, returns additional information about the bounding box.

Through dc_extent, inq_extent_info returns two extreme endpoints of the orthogonal bounding box computed by set_extent. This bounding box is expressed in the pre-perspective-divide coordinate space in which clipping is performed (see clip_depth(3G)). In this space, the X and Y coordinates are Device Coordinates and the Z coordinate is device-dependent. Inasmuch as the computed bounding box is orthogonal, it is described by simply returning the endpoints of one of its diagonals. This diagonal is chosen such that each coordinate of the first point is less than or equal to the coordinate of the second point.

Through clip_mask, inq_extent_info returns the clip planes that the computed bounding box intersected at the time of the set_extent call. These are the planes that may be disabled if the optimization provided by adapt_clip_to_extent is enabled. For each plane intersected, the corresponding element of clip_mask is set TRUE (1). For non-intersecting planes, or for planes inactivated by calls to clip_indicator or depth_indicator, the corresponding element of clip_mask is set FALSE (0). If a clip plane is disabled because of adapt_clip_to_extent (3G), the corresponding element of clip_mask is also set FALSE (0). If the extent box lies entirely inside or outside the clip limits, all elements of clip_mask are set FALSE (0). These two cases can be distinguished by inquiring the prune condition value via inq_cond_index.

Through diagonal_length, inq_extent_info returns the length of the diagonal that set_extent uses to determine the cull condition value. Set_extent calculates this length from the rectangle it obtains by projecting the bounding box of the specified extent onto the XY Device Coordinate plane. Normally, diagonal_length is the length of the diagonal of the front face of the bounding box. However, if the extent box specified in the call to set_extent crosses the eye-plane and a perspective projection is in effect, the projection of the bounding box onto the eye plane will cover an infinite region. Under these conditions, a real number greater than 1E38 representing infinity will be returned in diagonal_length.

ERRORS

1 Graphics device is not initialized for this operation.

DEFAULTS

Prior to the first call to set_extent, inq_extent_info will return 0.0 for all coordinates of dc_extent, TRUE (1) for all values of clip_mask, and 0.0 for diagonal_length.

Museum

Related Articles