com.jme.renderer
Class Renderer

java.lang.Object
  extended by com.jme.renderer.Renderer
Direct Known Subclasses:
DummyRenderer, JOGLRenderer, LWJGLRenderer

public abstract class Renderer
extends java.lang.Object

Renderer defines an abstract class that handles displaying of graphics data to the context. Creation of this object is typically handled via a call to a DisplaySystem subclass. All rendering state and tasks can be handled through this class. Example Usage:
NOTE: This example uses the DisplaySystem class to obtain the Renderer. DisplaySystem ds = new LWJGLDisplaySystem();
ds.createWindow(640,480,16,60,false);
Renderer r = ds.getRenderer();
r.draw(point);

Version:
$Id: Renderer.java 4137 2009-03-20 18:38:24Z christoph.luder $
Author:
Mark Powell, Tijl Houtbeckers (added VBO delete methods)
See Also:
DisplaySystem

Field Summary
protected  ColorRGBA backgroundColor
           
protected  AbstractCamera camera
           
static RenderState[] defaultStateList
          List of default states all spatials take if none is set.
protected  int height
           
protected  boolean processingQueue
           
protected  RenderQueue queue
           
static int QUEUE_INHERIT
          The Spatial will inherit its render queue state from its parent.
static int QUEUE_OPAQUE
          The Spatial will render in the opaque bucket.
static int QUEUE_ORTHO
          The Spatial will render in the ortho bucket.
static int QUEUE_SKIP
          The Spatial will skip render queueing.
static int QUEUE_TRANSPARENT
          The Spatial will render in the transparent bucket.
protected  int width
           
 
Constructor Summary
Renderer()
           
 
Method Summary
abstract  boolean checkAndAdd(Spatial s)
          Check a given Spatial to see if it should be queued.
abstract  void checkCardError()
          Check the underlying rendering system (opengl, etc.) for exceptions.
abstract  void cleanup()
          Perform any necessary cleanup operations such as deleting VBOs, etc.
abstract  void clearBuffers()
          clearBuffers clears both the depth buffer and the back buffer.
abstract  void clearColorBuffer()
          clearBackBuffer clears the back buffer of the renderer.
abstract  void clearPolygonOffset()
          Removes any previously set offset from the renderer.
 void clearQueue()
          clear the render queue
abstract  void clearStencilBuffer()
          clearStencilBuffer clears the stencil buffer of the renderer.
abstract  void clearStrictBuffers()
          clearBuffers clears both the depth buffer and the back buffer restricting the clear to the rectangle defined by the width and height of the renderer.
abstract  void clearVBOCache()
          Clears all entries from the VBO cache.
abstract  void clearZBuffer()
          clearZBuffer clears the depth buffer of the renderer.
abstract  BlendState createBlendState()
          createBlendState retrieves the blend state object for the proper renderer.
abstract  Camera createCamera(int width, int height)
          createCamera retrieves a default camera for this renderer.
abstract  ClipState createClipState()
          Retrieves the clip state object for the proper renderer.
abstract  ColorMaskState createColorMaskState()
          Retrieves the color mask state object for the proper renderer.
abstract  CullState createCullState()
          createCullState retrieves the cull state object for the proper renderer.
abstract  int createDisplayList(Geometry geom)
          Generate a DisplayList for drawing the given Geometry.
abstract  FogState createFogState()
          createFogState retrieves the fog state object for the proper renderer.
abstract  FragmentProgramState createFragmentProgramState()
          Retrieves the fragment program state object for the proper renderer.
abstract  GLSLShaderObjectsState createGLSLShaderObjectsState()
          createShaderObjectsState retrieves the shader object state object for the proper renderer.
abstract  LightState createLightState()
          createLightState retrieves the light state object for the proper renderer.
abstract  StateRecord createLineRecord()
           
abstract  MaterialState createMaterialState()
          createMaterialState retrieves the material state object for the proper renderer.
abstract  StateRecord createRendererRecord()
           
abstract  ShadeState createShadeState()
          createShadeState retrieves the shade state object for the proper renderer.
 RenderState createState(int type)
          Deprecated. As of 2.0, use createState(com.jme.scene.state.RenderState.StateType) instead.
 RenderState createState(RenderState.StateType type)
          Create a RenderState via a given RenderState.StateType type.
abstract  StencilState createStencilState()
          Retrieves the stencil state object for the proper renderer.
abstract  StippleState createStippleState()
          Retrieves the stipple state object for the proper renderer.
abstract  TextureState createTextureState()
          createTextureState retrieves the texture state object for the proper renderer.
