com.threerings.media

Class FrameManager

java.lang.Object

com.threerings.media.FrameManager

Direct Known Subclasses:

BackFrameManager, FlipFrameManager

public abstract class FrameManager
extends Object

Provides a central point from which the computation for each "frame" or tick can be dispatched. This assumed that the application structures its activity around the rendering of each frame, which is a common architecture for games. The animation and sprite support provided by other classes in this package are structured for use in an application that uses a frame manager to tick everything once per frame.

The frame manager goes through a simple two part procedure every frame:

• Ticking all of the frame participants: in FrameParticipant.tick(long), any processing that need be performed during this frame should be performed. Care should be taken not to execute code that will take unduly long, instead such processing should be broken up so that it can be performed in small pieces every frame (or performed on a separate thread with the results safely communicated back to the frame participants for incorporation into the rendering loop).
• Painting the user interface hierarchy: the top-level component (the frame) is painted (via a call to JComponent.paint(java.awt.Graphics)) into a flip buffer (if supported, an off-screen buffer if not). Updates that were computed during the tick should be rendered in this call to paint. The paint call will propagate down to all components in the UI hierarchy, some of which may be FrameParticipants and will have prepared themselves for their upcoming painting in the previous call to FrameParticipant.tick(long). When the call to paint completes, the flip buffer is flipped and the process starts all over again.

The ticking and rendering takes place on the AWT thread so as to avoid the need for complicated coordination between AWT event handler code and frame code. However, this means that all AWT (and Swing) event handlers must not perform any complicated processing. After each frame, control of the AWT thread is given back to the AWT which processes all pending AWT events before giving the frame manager an opportunity to process the next frame. Thus the convenience of everything running on the AWT thread comes with the price of requiring that AWT event handlers not block or perform any intensive processing. In general, this is a sensible structure for an application anyhow, so this organization tends to be preferable to an organization where the AWT and frame threads are separate and must tread lightly so as not to collide.

Note: the way that JScrollPane goes about improving performance when scrolling complicated contents cannot work with active rendering. If you use a JScrollPane in an application that uses the frame manager, you should either use the provided SafeScrollPane or set your scroll panes' viewports to SIMPLE_SCROLL_MODE.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	FrameManager.ManagedRoot Provides a bridge between either ManagedJFrame or ManagedJApplet and the frame manager.
static interface	FrameManager.SafeLayerComponent Normally, the frame manager will repaint any component in a JLayeredPane layer (popups, overlays, etc.) that overlaps a frame participant on every tick because the frame participant could have changed underneath the overlay which would require that the overlay be repainted.

Constructor Summary

Constructors

Constructor and Description
FrameManager()

Method Summary

Modifier and Type	Method and Description
void	clearMaxTimerDriftRatio() Clears out the maximum drift our timer remembers seeing.
void	clearMediaOverlay() Clears out any media overlay that is in use.
static MediaTimer	createTimer() Attempts to create a high resolution timer, but if that isn't possible, uses a System.currentTimeMillis based timer.
FrameManager.ManagedRoot	getManagedRoot() Returns the managed root on which this frame manager is operating.
float	getMaxTimerDriftRatio() Returns the highest drift ratio our timer has seen.
MediaOverlay	getMediaOverlay() Returns an overlay that can be used to render sprites and animations on top of the entire frame.
TrailingAverage[]	getPerfMetrics() Returns debug performance metrics.
int	getPerfTicks() Returns the number of ticks executed in the last second.
int	getPerfTries() Returns the number of ticks requested in the last second.
static Component	getRoot(Component comp, Rectangle rect) Returns the root component for the supplied component or null if it is not part of a rooted hierarchy or if any parent along the way is found to be hidden or without a peer.
long	getTimeStamp() Returns a millisecond granularity time stamp using the MediaTimer with which this frame manager was configured.
boolean	isRegisteredFrameParticipant(FrameParticipant participant) Returns true if the specified participant is registered.
boolean	isRunning() Returns true if the tick interval is be running (not necessarily at that instant, but in general).
static FrameManager	newInstance(FrameManager.ManagedRoot root) Creates a frame manager that will try to use a high resolution timer for timing but will fall back to MillisTimer, which is available on every platform, but returns inaccurate time stamps on many platforms.
static FrameManager	newInstance(FrameManager.ManagedRoot root, MediaTimer timer) Constructs a frame manager that will do its rendering to the supplied root and use the supplied media timer for timing information.
void	registerFrameParticipant(FrameParticipant participant) Registers a frame participant.
void	removeFrameParticipant(FrameParticipant participant) Removes a frame participant.
void	setTargetFrameRate(int fps) Instructs the frame manager to target the specified number of frames per second.
void	start() Starts up the per-frame tick
void	stop() Stops the per-frame tick.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FrameManager

