PEXOCCTestExtent - Test Extent Output Command (5.2)


Synopsis

 
   void PEXOCCTestExtent(
        PEXOCC context,
        PEXCoord corner1,
        PEXCoord corner2,
        int index,
        int condition,
        unsigned long clip_test_mask,
        unsigned long size_test_mask
   )
 

Arguments

context
An OC context returned by a successful PEXCreateOCC call.

display (OCC)
A pointer to a display structure returned by a successful XOpenDisplay call.

resource_id (OCC)
The resource identifier of the renderer or structure.

req_type (OCC)
The request type for the output command (PEXOCRender, PEXOCStore, PEXOCRenderSingle or PEXOCStoreSingle).

corner1
One corner of the extent box.

corner2
The other corner of the extent box.

index
Index into the renderer's extent size table.

condition
Comparison condition for the extent size (PEXLessThan, PEXLessThanOrEqual, PEXGreaterThan, PEXGreaterThanOrEqual, PEXEqual or PEXNotEqual)

clip_test_mask
Bitmask indicating bits to be changed in the renderer's condition flags according to the result of the clip test.

size_test_mask
Bitmask indicating bits to be changed in the renderer's condition flags according to the result of the size test.

Returns

None.

Description

Invoke PEXOCCTestExtent to create a test extent output command which, when encountered by a renderer, modifies the renderer's pipeline state condition flags based on the results of a clip test and a size test against the given extent.

The values in corner1 and corner2 define minimum and maximum x, y, and z coordinates in modeling coordinates. These two corners, as diagonal corners of the extent, define the eight corners of a bounding box. The renderer transforms these eight corners using the current modeling and viewing transformations to obtain the bounding box in NPC space. The renderer does not apply model clipping operations in this transformation. The renderer then modifies the extent to become the smallest box that surrounds itself with the edges being parallel to the NPC axes.

The renderer begins the clip test by clipping the NPC space bounding box and transforming the clipped NPC space bounding box to DC space. The renderer does not apply the clip list or window occlusion during clip testing.

If the extent is completely outside the renderer's viewport or completely outside the renderer's NPC subvolume, then the renderer ORs the clip_test_mask bitmask into the renderer's condition flags. Otherwise the renderer ANDs the complement of the clip_test_mask bitmask into the renderer's condition flags.

After modifying the condition flags with the results of the clip test, the renderer begins the size test by computing the extent's diagonal length in an implementation-dependent way. Conceptually the renderer uses the Euclidean distance, but may use a different measure, as long as it represents the extent's diagonal size in pixels.

If the extent is completely clipped, then the renderer assumes that the extent size is zero. The renderer again transforms the NPC space bounding box to DC, but without clipping in either NPC or DC, resulting in an extent that represents the full size of the object in DC space, with no clipping applied.

The extent's size is compared to the extent size in the renderer's extent size lookup table entry selected by index, using the comparison operation specified by the condition argument. If the comparison is true, the renderer ORs the size_test_mask bitmask into the renderer's condition flags. Otherwise the renderer ANDs the complement of the size_test_mask bitmask into the renderer's condition flags.

The extent tests are defined to err on the side of determining an object is more visible and its size slightly larger than a more precise test would find. Implementations may choose to implement higher quality and more exact extent tests.

Errors

BadPEXOutputCommand
The value of index is zero.

BadPEXOutputCommand
Condition is not one of the registered relational test values.

BadPEXRenderer
The specified renderer resource identifier is invalid.

BadPEXStructure
The specified structure resource identifier is invalid.

See Also

See Structure Control and Miscellaneous Functions for an overview.