In the Web Driver, objects are usually sorted for display on a polygon level. Closer
polygons will appear in front of more distant ones, regardless of the position of the
models and actors that contain those polygons. However, if an object contains alpha
(partial transparency), the polygons are sorted by object.
Because a polygon may be rendered on top of another polygon that is actually closer
to the camera/viewer due to the influence of alpha settings on sort order, you may wish
to take steps to prevent this from happening. But this could also be an effect you could
exploit : for example, imagine you are writing a first-person shooter, and you want the
player's gun model to always appear in front of world geometry ... even when the gun
pokes through a wall.
You can create
a custom sort order for alpha objects using WTGroup::setOption(), but if you want to create
custom sorting for objects without alpha polygons (such as the boxes in the
above scene), you can use WTSurfaceShader::setDepthOption() on
the surface shader attached to the object. setDepthOption() can be used to set two
parameters; Depth Buffer Test and Depth Buffer Write.
To see the effects of setDepthOption() in action,
follow the simple examples below.
You can force an object to be drawn last (that is, on top of everything else)
by turning OFF the "Depth Buffer Test Mode" of any object. In this example,
the green box has this option turned off.
Getting an object to be drawn first (that is, under other objects) is
a bit trickier. In this example, "Depth Buffer Write Mode" has been turned
OFF for the yellow box.
The yellow box now sorts on the object level, as opposed to the "per-poly" level sorting.
Now you can control the sorting that occurs based on the alpha bucket option.
In Web Driver 2.2 and later (having called designedForVersion("2.2")),
you can use a negative alpha bucket to make the yellow box
draw first. Here the yellow box has a sort bucket of -1. But if you are using
Web Driver 2.1, you don't get negative alpha buckets, so
you're stuck with setting the other objects in the scene
to have an alpha bucket greater than the default 0, plus you have to set all
their "Depth Buffer Write Modes" set to OFF.
The setDepthOption() function, and surface shaders in general,
require that designedForVersion("2.1") be called.
Depth buffer operations are set per surface shader, not per object. Therefore,
two different models that have the same surface shader applied will always have
the same depth option.
The alpha bucket sort option will only have an effect if
the object has an alpha mask (not seen in this lab) or has a surface shader
applied to it with the Depth Buffer Test turned off.
Both depth options are ON by default.
The floor has "Depth Buffer Write Mode" set to OFF with an alpha bucket
of -127, just to make sure you don't lose one of your boxes behind it.