public FrameManager()

Method Detail

newInstance

public static FrameManager newInstance(FrameManager.ManagedRoot root)

Creates a frame manager that will try to use a high resolution timer for timing but will fall back to MillisTimer, which is available on every platform, but returns inaccurate time stamps on many platforms.

See Also:

newInstance(ManagedRoot, MediaTimer)

createTimer

public static MediaTimer createTimer()

Attempts to create a high resolution timer, but if that isn't possible, uses a System.currentTimeMillis based timer.

newInstance

public static FrameManager newInstance(FrameManager.ManagedRoot root,
                                       MediaTimer timer)

Constructs a frame manager that will do its rendering to the supplied root and use the supplied media timer for timing information.

setTargetFrameRate

public void setTargetFrameRate(int fps)

Instructs the frame manager to target the specified number of frames per second. If the computation and rendering for a frame are completed with time to spare, the frame manager will wait until the proper time to begin processing for the next frame. If a frame takes longer than its allotted time, the frame manager will immediately begin processing on the next frame.

registerFrameParticipant

public void registerFrameParticipant(FrameParticipant participant)

Registers a frame participant. The participant will be given the opportunity to do processing and rendering on each frame.

isRegisteredFrameParticipant

public boolean isRegisteredFrameParticipant(FrameParticipant participant)

Returns true if the specified participant is registered.

removeFrameParticipant

public void removeFrameParticipant(FrameParticipant participant)

Removes a frame participant.

getTimeStamp

public long getTimeStamp()

Returns a millisecond granularity time stamp using the MediaTimer with which this frame manager was configured. Note: this should only be called from the AWT thread.

getMaxTimerDriftRatio

public float getMaxTimerDriftRatio()

Returns the highest drift ratio our timer has seen. 1.0 means no drift (and is what we return if we're not using a CalibratingTimer)

clearMaxTimerDriftRatio

public void clearMaxTimerDriftRatio()

Clears out the maximum drift our timer remembers seeing.

getMediaOverlay

public MediaOverlay getMediaOverlay()

Returns an overlay that can be used to render sprites and animations on top of the entire frame. This is lazily created the first time this method is called and the overlay will remain a frame participant until clearMediaOverlay() is called. Be sure to coordinate access to the overlay in your application as there is only one overlay in existence at any time, and attempts to use an overlay after it has been cleared will fail.

getManagedRoot

public FrameManager.ManagedRoot getManagedRoot()

Returns the managed root on which this frame manager is operating.

clearMediaOverlay

public void clearMediaOverlay()

Clears out any media overlay that is in use.

start

public void start()

Starts up the per-frame tick

stop

public void stop()

Stops the per-frame tick.

isRunning

public boolean isRunning()

Returns true if the tick interval is be running (not necessarily at that instant, but in general).

getPerfTicks

public int getPerfTicks()

Returns the number of ticks executed in the last second.

getPerfTries

public int getPerfTries()

Returns the number of ticks requested in the last second.

getPerfMetrics

public TrailingAverage[] getPerfMetrics()

Returns debug performance metrics.

getRoot

public static Component getRoot(Component comp,
                                Rectangle rect)

Returns the root component for the supplied component or null if it is not part of a rooted hierarchy or if any parent along the way is found to be hidden or without a peer. Along the way, it adjusts the supplied component-relative rectangle to be relative to the returned root component.