set_model_clip_volume(3G)

NAME

set_model_clip_volume − define a new or modified Model Clip Volume

SYNOPSIS

C Syntax:

void set_model_clip_volume(fildes,num_planes,
planes,combination);
int fildes,num_planes,combination;
float planes[];

FORTRAN77 Syntax:

subroutine set_model_clip_volume(fildes,num_planes,
planes,combination)
integer*4 fildes,num_planes,combination
real planes(6*num_planes)

Pascal Syntax:

procedure set_model_clip_volume(fildes,num_planes:integer;
var planes[lo..hi:integer] of real;combination:integer);

DESCRIPTION

Input Parameters

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

num_planes the number of clipping planes defined in the planes array (0 to 6).

planes the clipping plane definition(s), consisting of a three dimensional point on the plane and a normal vector from that plane in the direction of the acceptance region, all in modelling coordinates. The format of this array is: (point1, normal1, point2, normal2, ...), where a point is a triplet of reals, x,y,z, and a normal is a triplet of reals, ni,nj,nk, in modelling space.

combination defines how the new volume defined by planes is to be combined with the currently defined Model Clip Volume (MCV) to define the new MCV (see the restrictions below):

Combination	Resulting Clipping Volume
Rules
REPLACE_MCV	REPLACE current MCV with the new volume
AND_WITH_MCV	AND the new volume with the current MCV
OR_WITH_MCV	OR the new volume with the current MCV
INVERT_MCV	INVERT the current MCV (NOT (MCV))

Discussion

set_model_clip_volume defines a clip volume using up to six separate clipping planes in the current model coordinates. Each plane defines an acceptance region (a half space). These acceptance regions are AND’d together to form an acceptance volume. If num_planes = 0, then the acceptance region is unbounded.

The acceptance volume defined by planes is combined with the current Model Clip Volume by the specified combination rule to form a new MCV. The MCV should not be confused with view clipping. The MCV is a separate and concurrent clipping volume.

When model clipping is enabled, by set_model_clip_indicator, all primitives are clipped against the MCV acceptance region.

Depending on the combination rule provided, the new MCV will be either: the clip volume defined by planes (replacing the current MCV), the intersection of the clip volume and the current MCV (AND of the two volumes), the union of the clip volume and the current MCV (OR of the two volumes), or the logical inverse of the current MCV (NOT MCV).

The combination rules AND_WITH_MCV and OR_WITH_MCV may not be mixed in an MCV definition. Once an MCV definition has been started with an AND_WITH_MCV rule all subsequent set_model_clip_volume calls must use the AND_WITH_MCV combination rule or the REPLACE_MCV rule to start a new MCV definition. Similarly, the same rule applies to OR_WITH_MCV.

If an MCV is defined with the OR_WITH_MCV combination rule, each set_model_clip_volume call must contain only one clipping plane definition (num_planes = 1). This is because multiple half space definitions are ANDed together to form the new clip volume, and the combination of AND and OR operators is not allowed.

If a set_model_clip_volume call is made which attempts to mix AND_WITH_MCV and OR_WITH_MCV combination rules, a Starbase warning will be generated and the MCV will remain unchanged.

The INVERT_MCV combination rule provides a simple method to complement the current MCV. This rule has the effect of inverting all previously supplied acceptance regions and toggling the combination rules (AND’s to OR’s, OR’s to AND’s). Num_planes should be set to 0 when the INVERT combination rule is used. If num_planes does not equal zero, a Starbase warning will be generated and the MCV will be inverted. Since the INVERT_MCV rule toggles the preceding AND/OR rules, any set_model_clip_volume calls following an INVERT_MCV rule must recognize this and maintain the same combination rule (AND or OR) that is in effect in the current MCV.

Although the MCV clip planes are defined in Model Coordinates, the MCV is maintained in World Coordinates. Therefore, any subsequent changes to the current model transformation will not affect the current MCV.

The MCV supports a maximum of six clip planes in its definition. These six planes can be defined with one set_model_clip_volume call or by up to six separate calls (each providing one plane definition and the AND_WITH_MCV or OR_WITH_MCV combination rule). If a set_model_clip_volume call attempts to define an MCV with more than a total of six clip planes, then the MCV is unchanged and a Starbase error is generated.

DEFAULTS

The default MCV is an unbounded acceptance region.

Museum

Related Articles