org.xith3d.loop
Class RenderLoop

java.lang.Object
  extended by org.xith3d.loop.UpdatingThread
      extended by org.xith3d.loop.RenderLoop
All Implemented Interfaces:
java.lang.Runnable, GameTimeHost, RenderLoopController, Updatable, Updater
Direct Known Subclasses:
InputAdapterRenderLoop

public class RenderLoop
extends UpdatingThread
implements Updater, RenderLoopController

This loop renders the scene in a separate thread. You can schedule operations to be done by the thread in the next loop iteration.

See Also:
You can schedule animations to be done by the thread in the next loop iteration., You can get the fps count from this loop and set the maximum FPS., FPSListener

Nested Class Summary
static class RenderLoop.RunMode
          You can start the RenderLoop in the same Thread as the app itself or in a separate one.
static class RenderLoop.StopOperation
          Use this enum for the setStopOperation() method.
 
Nested classes/interfaces inherited from class org.xith3d.loop.UpdatingThread
UpdatingThread.TimingMode
 
Field Summary
static int PAUSE_RENDERING
           
 
Fields inherited from class org.xith3d.loop.UpdatingThread
PAUSE_NONE, PAUSE_TOTAL
 
Constructor Summary
RenderLoop()
          Creates a new instance
RenderLoop(float maxFPS)
          Creates a new instance
RenderLoop(Xith3DEnvironment x3dEnv)
          Creates a new instance
RenderLoop(Xith3DEnvironment x3dEnv, float maxFPS)
          Creates a new instance
 
Method Summary
 void addFPSListener(FPSListener l)
          Adds a new FPSListener to this loop to be notified periodically.
 void addRenderLoopListener(RenderLoopListener l)
          Adds a new RenderLoopListener to this loop.
 void addUpdatable(Updatable updatable)
          Adds a new Updatable instance to the list, that is worked each frame.
 void begin()
          Starts this rendering-loop in the same Thread and with TimingMode.MICROSECONDS.
 void begin(RenderLoop.RunMode runMode)
          Starts this rendering-loop with TimingMode.MICROSECONDS.
 void begin(RenderLoop.RunMode runMode, UpdatingThread.TimingMode timingMode)
          Starts this RenderLoop.
 void begin(UpdatingThread.TimingMode timingMode)
          Starts this rendering-loop in the same Thread.
protected  void destroy()
          This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY or DESTROY_AND_EXIT.
protected  void destroyAndExit()
          This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY_AND_EXIT.
 void end()
          
protected  void exit()
          This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY_AND_EXIT.
 Animator getAnimator()
           
 float getFPS()
           
 long getFPSCalcInterval()
           
 float getMaxFPS()
           
 OperationScheduler getOperationScheduler()
           
 RenderLoop.RunMode getRunMode()
           
 RenderLoop.StopOperation getStopOperation()
           
 java.lang.Thread getThread()
          
 float getTotalAverageFPS()
           
 Updater getUpdater()
           
 Xith3DEnvironment getXith3DEnvironment()
           
protected  void loop()
          This method defines the main loop of the Thread.
protected  void loopIteration(long gameTime, long frameTime, UpdatingThread.TimingMode timingMode)
          This method is called each loop iteration.
 long nextFrame()
          If the RenderLoop is currently running in RUN_IN_SEPARATE_THREAD_AND_WAIT RunMode the next iteration is allowed and executed asynchronously. -1 is returned as the frame time, because it is not defined at this time.
protected  long nextIteration(boolean force)
          
protected  void onFPSCountIntervalHit(float fps)
          This method is called by the render loop each counting interval
protected  void onRenderLoopPaused(long gameTime, UpdatingThread.TimingMode timingMode, int pauseMode)
          This event is fired by the RenderLoop when the pauseMode has been increased.
protected  void onRenderLoopResumed(long gameTime, UpdatingThread.TimingMode timingMode, int pauseMode)
          This event is fired by the RenderLoop when the pauseMode has been released.