abstract  VertexProgramState createVertexProgramState()
          Retrieves the vertex program state object for the proper renderer.
abstract  WireframeState createWireframeState()
          createWireframeState retrieves the wireframe state object for the proper renderer.
abstract  ZBufferState createZBufferState()
          Retrieves the Z buffer state object for the proper renderer.
abstract  void deleteVBO(java.nio.Buffer buffer)
          Checks the VBO cache to see if this Buffer is mapped to a VBO-id.
abstract  void deleteVBO(int vboid)
          Attempts to delete the VBO with this VBO id.
abstract  void displayBackBuffer()
          displayBackBuffer swaps the back buffer with the currently displayed buffer.
abstract  void draw(Curve c)
          draw renders a curve to the back buffer.
abstract  void draw(Line line)
          draw renders a single Line collection to the back buffer.
abstract  void draw(Point point)
          draw renders a single Point collection to the back buffer.
abstract  void draw(QuadMesh mesh)
          draw renders a single QuadMesh to the back buffer.
abstract  void draw(Spatial s)
          draw renders a scene.
abstract  void draw(Text t)
          draw renders text to the back buffer.
abstract  void draw(TriMesh mesh)
          draw renders a single TriMesh to the back buffer.
abstract  void finish()
          finish is similar to flush, however it blocks until all waiting OpenGL commands have been finished.
abstract  void flush()
          flush tells opengl to send through all currently waiting commands in the buffer.
 ColorRGBA getBackgroundColor()
          getBackgroundColor retrieves the clear color of the current OpenGL context.
 Camera getCamera()
          getCamera returns the camera used by this renderer.
 int getHeight()
          Retrieve the height set on this renderer.
 RenderQueue getQueue()
          Get the render queue associated with this Renderer.
 int getWidth()
          Retrieve the width set on this renderer.
abstract  void grabScreenContents(java.nio.ByteBuffer buff, Image.Format format, int x, int y, int w, int h)
          grabScreenContents reads a block of data as bytes from the current framebuffer.
 boolean isHeadless()
          See Renderer.isHeadless()
abstract  boolean isInOrthoMode()
           
 boolean isProcessingQueue()
          Return true if this renderer is in the middle of processing its RenderQueue.
abstract  void reinit(int width, int height)
          Reinitialize the renderer with the given width/height.
abstract  void releaseDisplayList(int listId)
          Releases a DisplayList from the card.
abstract  java.lang.Integer removeFromVBOCache(java.nio.Buffer buffer)
          Removes the mapping between this Buffer and it's VBO-id.
 void renderQueue()
          render queue if needed
abstract  void setBackgroundColor(ColorRGBA c)
          setBackgroundColor sets the color of window.
abstract  void setCamera(Camera camera)
          setCamera sets the reference to the applications camera object.
 void setHeadless(boolean headless)
          See Renderer.setHeadless()
abstract  void setOrtho()
          setOrtho sets the display system to be in orthographic mode.
abstract  void setOrthoCenter()
          setOrthoCenter sets the display system to be in orthographic mode.
abstract  void setPolygonOffset(float factor, float offset)
          Sets an offset to the zbuffer to be used when comparing an incoming polygon for depth buffer pass/fail.
abstract  boolean supportsVBO()
          Return true if the system running this supports VBO
abstract  boolean takeScreenShot(java.lang.String filename)
          takeScreenShot saves the current buffer to a png file.
abstract  void unsetOrtho()
          unsetOrhto unsets the display system from orthographic mode back into regular projection mode.
abstract  void updateTextureSubImage(Texture dstTexture, int dstX, int dstY, Image srcImage, int srcX, int srcY, int width, int height)
          Updates a region of the content area of the provided texture using the specified region of the given data.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QUEUE_INHERIT

public static final int QUEUE_INHERIT
The Spatial will inherit its render queue state from its parent.

See Also:
Constant Field Values

QUEUE_SKIP

public static final int QUEUE_SKIP
The Spatial will skip render queueing.

See Also:
Constant Field Values

QUEUE_OPAQUE

public static final int QUEUE_OPAQUE
The Spatial will render in the opaque bucket.

See Also:
Constant Field Values

QUEUE_TRANSPARENT

public static final int QUEUE_TRANSPARENT
The Spatial will render in the transparent bucket.

See Also:
Constant Field Values

QUEUE_ORTHO

public static final int QUEUE_ORTHO
The Spatial will render in the ortho bucket.

See Also:
Constant Field Values

camera

protected AbstractCamera camera

backgroundColor

