set_capping_planes(3G)

NAME

set_capping_planes − cap current Model Clip Volume planes

SYNOPSIS

C Syntax:

void set_capping_planes ( fildes, planes, interference_check );
int fildes, planes, interference_check;

FORTRAN77 Syntax:

subroutine set_capping_planes ( fildes, planes, interference_check )
integer*4 fildes, planes, interference_check

Pascal Syntax:

procedure set_capping_planes ( fildes, planes,
interference_check:integer );

DESCRIPTION

Input Parameters

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

planes The mask specifying whether to enable/disable capping for each of the clipping planes present in the current Model Clip Volume (MCV). The following flags can be bitwise ORed together to create this mask:

NULL does not enable capping of MCV clipping planes. This flag should be used when disabling capping.

PLANE1 enable capping of 1st MCV clipping plane.

PLANE2 enable capping of 2nd MCV clipping plane.

PLANE3 enable capping of 3rd MCV clipping plane.

PLANE4 enable capping of 4th MCV clipping plane.

PLANE5 enable capping of 5th MCV clipping plane.

PLANE6 enable capping of 6th MCV clipping plane.

interference_check
Flag used to activate and close interference checking on caps

Discussion

set_capping_planes ends capping of any previously started capping sequences (when unselected) and begins new capping sequences on any specified MCV planes. The planes parameter selects which of the zero to six Model Clip Volume clipping planes specified in the current MCV are to be capped.

Caps can be concurrently generated for up to six model clipping planes. If the current MCV does not define a plane for which capping is enabled, no cap will be generated and a warning will be issued.

The collection of capping edge data begins when capping for a plane is enabled. This edge data records the intersection of all subsequent surface-generating primitives with the MCV plane.

If set_capping_planes is called again, the set of currently enabled capping planes remain, even though they are not selected in the planes parameter of the new call. The collected capping edge data for each of these previously enabled capping planes are grouped to create a set of polygons within each plane. These polygons are rendered using the current fill_color (or bf_fill_color) and interior_style (or bf_interior_style). The front-face of a capping polygon is defined as the face which is away from the current acceptance region. This is opposite to the direction of the clipping plane normal specified in set_model_clip_volume (unless a subsequent call to set_model_clip_volume with the INVERT_MCV combination rule has reversed the normal direction of the clip plane).

The cap polygons will be rendered according to the current lighting settings. No additional vertex data will be used in rendering these polygons, such as vertex color, vertex normal, or move/draw flags. The capping polygons are clipped to the current MCV.

Capping is disabled by calling set_capping_planes with the value of planes set to NULL. If a MCV plane is enabled in two consecutive calls to set_capping_planes, the first plane capping sequence will be ended (and any associated capping polygons rendered) when the second call is made. The second call will then start a new capping sequence.

set_capping_planes expects a closed volume to be rendered between the enabling and ending of a capping sequence such that the intersections of the surface-generating primitives (polygon, quadrilateral_mesh, triangle_strip, spline_surface, and polyhedron) and the enabled capping planes form closed polygons. This function will attempt to close any remaining gaps by forcing a connection between open segment endpoints.

Interference checking of caps identifies which solids are intersecting in the cross section denoted by the model clip plane. This feature requires that front- and back-facing caps are distinguished (see bf_control). Performing interference checking without front/back distinguishing will result in an error. Interference checking for a given model clip plane is enabled in the same way normal capping is, only with the interference_check flag set. When closing a cap that has interference checking enabled, the cap must be closed first with a call to set_capping_planes with the appropriate planes flag cleared (not set) and interference_check FALSE, then the interference check can be made by calling set_capping_planes with the appropriate planes flag cleared (not set) and interference_check TRUE. The attributes of the cap and the interference cap can be set differently by modifying the polygon attributes between these two calls to set_capping_planes.

Interference checking between polyhedrons can be accomplished by: defining a model clip plane, enabling interference checking to a cap, separately capping several polyhedra (possibly with different polygon attributes) with the interference_check flag FALSE, and finally closing the interference check for the given plane by closing the cap with the interference_check flag TRUE.

Set_model_clip_indicator should be called to enable model clipping prior to calling set_capping_planes. If model clipping is not enabled when set_capping_planes is called, a Starbase error will be generated.

If set_model_clip_indicator is called to disable model clipping while capping is enabled, set_capping_planes will automatically be called to attempt to end capping and a warning will be generated.

The current MCV and Model Coordinate transform must not be modified while capping is enabled. If either is changed, capping will be ended and a warning will be produced.

DEFAULTS

Capping of all current MCV planes is disabled.

Museum

Related Articles