com.jme.system
Class DisplaySystem

java.lang.Object
  extended by com.jme.system.DisplaySystem
Direct Known Subclasses:
DummyDisplaySystem, JOGLDisplaySystem, LWJGLDisplaySystem

public abstract class DisplaySystem
extends java.lang.Object

DisplaySystem defines an interface for system creation. Specifically, any implementing class will create a window for rendering. It also should create the appropriate Renderer object that allows the client to render to this window.

Implementing classes should check for the appropriate libraries to insure these libraries are indeed installed on the system. This will allow users to cleanly exit if an improper library was chosen for rendering.

Example usage:

DisplaySystem ds = DisplaySystem.getDisplaySystem();
ds.createWindow(640,480,32,60,true);
Renderer r = ds.getRenderer();

Version:
$Id: DisplaySystem.java 4131 2009-03-19 20:15:28Z blaine.dev $
Author:
Mark Powell, Gregg Patton, Joshua Slack - Optimizations, Headless rendering, RenderContexts, AWT integration
See Also:
Renderer

Field Summary
protected  int alphaBits
          Alpha bits to use for the renderer.
protected  int bpp
          Bit depth selected for renderer.
protected  float brightness
          Brightness value of display - default is 0f.
protected  float contrast
          Contrast value of display - default is 1.0f.
protected  boolean created
          Is the display created already?
protected  int depthBits
          Depth bits to use for the renderer.
protected  int frq
          Frequency selected for renderer.
protected  boolean fs
          Is the display full screen?
protected  float gamma
          Gamma value of display - default is 1.0f.
protected  int height
          height selected for the renderer.
protected  int samples
          Number of samples to use for the multisample buffer.
protected  int stencilBits
          Stencil bits to use for the renderer.
protected  int width
          Width selected for the renderer.
 
Constructor Summary
protected DisplaySystem()
          A new display system has been created.
 
Method Summary
abstract  void close()
          close shutdowns and destroys any window contexts.
 JMECanvas createCanvas(int w, int h)
          createCanvas should create a canvas object with the desired settings.
abstract  JMECanvas createCanvas(int w, int h, java.lang.String type, java.util.HashMap<java.lang.String,java.lang.Object> props)
          createCanvas should create a canvas object with the desired settings.
abstract  void createHeadlessWindow(int w, int h, int bpp)
          createHeadlessWindow creates a headless window with the desired settings.
abstract  TextureRenderer createTextureRenderer(int width, int height, TextureRenderer.Target target)
          Create a TextureRenderer using the underlying system.
abstract  void createWindow(int w, int h, int bpp, int frq, boolean fs)
          createWindow creates a window with the desired settings.
abstract  java.lang.String getAdapter()
          getAdapter returns the name of the underlying system's graphics adapter for debugging / display purposes.
 int getBitDepth()
          Returns the set bitdepth for the display system.
 float getBrightness()
          Returns the brightness last requested by this display.
 float getContrast()
           
abstract  RenderContext<?> getCurrentContext()
           
abstract  java.lang.String getDisplayAPIVersion()
          getDisplayAPIVersion returns the API version supported
abstract  java.lang.String getDisplayRenderer()
          getDisplayRenderer returns details of the adapter
static DisplaySystem getDisplaySystem()
          Returns the currently created display system.
static DisplaySystem getDisplaySystem(java.lang.String key)
          getDisplaySystem is a factory method that creates the appropriate display system specified by the key parameter.
abstract  java.lang.String getDisplayVendor()
          getDisplayVendor returns the vendor of the graphics adapter
abstract  java.lang.String getDriverVersion()
          getDriverVersion returns a string representing the version of driver installed on the underlying system.
 int getFrequency()
          Returns the set frequency for the display system.
 float getGamma()
           
 int getHeight()
          Returns the set height for the display system.
 int getMinAlphaBits()
          Returns the minimum bits per pixel in the alpha buffer.
 int getMinDepthBits()
          Returns the minimum bits per pixel in the depth buffer.
 int getMinSamples()
          Returns the minimum samples in multisample buffer.
 int getMinStencilBits()
          Returns the minimum bits per pixel in the stencil buffer.
 Ray getPickRay(Vector2f screenPosition, boolean flipVertical, Ray store)
          Generate a pick ray from a 2d screen point.