protected ColorRGBA backgroundColor

processingQueue

protected boolean processingQueue

queue

protected RenderQueue queue

width

protected int width

height

protected int height

defaultStateList

public static final RenderState[] defaultStateList
List of default states all spatials take if none is set.

Constructor Detail

Renderer

public Renderer()
Method Detail

setCamera

public abstract void setCamera(Camera camera)
setCamera sets the reference to the applications camera object.

Parameters:
camera - the camera object to use with this Renderer.

getCamera

public Camera getCamera()
getCamera returns the camera used by this renderer.

See Also:
getCamera()

createCamera

public abstract Camera createCamera(int width,
                                    int height)
createCamera retrieves a default camera for this renderer.

Parameters:
width - the width of the frame.
height - the height of the frame.
Returns:
a default camera for this renderer.

createBlendState

public abstract BlendState createBlendState()
createBlendState retrieves the blend state object for the proper renderer.

Returns:
the BlendState object that can make use of the proper renderer.

createCullState

public abstract CullState createCullState()
createCullState retrieves the cull state object for the proper renderer.

Returns:
the CullState object that can make use of the proper renderer.

createFogState

public abstract FogState createFogState()
createFogState retrieves the fog state object for the proper renderer.

Returns:
the FogState object that can make use of the proper renderer.

createLightState

public abstract LightState createLightState()
createLightState retrieves the light state object for the proper renderer.

Returns:
the LightState object that can make use of the proper renderer.

createMaterialState

public abstract MaterialState createMaterialState()
createMaterialState retrieves the material state object for the proper renderer.

Returns:
the MaterialState object that can make use of the proper renderer.

createShadeState

public abstract ShadeState createShadeState()
createShadeState retrieves the shade state object for the proper renderer.

Returns:
the ShadeState object that can make use of the proper renderer.

createTextureState

public abstract TextureState createTextureState()
createTextureState retrieves the texture state object for the proper renderer.

Returns:
the TextureState object that can make use of the proper renderer.

createWireframeState

public abstract WireframeState createWireframeState()
createWireframeState retrieves the wireframe state object for the proper renderer.

Returns:
the WireframeState object that can make use of the proper renderer.

createZBufferState

public abstract ZBufferState createZBufferState()
Retrieves the Z buffer state object for the proper renderer.

Returns:
The ZBufferState object that can make use of the proper renderer.

createVertexProgramState

public abstract VertexProgramState createVertexProgramState()
Retrieves the vertex program state object for the proper renderer.

Returns:
The VertexProgramState object that can make use of the proper renderer.

createFragmentProgramState

public abstract FragmentProgramState createFragmentProgramState()
Retrieves the fragment program state object for the proper renderer.

Returns:
The VertexProgramState object that can make use of the proper renderer.

createGLSLShaderObjectsState

public abstract GLSLShaderObjectsState createGLSLShaderObjectsState()
createShaderObjectsState retrieves the shader object state object for the proper renderer.

Returns:
the ShaderObjectsState object that can make use of the proper renderer.

createStencilState

public abstract StencilState createStencilState()
Retrieves the stencil state object for the proper renderer.

Returns:
The StencilState object that can make use of the proper renderer.

createClipState

public abstract ClipState createClipState()
Retrieves the clip state object for the proper renderer.

Returns:
The ClipState object that can make use of the proper renderer.

createColorMaskState

public abstract ColorMaskState createColorMaskState()
Retrieves the color mask state object for the proper renderer.

Returns:
The ColorMaskState object that can make use of the proper renderer.

createStippleState

public abstract StippleState createStippleState()
Retrieves the stipple state object for the proper renderer.

Returns:
The StippleState object that can make use of the proper renderer.

setBackgroundColor

public abstract void setBackgroundColor(ColorRGBA c)
setBackgroundColor sets the color of window. This color will be shown for any pixel that is not set via typical rendering operations.

Parameters:
c - the color to set the background to.

getBackgroundColor

public ColorRGBA getBackgroundColor()
getBackgroundColor retrieves the clear color of the current OpenGL context.

Returns:
the current clear color.
See Also:
getBackgroundColor()

clearZBuffer

public abstract void clearZBuffer()
clearZBuffer clears the depth buffer of the renderer. The Z buffer allows sorting of pixels by depth or distance from the view port. Clearing this buffer prepares it for the next frame.


clearColorBuffer

public abstract void clearColorBuffer()
clearBackBuffer clears the back buffer of the renderer. The backbuffer is the buffer being rendered to before it is displayed to the screen. Clearing this buffer frees it for rendering the next frame.


