Java 3D^TM 1.4: Stencil Buffer

NOTE: THIS DOES NOT INCLUDE ANY MULTIPASS SUPPORT 

This page describes the proposed API changes for stencil buffer support in Java 3D 1.4. The GraphicsConfigTemplate3D class is used to find a GraphicsConfiguration object with the desired attributes. These attributes include number of color bits (red, green, and blue size), depth buffer size, and whether or not double-buffering, stereo, or antialiasing is needed. The GraphicsConfiguration is used in turn used to create a Canvas3D into which Java 3D can render.

We propose to add a new stencilSize attribute to GraphicsConfigTemplate3D that will allow an application to create a Canvas3D (on-screen or off-screen) with a stencil buffer. We also propose to add new attributes to the RenderingAttributes object that will allow an application to control the stencil test and update. These will work in a similar manner to the equivalent OpenGL methods. Note that since multipass support is not yet available, applications wishing to use stencil will need to make use of OrderedGroup (or use mixed-mode / immediate-mode rendering).

See the new javadoc for more information: GraphicsConfigTemplate3D.setStencilSize, RenderingAttributes.

The proposed API changes are:

• New fields and set methods in existing classes (will also add get methods):
  

GraphicsConfigTemplate3D
    method: setStencilSize(int) // default=0

RenderingAttributes
    fields: ALLOW_STENCIL_ATTRIBUTES_READ/WRITE
    fields: STENCIL_KEEP, STENCIL_ZERO, STENCIL_REPLACE,
    fields: STENCIL_INCR, STENCIL_DECR, STENCIL_INVERT
    method: setStencilEnable(boolean enable)
    method: setStencilOp(int fail, int zfail, int zpass)
    method: setStencilFunction(int func, int ref, int mask)
    method: setStencilWriteMask(int mask)

Issues:

1. How/when is the stencil buffer cleared? Implicitly at the start of a frame? Explicitly? The latter seems problematic.
   [Current plan is to clear implicitly at the start of each frame and not provide explicit control]
   
2. Does the OpenGL stencil functionality map cleanly to DirectX? If not, then stencil support may not be available for the D3D version of Java 3D.
   

Page last updated — $Date$