Capability Bits

To provide the optimal rendering conditions in the default scene graph, Java 3D defaults to the most restrictive options. In other words, it is up to the programmer to turn on the appropriate capability bits for anything that is restricted. For the uninitiated, the errors generated because of “capability not set” can be mysterious and eat up a lot of time.

There are two basic ways to set the capability bits, and a preference for one over the other is a matter of personal style. We demonstrate the general approach using the most common application, allowing for reading and writing of the current transform for a TransformGroup.

The first is to set them at instantiation time using a construct such as

TransformGroup tg = new TransformGroup(TransformGroup.ALLOW_TRANSFORM_READ |
               TransformGroup.ALLOW_TRANSFORM_WRITE);

The second is to use the setCapability() method as follows:

TransformGroup tg = new TransformGroup();
tg.setCapability(TransformGroup.ALLOW_TRANSFORM_READ);
tg.setCapability(TransformGroup.ALLOW_TRANSFORM_WRITE);

By setting these two particular capability bits, we are disabling some of the optimizations that can be used by the Java 3D renderer on this particular TransformGroup. You should avoid making the mistake of allowing all TransformGroups these capabilities because noticeable reductions in rendering speed can result.