clearStencilBuffer

public abstract void clearStencilBuffer()
clearStencilBuffer clears the stencil buffer of the renderer.


clearBuffers

public abstract void clearBuffers()
clearBuffers clears both the depth buffer and the back buffer.


clearStrictBuffers

public abstract void clearStrictBuffers()
clearBuffers clears both the depth buffer and the back buffer restricting the clear to the rectangle defined by the width and height of the renderer.


displayBackBuffer

public abstract void displayBackBuffer()
displayBackBuffer swaps the back buffer with the currently displayed buffer. Swapping (page flipping) allows the renderer to display a prerenderer display without any flickering.


setOrtho

public abstract void setOrtho()
setOrtho sets the display system to be in orthographic mode. If the system has already been set to orthographic mode a JmeException is thrown. The origin (0,0) is the bottom left of the screen.


isInOrthoMode

public abstract boolean isInOrthoMode()
Returns:
true if the renderer is currently in ortho mode.

renderQueue

public void renderQueue()
render queue if needed


clearQueue

public void clearQueue()
clear the render queue


setOrthoCenter

public abstract void setOrthoCenter()
setOrthoCenter sets the display system to be in orthographic mode. If the system has already been set to orthographic mode a JmeException is thrown. The origin (0,0) is the center of the screen.


unsetOrtho

public abstract void unsetOrtho()
unsetOrhto unsets the display system from orthographic mode back into regular projection mode. If the system is not in orthographic mode a JmeException is thrown.


takeScreenShot

public abstract boolean takeScreenShot(java.lang.String filename)
takeScreenShot saves the current buffer to a png file. The filename is provided, .png will be appended to the end of the name.

Parameters:
filename - the name of the screenshot file.
Returns:
true if the screen capture was successful, false otherwise.

grabScreenContents

public abstract void grabScreenContents(java.nio.ByteBuffer buff,
                                        Image.Format format,
                                        int x,
                                        int y,
                                        int w,
                                        int h)
grabScreenContents reads a block of data as bytes from the current framebuffer. The format determines how many bytes per pixel are read and thus how big the buffer must be that you pass in.

Parameters:
buff - a buffer to store contents in.
format - the format to read in bytes for.
x - - x starting point of block
y - - y starting point of block
w - - width of block
h - - height of block

draw

public abstract void draw(Spatial s)
draw renders a scene. As it recieves a base class of Spatial the renderer hands off management of the scene to spatial for it to determine when a Geometry leaf is reached.

Parameters:
s - the scene to render.

draw

public abstract void draw(TriMesh mesh)
draw renders a single TriMesh to the back buffer.

Parameters:
mesh - the mesh to be rendered.

draw

public abstract void draw(QuadMesh mesh)
draw renders a single QuadMesh to the back buffer.

Parameters:
mesh - the mesh to be rendered.

draw

public abstract void draw(Point point)
draw renders a single Point collection to the back buffer.

Parameters:
point - the points to be rendered.

draw

public abstract void draw(Line line)
draw renders a single Line collection to the back buffer.

Parameters:
line - the line to be rendered.

draw

public abstract void draw(Curve c)
draw renders a curve to the back buffer.

Parameters:
c - the curve to be rendered.

draw

public abstract void draw(Text t)
draw renders text to the back buffer.

Parameters:
t - the text object to be rendered.

flush

public abstract void flush()
flush tells opengl to send through all currently waiting commands in the buffer.


finish

public abstract void finish()
finish is similar to flush, however it blocks until all waiting OpenGL commands have been finished.


getQueue

public RenderQueue getQueue()
Get the render queue associated with this Renderer.

Returns:
RenderQueue

isProcessingQueue

public boolean isProcessingQueue()
Return true if this renderer is in the middle of processing its RenderQueue.

Returns:
boolean

checkAndAdd

public abstract boolean checkAndAdd(Spatial s)
Check a given Spatial to see if it should be queued. return true if it was queued.

Parameters:
s - Spatial to check
Returns:
true if it was queued.

supportsVBO

public abstract boolean supportsVBO()
Return true if the system running this supports VBO

Returns:
boolean

isHeadless

public boolean isHeadless()
See Renderer.isHeadless()

Returns:
boolean

setHeadless

public void setHeadless(boolean headless)
See Renderer.setHeadless()


getWidth

public int getWidth()
Retrieve the width set on this renderer.

Returns:
width

getHeight

public int getHeight()
Retrieve the height set on this renderer.

Returns:
height

reinit

public abstract void reinit(int width,
                            int height)