abstract  Renderer getRenderer()
          getRenderer returns the Renderer implementation that is compatible with the chosen DisplaySystem.
 Vector3f getScreenCoordinates(Vector3f worldPosition)
          Translate world to screen coordinates
 Vector3f getScreenCoordinates(Vector3f worldPosition, Vector3f store)
          Translate world to screen coordinates
static SystemProvider getSystemProvider()
          Returns the currently system provider.
static java.lang.String[] getSystemProviderIdentifiers()
          Returns all available system providers
 int getWidth()
          Returns the set width for the display system.
 Vector3f getWorldCoordinates(Vector2f screenPosition, float zPos)
          Translate screen to world coordinates.
 Vector3f getWorldCoordinates(Vector2f screenPosition, float zPos, Vector3f store)
          Translate screen to world coordinates.
abstract  boolean isActive()
          isActive returns true if the display is active.
abstract  boolean isClosing()
          isClosing notifies if the window is currently closing.
 boolean isCreated()
          isCreated returns the current status of the display system.
 boolean isFullScreen()
          Returns whether or not the display system is set to be full screen.
abstract  boolean isValidDisplayMode(int width, int height, int bpp, int freq)
          isValidDisplayMode determines if the given parameters constitute a valid display mode on this system.
 CanvasConstructor makeCanvasConstructor(java.lang.String type)
           
abstract  void moveWindowTo(int locX, int locY)
          If running in windowed mode, move the window's position to the given display coordinates.
abstract  void recreateWindow(int w, int h, int bpp, int frq, boolean fs)
          recreateWindow recreates a window with the desired settings.
 void registerCanvasConstructor(java.lang.String type, java.lang.Class<? extends CanvasConstructor> constructorClass)
           
abstract  void reset()
          reset cleans up the display system for closing or restarting.
static void resetSystemProvider()
           
 void setBrightness(float brightness)
          Note: This affects the whole screen, not just the game window.
 void setBrightnessGammaContrast(float brightness, float gamma, float contrast)
          Sets all three in one call.
 void setContrast(float contrast)
          Note: This affects the whole screen, not just the game window.
 void setGamma(float gamma)
          Note: This affects the whole screen, not just the game window.
 void setHeight(int height)
          Sets a new height for the display system
abstract  void setIcon(Image[] iconImages)
          Sets one or more icons for the DisplaySystem.
 void setMinAlphaBits(int alphaBits)
          Sets the minimum bits per pixel in the alpha buffer.
 void setMinDepthBits(int depthBits)
          Sets the minimum bits per pixel in the depth buffer.
 void setMinSamples(int samples)
          Sets the minimum samples in the multisample buffer.
 void setMinStencilBits(int stencilBits)
          Sets the minimum bits per pixel in the stencil buffer.
abstract  void setRenderer(Renderer r)
          setRenderer sets the Renderer object that is to be used by this display.
static void setSystemProvider(SystemProvider provider)
          Sets the SystemProvider to be provider.
abstract  void setTitle(java.lang.String title)
          Sets the title of the display system.
abstract  void setVSyncEnabled(boolean enabled)
          setVSyncEnabled attempts to enable or disable monitor vertical synchronization.
 void setWidth(int width)
          Sets a new width for the display system
protected abstract  void updateDisplayBGC()
          Update the display's gamma, brightness and contrast based on the set values.
static void updateStates(Renderer r)
          Called when the display system is created, this function sets the default render states for the renderer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected int width
Width selected for the renderer.


height

protected int height
height selected for the renderer.


bpp

protected int bpp
Bit depth selected for renderer.


frq

protected int frq
Frequency selected for renderer.


fs

protected boolean fs
Is the display full screen?


created

protected boolean created
Is the display created already?


alphaBits

protected int alphaBits
Alpha bits to use for the renderer.


depthBits

protected int depthBits
Depth bits to use for the renderer.


stencilBits

protected int stencilBits
Stencil bits to use for the renderer.


samples

protected int samples
Number of samples to use for the multisample buffer.


gamma

protected float gamma
Gamma value of display - default is 1.0f. 0->infinity


brightness

protected float brightness
Brightness value of display - default is 0f. -1.0 -> 1.0


contrast

protected float contrast
Contrast value of display - default is 1.0f. 0->infinity

Constructor Detail

DisplaySystem

protected DisplaySystem()
A new display system has been created. The default static display system is set to the newly created display system.

Method Detail

getDisplaySystem

public static DisplaySystem getDisplaySystem(java.lang.String key)
getDisplaySystem is a factory method that creates the appropriate display system specified by the key parameter. If the key given is not a valid identifier for a specific display system, the fallback default is returned.

