Hit testing is performed in the graphics window (GraphicsWindow) using a side-effect mechanism. There is a special rendering mode (see Rendering Modes) that performs hit testing. In this mode (called GW_PICK), the item is not actually drawn, but is instead tested for intersection with the specified hit region. When hit-testing is enabled, primitives set a flag if they pass through or are fully contained in the hit region. When in this mode, the primitives do not cause any visual side-effects -- in particular, they do not change the image or Z buffers If an item needs to be hit tested, a developer must simply draw the item using a rendering level GW_PICK and then check the result.

By clearing the flag before a primitive is rendered, and checking it immediately afterwards, a hit-check for that particular primitive is made. Hit testing on vertices, edges, entire meshes, etc., can be accomplished by rendering only the desired primitives and checking the hit flag at the desired granularity.

When the hit region is a single point, each "hit" primitive also sets a distance variable (representing distance from the hit point to the line in wire-frame mode, and Z distance in filled mode), so that "smart" hit testing -- i.e. choosing the closest primitive to the hit point -- may be implemented.

The following methods are used for hit testing.

• GraphicsWindow::setHitRegion() - Sets the hit region used for hit testing.
• GraphicsWindow::clearHitCode() - This methods clears the hit code. Call this method before performing a hit test.
• GraphicsWindow::checkHitCode() - Returns TRUE if a hit was made; otherwise FALSE.
• GraphicsWindow::getHitDistance()- If checkHitCode() returns TRUE you may call this method to return the hit distance. In wire-frame mode this is the distance to the line. In shaded mode, this is the z distance. This allows you to perform 'smart' hit testing by choosing the item with the smallest hit distance.

Typically you use these methods in the following sequence:

1. You set a hit regions using GraphicsWindow::setHitRegion().
2. You clear the hit code using GraphicsWindow::clearHitCode().
3. You "render" the primitive by setting the graphics mode GW_PICK (using GraphicsWindow::setRndLimits()) and at whatever level you want to check at. For example, if you are in interested in vertex hit testing, you would "render" a series of markers using a rendering mode that included GW_PICK. The GW_PICK mode will cause the system to perform hit testing rather than actually render the item.
4. After each item is "rendered" you check to see if a hit was made using GraphicsWindow::checkHitCode(). If you are looking for just a single hit, you could abort as soon as the method returns TRUE. If you are interested in the closest hit, you loop through all the items calling clearHitCode(), checkHitCode(), and getHitDistance(). After checking all the items you simply choose the smallest hit distance from all the items you've checked.