pulpcore
Class Stage

java.lang.Object
  pulpcore.Stage

All Implemented Interfaces:

Runnable

public class Stage
extends Object
implements Runnable

The Stage class manages Scenes and drawing to the Surface. The Stage class is a singleton that Scenes can access using its static methods.

Stage runs the animation loop. The main class (e.g. CoreApplet) creates, starts, and stops the Stage.

Field Summary

static int	AUTO_CENTER Automatically center the Scene in the Stage.
static int	AUTO_FIT Automatically scale the Scene to the Stage dimensions, preserving the Scene's aspect ratio.
static int	AUTO_OFF Perform no auto scaling (default)
static int	AUTO_STRETCH Automatically stretch the Scene to the Stage dimensions.
static int	DEFAULT_FPS 60 fps, or the screen's refresh rate if it is between 55hz and 65hz.
static int	HIGH_FPS 60 fps
static int	LOW_FPS 15 fps
static int	MAX_FPS No limit to the frame rate (not recommended)
static int	MEDIUM_FPS 30 fps

Constructor Summary

Stage(pulpcore.platform.Surface surface, pulpcore.platform.AppContext appContext)

Method Summary

static boolean	canPopScene() Returns true if the there are Scenes on the scene stack.
void	destroy()
static double	getActualFrameRate() Gets the actual frame rate the Stage is displaying in frames per second.
static Transform	getDefaultTransform()
static int	getFrameRate() Gets the current desired frame rate in frames per second.
static int	getHeight()
static Sprite	getInfoOverlay()
static Scene	getScene() Gets the current active Scene.
static CoreImage	getScreenshot() Gets a screenshot of the current appearance of the stage.
static void	getScreenshot(CoreImage image, int x, int y) Gets a screenshot at the specified location on the screen and copies it to the specified image.
static int	getWidth()
static void	invokeOnShutdown(Runnable runnable) Sets the runnable to execute at application shutdown.
static boolean	isAnimationThread() Returns true if the current thread is the animation thread.
void	pollInput()
static void	popScene() Sets the current scene to the scene at the top of the scene stack.
static void	pushScene(Scene scene) Pushes the current scene onto the scene stack and sets the current scene.
static void	replaceScene(Scene scene) Unloads the current scene and sets the next scene to display.
void	run()
static void	setAutoScale(int naturalWidth, int naturalHeight)
static void	setAutoScale(int naturalWidth, int naturalHeight, int autoScaleType)
static void	setDirtyRectangles(Rect[] dirtyRectangles)
static void	setDirtyRectangles(Rect[] dirtyRectangles, int numDirtyRectangles)
static void	setFrameRate(int desiredFPS) Sets the desired frame rate in frames per second.
static void	setScene(Scene scene) Unloads the current scene, empties the scene stack, and sets the next scene to display.
static void	setUncaughtExceptionScene(Scene scene) Sets the scene to use when an uncaught exception occurs.
void	start()
void	stop()

Methods inherited from class java.lang.Object

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

Field Detail

MAX_FPS

public static final int MAX_FPS

No limit to the frame rate (not recommended)

See Also:

Constant Field Values

HIGH_FPS

public static final int HIGH_FPS

60 fps

See Also:

Constant Field Values

MEDIUM_FPS

public static final int MEDIUM_FPS

30 fps

See Also:

Constant Field Values

LOW_FPS

public static final int LOW_FPS

15 fps

See Also:

Constant Field Values

DEFAULT_FPS

public static final int DEFAULT_FPS

60 fps, or the screen's refresh rate if it is between 55hz and 65hz.

See Also:

Constant Field Values

AUTO_OFF

public static final int AUTO_OFF

Perform no auto scaling (default)

See Also:

Constant Field Values

AUTO_CENTER

public static final int AUTO_CENTER

Automatically center the Scene in the Stage. The Scene is not scaled.

See Also:

Constant Field Values

AUTO_STRETCH

public static final int AUTO_STRETCH

Automatically stretch the Scene to the Stage dimensions.

See Also:

Constant Field Values

AUTO_FIT

public static final int AUTO_FIT

Automatically scale the Scene to the Stage dimensions, preserving the Scene's aspect ratio.

See Also:

Constant Field Values

Constructor Detail

Stage

public Stage(pulpcore.platform.Surface surface,
             pulpcore.platform.AppContext appContext)

Method Detail

getWidth

public static int getWidth()

Returns:

The width of the surface.

getHeight

public static int getHeight()

Returns:

The height of the surface.

getDefaultTransform

public static Transform getDefaultTransform()