Parameters:
key - the display system to use.
Returns:
the appropriate display system specified by the key.

getSystemProviderIdentifiers

public static java.lang.String[] getSystemProviderIdentifiers()
Returns all available system providers

Returns:
String array containing all available system providers

getSystemProvider

public static SystemProvider getSystemProvider()
Returns the currently system provider. If no system provider has been set, then a default LWJGL system provider is used.

Returns:
The current system provider.

setSystemProvider

public static void setSystemProvider(SystemProvider provider)
                              throws java.lang.IllegalStateException
Sets the SystemProvider to be provider.

Once installed, the provider cannot be replaced.

Parameters:
provider - the SystemProvider to install. if null, no provider is set.
Throws:
java.lang.IllegalStateException - if a provider was previous installed.
Since:
2.0

getDisplaySystem

public static DisplaySystem getDisplaySystem()
Returns the currently created display system.

Returns:
The current display system.

setWidth

public void setWidth(int width)
Sets a new width for the display system

Parameters:
width -

getWidth

public int getWidth()
Returns the set width for the display system.

Returns:
The set width.

setHeight

public void setHeight(int height)
Sets a new height for the display system

Parameters:
height -

getHeight

public int getHeight()
Returns the set height for the display system.

Returns:
The set height.

getBitDepth

public int getBitDepth()
Returns the set bitdepth for the display system.

Returns:
the set bit depth

getFrequency

public int getFrequency()
Returns the set frequency for the display system.

Returns:
the set frequency

isFullScreen

public boolean isFullScreen()
Returns whether or not the display system is set to be full screen.

Returns:
true if full screen

getAdapter

public abstract java.lang.String getAdapter()
getAdapter returns the name of the underlying system's graphics adapter for debugging / display purposes.

Returns:
the adapter's name as a String

getDriverVersion

public abstract java.lang.String getDriverVersion()
getDriverVersion returns a string representing the version of driver installed on the underlying system.

Returns:
the version as a String

getDisplayVendor

public abstract java.lang.String getDisplayVendor()
getDisplayVendor returns the vendor of the graphics adapter

Returns:
The adapter vendor

getDisplayRenderer

public abstract java.lang.String getDisplayRenderer()
getDisplayRenderer returns details of the adapter

Returns:
The adapter details

getDisplayAPIVersion

public abstract java.lang.String getDisplayAPIVersion()
getDisplayAPIVersion returns the API version supported

Returns:
The api version supported

isValidDisplayMode

public abstract boolean isValidDisplayMode(int width,
                                           int height,
                                           int bpp,
                                           int freq)
isValidDisplayMode determines if the given parameters constitute a valid display mode on this system. Returning true does not necessarily guarantee that the system is capable of running in the specified display mode, merely that it believes it is possible.

Parameters:
width - the width/horizontal resolution of the display.
height - the height/vertical resolution of the display.
bpp - the bit depth of the display.
freq - the frequency of refresh of the display (in Hz).

setVSyncEnabled

public abstract void setVSyncEnabled(boolean enabled)
setVSyncEnabled attempts to enable or disable monitor vertical synchronization. The method is a "best attempt" to change the monitor vertical refresh synchronization, and is not guaranteed to be successful. This is dependant on OS.

Parameters:
enabled - true to synchronize, false to ignore synchronization

setTitle

public abstract void setTitle(java.lang.String title)
Sets the title of the display system. This is usually reflected by the renderer as text in the menu bar.

Parameters:
title - The new display title.

createWindow

public abstract void createWindow(int w,
                                  int h,
                                  int bpp,
                                  int frq,
                                  boolean fs)
createWindow creates a window with the desired settings. The width and height defined by w and h define the size of the window if fullscreen is false, otherwise it defines the resolution of the fullscreen display. The color depth is defined by bpp. The implementing class should only allow 16, 24, and 32. The monitor frequency is defined by the frq parameter and should not exceed the capabilities of the connected hardware, the implementing class should attempt to assure this does not happen. Lastly, the boolean flag fs determines if the display should be windowed or fullscreen. If false, windowed is chosen. This window will be placed in the center of the screen initially. If true fullscreen mode will be entered with the appropriate settings.

Parameters:
w - the width/horizontal resolution of the display.
h - the height/vertical resolution of the display.
bpp - the color depth of the display.
frq - the frequency of refresh of the display.
fs - flag determining if fullscreen is to be used or not. True will use fullscreen, false will use windowed mode.

