C4 Engine
C4 Engine API Documentation

class OcclusionQuery

Defined in:  C4Renderable.h
The OcclusionQuery class represents an occlusion query operation.

class OcclusionQuery : public ListElement<OcclusionQuery>

Member Functions
OcclusionQuery::GetRenderCookie Returns the cookie stored in an occlusion query object.
OcclusionQuery::SetRenderCallback Sets the render callback function for an occlusion query object.
OcclusionQuery::GetUnoccludedArea Returns the area that was unoccluded during an occlusion query.

OcclusionQuery(RenderCallback *callback, void *cookie);

callback A pointer to the occlusion query's render callback function.
cookie The cookie that is passed to the render callback function as its last parameter.
The OcclusionQuery class represents an occlusion query operation that can be attached to a renderable object. When such a renderable object is rendered as an effect, the GPU counts how many fragments pass the depth test. This information is reported through a render callback function later so that it can be used to alter the appearance of some other renderable object. The render callback function is specified by the callback parameter, which must point to a function having the following signature defined by the RenderCallback type.

typedef void RenderCallback(OcclusionQuery *, List<Renderable> *, void *);

The cookie parameter specifies a user-defined pointer that is passed to the render callback function as its last parameter.

An occlusion query is attached to a Renderable object by calling the Renderable::SetOcclusionQuery function before the renderable object is first rendered. The renderable object is typically created with the render flags kRenderDepthTest, kRenderColorInhibit, and kRenderDepthInhibit all set so that the depth test is performed, but nothing is written to the color buffer or depth buffer.

When the render callback function is called, the first parameter is a pointer to the occlusion query object, and the second parameter points to a list of renderable objects. The render callback function should call the OcclusionQuery::GetUnoccludedArea function to determine the normalized viewport area that passed the depth test when the occlusion query was rendered and optionally add items to the list of renderable objects after making adjustments to their appearance as necessary depending on the outcome of the occlusion query.

The occluded area returned by the GetUnoccludedArea function is reported as the fraction of the entire viewport area corresponding to the number of fragments that passed the depth test. It is always in the range [0.0, 1.0], where a value of 0.0 means that no fragments passed the depth test, and a value of 1.0 means that the entire viewport was filled with fragments that did pass the depth test.
Base Classes
ListElement<OcclusionQuery> Used internally by the Graphics Manager.
See Also