protected  void onRenderLoopStarted()
          This method is executed by the RenderLoop when the thread has been started.
protected  void onRenderLoopStopped(long gameTime, UpdatingThread.TimingMode timingMode, float averageFPS)
          This method is executed by the RenderLoop when the thread has been stopped.
 void pauseRendering()
          pauses rendering in this RenderLoop
protected  void prepareNextFrame(long gameTime, long frameTime, UpdatingThread.TimingMode timingMode)
          This method is called each loop iteration before the renderNextFrame() methiod.
 void removeFPSListener(FPSListener l)
          Removes an FPSListener from this loop.
 void removeRenderLoopListener(RenderLoopListener l)
          Removes a RenderLoopListener from this loop.
 void removeUpdatable(Updatable updatable)
          Removes an Updatable instance from the list, that is worked each frame.
protected  void renderNextFrame(long gameTime, long frameTime, UpdatingThread.TimingMode timingMode)
          Just calls the render() method on the linked Xith3DEnvironment.
 void resumeRendering()
          resumes rendering in this RenderLoop
 void run()
          
 void setFPSCalcInterval(long micros)
          Sets the interval in which the FPS are recalculated
 void setMaxFPS(float maxFPS)
          Sets the maximum frames per second.
 void setOperationScheduler(OperationScheduler opScheder)
          Sets the OperationScheduler to be used by this RenderLoop (can be null).
 void setStopOperation(RenderLoop.StopOperation operation)
          Sets the StopOperation to invoke when the RenderLoop stops.
 void setUpdater(Updater updater)
          Sets the Updater, that manages the Updatables.
 void setXith3DEnvironment(Xith3DEnvironment env)
          Sets the Xith3DEnvironment to this RenderLoop to be updated frame-by-frame.
 void update(long gameTime, long frameTime, UpdatingThread.TimingMode timingMode)
          Updates this Updatable object.
 
Methods inherited from class org.xith3d.loop.UpdatingThread
begin, getFPSLimiter, getGameMicroTime, getGameMilliTime, getGameNanoTime, getGameTime, getIterationsCount, getLastFrameTime, getLastNanoFrameTime, getMinIterationTime, getPauseMode, getTimer, getTimingMode, isRunning, isStopping, setFPSLimiter, setMinIterationTime, setPauseMode, setTimer, setTimingMode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PAUSE_RENDERING

public static final int PAUSE_RENDERING
See Also:
Constant Field Values
Constructor Detail

RenderLoop

public RenderLoop(Xith3DEnvironment x3dEnv,
                  float maxFPS)
Creates a new instance

Parameters:
x3dEnv - the Xith3DEnvironment to be linked with this RenderLoop.
maxFPS - the maximum FPS to render at

RenderLoop

public RenderLoop(float maxFPS)
Creates a new instance

Parameters:
maxFPS - the maximum FPS to render at

RenderLoop

public RenderLoop(Xith3DEnvironment x3dEnv)
Creates a new instance

Parameters:
x3dEnv - the Xith3DEnvironment to be linked with this RenderLoop.

RenderLoop

public RenderLoop()
Creates a new instance

Method Detail

getRunMode

public RenderLoop.RunMode getRunMode()
Returns:
the RunMode this RenderLoop is running in. Returns null, if the RenderLoop hasn't been started.
See Also:
RenderLoop.RunMode

setStopOperation

public void setStopOperation(RenderLoop.StopOperation operation)
Sets the StopOperation to invoke when the RenderLoop stops.

Parameters:
operation -
See Also:
RenderLoop.StopOperation

getStopOperation

public RenderLoop.StopOperation getStopOperation()
Returns:
the StopOperation to invoke when the RenderLoop stops.
See Also:
RenderLoop.StopOperation

setOperationScheduler

public void setOperationScheduler(OperationScheduler opScheder)
Sets the OperationScheduler to be used by this RenderLoop (can be null).

Parameters:
opScheder -