createHeadlessWindow

public abstract void createHeadlessWindow(int w,
                                          int h,
                                          int bpp)
createHeadlessWindow creates a headless window with the desired settings. A headless window is a rendering target that is not shown on screen. It is useful for doing offline rendering, integration and so forth. You can not have a regular and headless window at the same time. The width and height defined by w and h define the size of the window. The color depth is defined by bpp.

Parameters:
w - the width/horizontal resolution of the display.
h - the height/vertical resolution of the display.
bpp - the color depth of the display.

createCanvas

public JMECanvas createCanvas(int w,
                              int h)
createCanvas should create a canvas object with the desired settings. The width and height defined by w and h define the size of the canvas. Makes an AWT canvas by default.

Parameters:
w - the width/horizontal resolution of the display.
h - the height/vertical resolution of the display.

createCanvas

public abstract JMECanvas createCanvas(int w,
                                       int h,
                                       java.lang.String type,
                                       java.util.HashMap<java.lang.String,java.lang.Object> props)
createCanvas should create a canvas object with the desired settings. The width and height defined by w and h define the size of the canvas.

Parameters:
w - the width/horizontal resolution of the display.
h - the height/vertical resolution of the display.
type - the type of canvas to make. e.g. "AWT", "SWT".
props - the properties we want to use (if any) for constructing our canvas.

registerCanvasConstructor

public void registerCanvasConstructor(java.lang.String type,
                                      java.lang.Class<? extends CanvasConstructor> constructorClass)

makeCanvasConstructor

public CanvasConstructor makeCanvasConstructor(java.lang.String type)

recreateWindow

public abstract void recreateWindow(int w,
                                    int h,
                                    int bpp,
                                    int frq,
                                    boolean fs)
recreateWindow recreates a window with the desired settings.

Parameters:
w - the width/horizontal resolution of the display.
h - the height/vertical resolution of the display.
bpp - the color depth of the display.
frq - the frequency of refresh of the display.
fs - flag determining if fullscreen is to be used or not. True will use fullscreen, false will use windowed mode.

getRenderer

public abstract Renderer getRenderer()
getRenderer returns the Renderer implementation that is compatible with the chosen DisplaySystem. For example, if LWJGLDisplaySystem is used, the returned Renderer will be LWJGLRenderer.

Returns:
the appropriate Renderer implementation that is compatible with the used DisplaySystem.
See Also:
Renderer

setRenderer

public abstract void setRenderer(Renderer r)
setRenderer sets the Renderer object that is to be used by this display. The implementing class should take measures to insure that the given Renderer is compatible with the Display.

Parameters:
r - the Renderer to set for this display.

isCreated

public boolean isCreated()
isCreated returns the current status of the display system. If the window and renderer are created, true is returned, otherwise false.

Returns:
whether the display system is created.

isActive

public abstract boolean isActive()
isActive returns true if the display is active.

Returns:
whether the display system is active.

isClosing

public abstract boolean isClosing()
isClosing notifies if the window is currently closing. This could be caused via the application itself or external interrupts such as alt-f4 etc.

Returns:
true if the window is closing, false otherwise.

reset

public abstract void reset()
reset cleans up the display system for closing or restarting.


close

public abstract void close()
close shutdowns and destroys any window contexts.


getMinAlphaBits

public int getMinAlphaBits()
Returns the minimum bits per pixel in the alpha buffer.

Returns:
the int value of alphaBits.

setMinAlphaBits

public void setMinAlphaBits(int alphaBits)
Sets the minimum bits per pixel in the alpha buffer.

Parameters:
alphaBits - - the new value for alphaBits

getMinDepthBits

public int getMinDepthBits()
Returns the minimum bits per pixel in the depth buffer.

Returns:
the int value of depthBits.

setMinDepthBits

public void setMinDepthBits(int depthBits)
Sets the minimum bits per pixel in the depth buffer.

Parameters:
depthBits - - the new value for depthBits

getMinStencilBits

public int getMinStencilBits()
Returns the minimum bits per pixel in the stencil buffer.

Returns:
the int value of stencilBits.

setMinStencilBits

public void setMinStencilBits(int stencilBits)
Sets the minimum bits per pixel in the stencil buffer.

Parameters:
stencilBits - - the new value for stencilBits

getMinSamples

public int getMinSamples()
Returns the minimum samples in multisample buffer.

Returns:
the int value of samples.