Returns:

The transform used to draw onto the surface.

setAutoScale

public static void setAutoScale(int naturalWidth,
                                int naturalHeight)

setAutoScale

public static void setAutoScale(int naturalWidth,
                                int naturalHeight,
                                int autoScaleType)

setFrameRate

public static void setFrameRate(int desiredFPS)

Sets the desired frame rate in frames per second. The Stage will attempt to get as close to the desired frame rate as possible, but the actual frame rate may vary.

To run at the highest frame rate possible (no pauses between frames), invoke setFrameRate(Stage.MAX_FPS). Note, however, running at the highest frame rate possible usually means as many processor cycles are used as possible.

See Also:

getFrameRate(), getActualFrameRate()

getFrameRate

public static int getFrameRate()

Gets the current desired frame rate in frames per second. This is the same value passed in to setFrameRate(int).

See Also:

setFrameRate(int), getActualFrameRate()

getActualFrameRate

public static double getActualFrameRate()

Gets the actual frame rate the Stage is displaying in frames per second. The actual frame rate may vary from the desired frame rate. This method returns -1 if the frame rate has not yet been calculated. The actual frame rate is calculated periodically.

See Also:

setFrameRate(int), getFrameRate()

setDirtyRectangles

public static void setDirtyRectangles(Rect[] dirtyRectangles)

setDirtyRectangles

public static void setDirtyRectangles(Rect[] dirtyRectangles,
                                      int numDirtyRectangles)

getScene

public static Scene getScene()

Gets the current active Scene.

canPopScene

public static boolean canPopScene()

Returns true if the there are Scenes on the scene stack.

setScene

public static void setScene(Scene scene)

Unloads the current scene, empties the scene stack, and sets the next scene to display.

Any scenes on the scene stack are unloaded and the scene stack is emptied.

The new scene isn't activated until the next frame. Multiple calls to the setScene(Scene), replaceScene(Scene), pushScene(Scene), and popScene() methods within a single frame will cause the first calls to be ignored - only the last call during a single frame is recognized.

replaceScene

public static void replaceScene(Scene scene)

Unloads the current scene and sets the next scene to display.

The scene stack is left untouched.

The new scene isn't activated until the next frame. Multiple calls to the setScene(Scene), replaceScene(Scene), pushScene(Scene), and popScene() methods within a single frame will cause the first calls to be ignored - only the last call during a single frame is recognized.

pushScene

public static void pushScene(Scene scene)

Pushes the current scene onto the scene stack and sets the current scene. The pushed scene is activated again when popScene() is invoked.

The new scene isn't activated until the next frame. Multiple calls to the setScene(Scene), replaceScene(Scene), pushScene(Scene), and popScene() methods within a single frame will cause the first calls to be ignored - only the last call during a single frame is recognized.

popScene

public static void popScene()

Sets the current scene to the scene at the top of the scene stack. If the scene stack is empty, this method does nothing.

The popped scene isn't activated until the next frame. Multiple calls to the setScene(Scene), replaceScene(Scene), pushScene(Scene), and popScene() methods within a single frame will cause the first calls to be ignored - only the last call during a single frame is recognized.

setUncaughtExceptionScene

public static void setUncaughtExceptionScene(Scene scene)

Sets the scene to use when an uncaught exception occurs. If null, the app "reboots" itself after a short delay. By default, debug builds use a ConsoleScene, and release builds use null.

When an uncaught exception occurs, the talkback field "pulpcore.uncaught-exception" is set to the exception's stack trace.

If the uncaught exception scene itself throws an exception, the app is stopped.

invokeOnShutdown

public static void invokeOnShutdown(Runnable runnable)

Sets the runnable to execute at application shutdown. Single-scene apps can overload the Scene2D.unload() method, but multi-scene apps that require shutdown code to be run (for example, logging off from a server) can use this method for convenience.

The runnable is executed in the animation thread after all scenes are unloaded.

getScreenshot

public static CoreImage getScreenshot()

Gets a screenshot of the current appearance of the stage.

Returns:

a new image that contains the screenshot.

getScreenshot

public static void getScreenshot(CoreImage image,
                                 int x,
                                 int y)

Gets a screenshot at the specified location on the screen and copies it to the specified image.

isAnimationThread

public static boolean isAnimationThread()

Returns true if the current thread is the animation thread.

start

public void start()

stop

public void stop()

destroy

public void destroy()

run

public void run()

Specified by:

run in interface Runnable

pollInput

public void pollInput()

getInfoOverlay

public static Sprite getInfoOverlay()