Java3DRenderToTexture

ROUGH DRAFT: This API is a Work in Progress

This page describes the possible render-to-texture feature in Java 3D 1.5 / 1.6. The main idea is to create new "render-to-texture" subclasses of Canvas3D^? and View that would render into a texture that could then be used in a scene graph to render into an ordinary on-screen (or off-screen) Canvas3D^?. We will either need to create special "rendered" subclasses of Texture (e.g., RenderedTexture2D), or add a mode flag to the existing texture classes. The former is cleaner from an API point of view, but the latter is more flexible (e.g., it would allow some mipmap levels of a Texture or faces of a TextureCubeMap to be generated by rendering and others to be specified via an image).

Notes:

• A TextureView is rendered when any View that references a scene graph containing its RenderedTexture object is rendered. The ordinary View is said to be dependent on the TextureView.
• Each TextureView is rendered before its dependent View(s).
• RenderedTexture objects cannot be in a scene graph that is rendered by a TextureView. Violating this will lead to undefined results. We may want to consider relaxing this restriction to allow for cascading render-to-texture operations. If we do relax this, we may need to provide a way for the application to specify an ordering of TextureViews (determining the dependency graph would be difficult).
• To make it easier for an app to comply with the above, we will add a new feature to View: a boolean attribute indicating whether to render only to nodes under a ViewSpecificGroup. This flag is false by default for an ordinary View and true by default for a TextureView.

The proposed API is:

• New classes

public class TextureView extends View
    method: setXxxxx() // Any methods here?

public class TextureCanvas3D extends Canvas3D
    method: setRenderedTexture(RenderedTexture) // or should this be immutable?
    method: setLevel(int level)
    method: setFace(int face)
    // override lots of Canvas-related methods and throw UnimplementedException

public class RenderedTexture extends Texture
    method: setXxxxx() // Any methods here?

public class RenderedTexture2D extends RenderedTexture
    method: setXxxxx() // Any methods here?

public class RenderedTexture3D extends RenderedTexture
    method: setXxxxx() // Any methods here?

public class RenderedTextureCubeMap extends RenderedTexture
    method: setXxxxx() // Any methods here?

• New methods in existing classes:

View
    method: setViewSpecificGroupOnly(boolean)

Issues:

1. Can the resulting image be read back to the application?
   [ we don't plan to allow this ]
2. What is the best way to ensure that there is a valid source of all mipmap levels (and all faces of a cube-map)?
3. Should RenderedTexture be a mode or a subclass?
   [ currently proposed to be a subclass ]
4. Since this feature encourages using implicit mipmap generation, we need to implement the implicit mipmap generation features (issue 126) using OpenGL or DirectX HW mipmap generation.