setMinSamples

public void setMinSamples(int samples)
Sets the minimum samples in the multisample buffer.

Parameters:
samples - - the new value for samples

getBrightness

public float getBrightness()
Returns the brightness last requested by this display.

Returns:
brightness - should be between -1 and 1.

setBrightness

public void setBrightness(float brightness)
Note: This affects the whole screen, not just the game window.

Parameters:
brightness - The brightness to set (set -1 to 1) default is 0

getContrast

public float getContrast()
Returns:
Returns the contrast.

setContrast

public void setContrast(float contrast)
Note: This affects the whole screen, not just the game window.

Parameters:
contrast - The contrast to set (set greater than 0) default is 1

getGamma

public float getGamma()
Returns:
Returns the gamma.

setGamma

public void setGamma(float gamma)
Note: This affects the whole screen, not just the game window.

Parameters:
gamma - The gamma to set (default is 1)

setBrightnessGammaContrast

public void setBrightnessGammaContrast(float brightness,
                                       float gamma,
                                       float contrast)
Sets all three in one call.

Note: This affects the whole screen, not just the game window.

Parameters:
brightness -
gamma -
contrast -

updateStates

public static void updateStates(Renderer r)
Called when the display system is created, this function sets the default render states for the renderer. It should not be called directly by the user.

Parameters:
r - The renderer to get the default states from.

createTextureRenderer

public abstract TextureRenderer createTextureRenderer(int width,
                                                      int height,
                                                      TextureRenderer.Target target)
Create a TextureRenderer using the underlying system.

Parameters:
width - width of texture
height - height of texture
target -
Returns:
A TextureRenderer for the display system.

getScreenCoordinates

public Vector3f getScreenCoordinates(Vector3f worldPosition)
Translate world to screen coordinates

Parameters:
worldPosition - Vector3f representing the world position to retrieve.
Returns:
the screen position.

getScreenCoordinates

public Vector3f getScreenCoordinates(Vector3f worldPosition,
                                     Vector3f store)
Translate world to screen coordinates

Parameters:
worldPosition - Vector3f representing the world position to retrieve.
store - Vector3f to store the world position in.
Returns:
Vector3f The store vector3f, after storing.

getWorldCoordinates

public Vector3f getWorldCoordinates(Vector2f screenPosition,
                                    float zPos)
Translate screen to world coordinates.

Parameters:
screenPosition - Vector2f representing the screen position with 0,0 at the bottom left.
zPos - The z position away from the viewing plane, between 0 and 1.
Returns:
A Vector3f representing the vector's world position.

getWorldCoordinates

public Vector3f getWorldCoordinates(Vector2f screenPosition,
                                    float zPos,
                                    Vector3f store)
Translate screen to world coordinates.

Parameters:
screenPosition - Vector2f representing the screen position with 0,0 at the bottom left
zPos - float The z position away from the viewing plane.
store - Vector3f The vector to store the result in.
Returns:
Vector3f The store vector, after storing it's result.

getPickRay

public Ray getPickRay(Vector2f screenPosition,
                      boolean flipVertical,
                      Ray store)
Generate a pick ray from a 2d screen point. The screen point is assumed to have origin at the lower left, but when using awt mouse clicks, you'll want to set flipVertical to true since that system has an origin at the upper right. The Ray will be in world coordinates and the direction will be normalized.

Parameters:
screenPosition - Vector2f representing the screen position with 0,0 at the bottom left
flipVertical - Whether or not to flip the y coordinate of the screen position across the middle of the screen.
store - The ray to store the result in. If null, a new Ray is created.
Returns:
the ray

updateDisplayBGC

protected abstract void updateDisplayBGC()
Update the display's gamma, brightness and contrast based on the set values.


setIcon

public abstract void setIcon(Image[] iconImages)
Sets one or more icons for the DisplaySystem.

As a reference for usual platforms on number of icons and their sizes:

Images should be in format RGBA8888. If they are not jME will try to convert them using ImageUtils. If that fails a JmeException could be thrown.

Parameters:
iconImages - Array of Images to be used as icons.

getCurrentContext

public abstract RenderContext<?> getCurrentContext()
Returns:
a RenderContext object representing the current OpenGL context.

resetSystemProvider

public static void resetSystemProvider()

moveWindowTo

public abstract void moveWindowTo(int locX,
                                  int locY)
If running in windowed mode, move the window's position to the given display coordinates.

Parameters:
locX -
locY -