see Javadoc

The Renderer defines exactly how geometrical elements will be displayed to the screen. It's an abstract class that does not particularly care about how the implementing class is displaying the information. This also means, that a jME application need not care how the actual rendering is being handled. It could be making use of the LWJGL API, JOGL API, a software renderer, or any other rendering API that might be supported.

The concrete Renderer object will be created by the DisplaySystem class during the creation of the window. This is the object that all jME applications should use for displaying graphics.

Renderer also provides the means to obtain RenderState objects. This method of obtaining the RenderState objects ensures that the properly configured state is provided to you. This also means, that you can, at any time, change the Renderer type without affecting the jME application.

Renderer provides the means for the client application to interact with the display buffer. This includes rendering geometry, clearing the screen, setting the mode (Ortho vs. Perspective), etc. Typically, the display method of the jME application will consist of two calls to the Renderer, clearing the buffers and rendering the data.

As stated above, creation of the Renderer occurs during the creation of the DisplaySystem. The DisplaySystem creates the type of Renderer requested by the user. For instance, if an LWJGLDisplaySystem is created (DisplaySystem.getDisplaySystem(“LWJGL”)) then it will create an instance of LWJGLRenderer.

You may then obtain the Renderer via DisplaySystem's getRenderer method. You can then draw (actually send data for display) any Geometry (display.getRenderer().draw(myGeometry)), and swap the buffers to show the data on the screen.

The order of which the geometry is rendered is dependant on its place in the RenderQueue and can be found explained in detail there. However, Renderer maintains constants (QUEUE_INHERIT, QUEUE_SKIP, QUEUE_OPAQUE, QUEUE_TRANSPARENT, QUEUE_ORTHO). The standard steps for drawing using the renderer are:

1. Clear the current buffer
2. Call the draw method on the Geometry to render
3. Display the back buffer (the new screen)

Statistics to the scene (Number of vertices and Number of triangles rendered) can be obtained via the Renderer. This is the data that is commonly shown on the SimpleGame demos. This is done via clearStatistics (to reset the count for the frame) and getStatistics (to get the count for the frame). Statistics can be enabled or disabled via a call to enableStatistics.

Additionally, Renderer is capable of taking a screenshot of the current display. This basically involves obtaining the data from the last rendered frame and writing it out to a PNG image. A call to takeScreenShot with the filename (the filename should not contain the file extension, as it's always going to be .png). This PNG image will be written out to the running directory.

//Create a display system using the values from the properties dialog
DisplaySystem display = DisplaySystem.getDisplaySystem(properties.getRenderer());
/** Create a window with the startup box's information. */
display.createWindow(
          properties.getWidth(),
          properties.getHeight(),
          properties.getDepth(),
          properties.getFreq(),
          properties.getFullscreen());
 
//Now that the display system is created, we can obtain the appropriate Renderer
Renderer r = display.getRenderer();

In the above example PropertiesIO was used to obtain: Renderer type, width, height, depth, frequency and fullscreen mode.

//A main game loop that continually renders a piece of Geometry (myGeom)
//We are assuming the display has been created above
while (!finished) {
 
    //clear the buffer
    display.getRenderer().clearBuffers();
    //draw the geometry
    display.getRenderer().draw(myGeom);
    //swap the buffers
    display.getRenderer().displayBackBuffer();
}

//This code displays some geometry and prints the statistics to the 
//console.
 
display.getRenderer().enableStatistics(true);
 
while (!finished) {
 
    //clear the buffer
    display.getRenderer().clearBuffers();
    //clear the stats
    display.getRenderer().clearStatistics();
    //draw the geometry
    display.getRenderer().draw(myGeom);
    //Print out the stats
    System.out.println(display.getRenderer().getStatistics());
    //swap the buffers
    display.getRenderer().displayBackBuffer();
}

<DisplaySystem|User's Guide|TextureRenderer>