getOperationScheduler

public final OperationScheduler getOperationScheduler()
Returns:
the OperationScheduler used by this RenderLoop.

getAnimator

public Animator getAnimator()
Returns:
the Animator used by this RenderLoop

addFPSListener

public void addFPSListener(FPSListener l)
Adds a new FPSListener to this loop to be notified periodically.

Parameters:
l - the new FPSListener

removeFPSListener

public void removeFPSListener(FPSListener l)
Removes an FPSListener from this loop.

Parameters:
l - the FPSListener to be removed

setUpdater

public void setUpdater(Updater updater)
Sets the Updater, that manages the Updatables.


getUpdater

public final Updater getUpdater()
Returns:
the Updater, that manages the Updatables.

addUpdatable

public final void addUpdatable(Updatable updatable)
Adds a new Updatable instance to the list, that is worked each frame. This is like adding a ScheduledOperation, that is infinitely alive and persistent.

Specified by:
addUpdatable in interface Updater

removeUpdatable

public final void removeUpdatable(Updatable updatable)
Removes an Updatable instance from the list, that is worked each frame.

Specified by:
removeUpdatable in interface Updater

addRenderLoopListener

public void addRenderLoopListener(RenderLoopListener l)
Adds a new RenderLoopListener to this loop.

Parameters:
l - the new RenderLoopListener

removeRenderLoopListener

public void removeRenderLoopListener(RenderLoopListener l)
Removes a RenderLoopListener from this loop.

Parameters:
l - the RenderLoopListener to be removed

setXith3DEnvironment

public void setXith3DEnvironment(Xith3DEnvironment env)
Sets the Xith3DEnvironment to this RenderLoop to be updated frame-by-frame.

Parameters:
env - the Xith3DEnvironment to be updated by this loop

getXith3DEnvironment

public final Xith3DEnvironment getXith3DEnvironment()
Returns:
the Xith3DEnvironment, which is linked to this RenderLoop.

onRenderLoopStarted

protected void onRenderLoopStarted()
This method is executed by the RenderLoop when the thread has been started.


onRenderLoopStopped

protected void onRenderLoopStopped(long gameTime,
                                   UpdatingThread.TimingMode timingMode,
                                   float averageFPS)
This method is executed by the RenderLoop when the thread has been stopped.

Parameters:
gameTime - the current gameTime
timingMode -
averageFPS - the average FPS over the time the loop was running

destroy

protected void destroy()
This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY or DESTROY_AND_EXIT.

It calls destroy() on any registered RenderEngine and sets any MouseDevice registered to the InputManager to non-exclusive.

Don't invoke this method directly except in a super call. Use end() instead.

See Also:
RenderLoop.StopOperation, setStopOperation(StopOperation), end()

exit

protected void exit()
This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY_AND_EXIT.

Don't invoke this method directly except in a super call. Use end() instead.

See Also:
setStopOperation(StopOperation), end()

destroyAndExit

protected void destroyAndExit()
This method is invoked, when the RenderLoop stopped and the StopOperation is set to DESTROY_AND_EXIT.

Don't invoke this method directly except in a super call. Use end() instead.

See Also:
setStopOperation(StopOperation), end()

end

public void end()

Overrides:
end in class UpdatingThread

onRenderLoopPaused

protected void onRenderLoopPaused(long gameTime,
                                  UpdatingThread.TimingMode timingMode,
                                  int pauseMode)
This event is fired by the RenderLoop when the pauseMode has been increased.

Parameters:
gameTime - the current gameTime
timingMode -
pauseMode - the current pause-mode

onRenderLoopResumed

protected void onRenderLoopResumed(long gameTime,
                                   UpdatingThread.TimingMode timingMode,
                                   int pauseMode)
This event is fired by the RenderLoop when the pauseMode has been released.

Parameters:
gameTime - the current gameTime
timingMode -
pauseMode - the current pause-mode

setMaxFPS