Reinitialize the renderer with the given width/height. Also calls resize on the attached camera if present.

Parameters:
width - int
height - int

createDisplayList

public abstract int createDisplayList(Geometry geom)
Generate a DisplayList for drawing the given Geometry.

Parameters:
geom - the geometry to make a display list for
Returns:
the id of the list

releaseDisplayList

public abstract void releaseDisplayList(int listId)
Releases a DisplayList from the card.

Parameters:
listId - the id of the display list to release

setPolygonOffset

public abstract void setPolygonOffset(float factor,
                                      float offset)
Sets an offset to the zbuffer to be used when comparing an incoming polygon for depth buffer pass/fail.

Parameters:
factor - Specifies a scale factor that is used to create a variable depth offset for each polygon. The initial value is 0.
offset - Is multiplied by an implementation-specific value to create a constant depth offset. The initial value is 0.

clearPolygonOffset

public abstract void clearPolygonOffset()
Removes any previously set offset from the renderer.


deleteVBO

public abstract void deleteVBO(java.nio.Buffer buffer)
Checks the VBO cache to see if this Buffer is mapped to a VBO-id. If it does the mapping will be removed from the cache and the VBO with the VBO-id found will be deleted. If no mapped VBO-id is found, this method does not do anything else.

Parameters:
buffer - The Buffer who's associated VBO should be deleted.

deleteVBO

public abstract void deleteVBO(int vboid)
Attempts to delete the VBO with this VBO id. Ignores ids < 1.

Parameters:
vboid -

clearVBOCache

public abstract void clearVBOCache()
Clears all entries from the VBO cache. Does not actually delete any VBO buffer, only all mappings between Buffers and VBO-ids.


removeFromVBOCache

public abstract java.lang.Integer removeFromVBOCache(java.nio.Buffer buffer)
Removes the mapping between this Buffer and it's VBO-id. Does not actually delete the VBO.
This method is usefull if you want to use the same Buffer to create several VBOs. After a VBO is created for this Buffer, update the Buffer and remove it from the VBO cache. You can now reuse the same buffer with another Geometry object.
If no association is found, this method does nothing.

Parameters:
buffer - The nio Buffer whose associated VBO should be deleted.
Returns:
An int wrapped in an Integer object that's the VBO-id of the VBO previously mapped to this Buffer, or null is no mapping existed.

createState

public RenderState createState(int type)
Deprecated. As of 2.0, use createState(com.jme.scene.state.RenderState.StateType) instead.

Create a renderstate via a given renderstate type.

Parameters:
type - one of RenderState.RS_****
Returns:
the new RenderState or null if an invalid type is given.

createState

public RenderState createState(RenderState.StateType type)
Create a RenderState via a given RenderState.StateType type.

Parameters:
types - one of RenderState.StateType types
Returns:
the new RenderState or null if an invalid type is given.

createLineRecord

public abstract StateRecord createLineRecord()
Returns:
a generated StateRecord representing gl line values for a gl context.

createRendererRecord

public abstract StateRecord createRendererRecord()
Returns:
a generated StateRecord representing basic values for this renderer context.

updateTextureSubImage

public abstract void updateTextureSubImage(Texture dstTexture,
                                           int dstX,
                                           int dstY,
                                           Image srcImage,
                                           int srcX,
                                           int srcY,
                                           int width,
                                           int height)
                                    throws JmeException,
                                           java.lang.UnsupportedOperationException
Updates a region of the content area of the provided texture using the specified region of the given data.

Parameters:
dstTexture - the texture to be updated
dstX - the x offset relative to the lower-left corner of this texture where the update will be applied
dstY - the y offset relative to the lower-left corner of this texture where the update will be applied
srcImage - the image data to be uploaded to the texture
srcX - the x offset relative to the lower-left corner of the supplied buffer from which to fetch the update rectangle
srcY - the y offset relative to the lower-left corner of the supplied buffer from which to fetch the update rectangle
width - the width of the region to be updated
height - the height of the region to be updated
Throws:
JmeException - if unable to update the texture
java.lang.UnsupportedOperationException - if updating for the provided texture type is unsupported
Since:
2.0
See Also:
com.sun.opengl.util.texture.Texture#updateSubImage(com.sun.opengl.util.texture.TextureData, int, int, int, int, int, int, int)

checkCardError

public abstract void checkCardError()
                             throws JmeException
Check the underlying rendering system (opengl, etc.) for exceptions.

Throws:
JmeException - if an error is found.

cleanup

public abstract void cleanup()
Perform any necessary cleanup operations such as deleting VBOs, etc.