public void setMaxFPS(float maxFPS)
Sets the maximum frames per second.


getMaxFPS

public float getMaxFPS()
Returns:
the maximum frames per second.

getFPS

public float getFPS()
Returns:
the current average frames per second

getTotalAverageFPS

public float getTotalAverageFPS()
Returns:
the average frames per second over the total game-time.

setFPSCalcInterval

public void setFPSCalcInterval(long micros)
Sets the interval in which the FPS are recalculated

Parameters:
micros - the new calculation interval

getFPSCalcInterval

public long getFPSCalcInterval()
Returns:
the interval in which the FPS are recalculated

prepareNextFrame

protected void prepareNextFrame(long gameTime,
                                long frameTime,
                                UpdatingThread.TimingMode timingMode)
This method is called each loop iteration before the renderNextFrame() methiod.

Parameters:
gameTime - the current game time
frameTime - time needed to render the last frame
timingMode -

renderNextFrame

protected void renderNextFrame(long gameTime,
                               long frameTime,
                               UpdatingThread.TimingMode timingMode)
Just calls the render() method on the linked Xith3DEnvironment.

Parameters:
gameTime - the current game time
frameTime - time needed to render one frame
timingMode -

loopIteration

protected void loopIteration(long gameTime,
                             long frameTime,
                             UpdatingThread.TimingMode timingMode)
This method is called each loop iteration. It just updates all registered Keyboard- and MouseDevices and calls invokeRendering(long). Override this method if you want something more to be done each iteration.

Parameters:
gameTime - the current game time
frameTime - time needed to render one frame
timingMode -

onFPSCountIntervalHit

protected void onFPSCountIntervalHit(float fps)
This method is called by the render loop each counting interval

Parameters:
fps - the average frames count during the last interval

update

public void update(long gameTime,
                   long frameTime,
                   UpdatingThread.TimingMode timingMode)
Updates this Updatable object.

Specified by:
update in interface Updatable
Specified by:
update in class UpdatingThread
Parameters:
gameTime - the gameTime in Milliseconds
frameTime - the frameTime in Milliseconds (needed time for the last frame)
timingMode - the TimingMode to use for frameTime.

nextIteration

protected long nextIteration(boolean force)

Overrides:
nextIteration in class UpdatingThread

nextFrame

public long nextFrame()
If the RenderLoop is currently running in RUN_IN_SEPARATE_THREAD_AND_WAIT RunMode the next iteration is allowed and executed asynchronously. -1 is returned as the frame time, because it is not defined at this time.
If the RenderLoop is not running, the next iteration is executed in the calling Thread and the needed (brutto) time for this frame is returned.

In all other cases an IllegalStateException is thrown.

Specified by:
nextFrame in interface RenderLoopController
Returns:
the time needed for this frame

loop

protected void loop()
This method defines the main loop of the Thread.
Override it to change its behavior.

Overrides:
loop in class UpdatingThread

getThread

public java.lang.Thread getThread()

Overrides:
getThread in class UpdatingThread
Returns:
the Thread, that runs this loop.

run

public void run()

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class UpdatingThread

begin

public void begin(RenderLoop.RunMode runMode,
                  UpdatingThread.TimingMode timingMode)
Starts this RenderLoop.

Parameters:
runMode - the RunMode this RenderLoop will run in
timingMode - the TimingMode to use

begin

public final void begin(RenderLoop.RunMode runMode)
Starts this rendering-loop with TimingMode.MICROSECONDS.

Parameters:
runMode - the RunMode this RenderLoop will run in

begin

public final void begin(UpdatingThread.TimingMode timingMode)
Starts this rendering-loop in the same Thread.

Parameters:
timingMode - the TimingMode to use

begin

public final void begin()
Starts this rendering-loop in the same Thread and with TimingMode.MICROSECONDS.


pauseRendering

public void pauseRendering()
pauses rendering in this RenderLoop


resumeRendering

public void resumeRendering()
resumes rendering in this RenderLoop