pulpcore.scene
Class Scene2D

java.lang.Object
  pulpcore.scene.Scene
      pulpcore.scene.Scene2D

Direct Known Subclasses:

LoadingScene

public class Scene2D
extends Scene

The Scene2D class is a Scene that provdes commonly used features like Sprite management, layer management, Timeline management, and dirty rectangle drawing.

Note the updateScene() method cannot be overridden, and subclasses should override the update(int) method instead.

Scene2D and Group are thread-safe, but in general, Sprites and Properties are not thread-safe. For multi-threaded apps (for example, network-enabled apps), use the addEvent(TimelineEvent), addEventAndWait(TimelineEvent), invokeLater(Runnable), or invokeAndWait(Runnable) methods to make sure Sprites and Properties are modified on the animation thread. For example:

    // Called from the network thread.
    public void receiveNetworkMessage(String message) {
        // It is safe to add and remove sprites. 
        scene.add(myLabel);

        // Modify Sprites and properties in the animation thread.
        scene.invokeLater(new Runnable() {
            public void run() {
                myLabel.setText(message);
                myLabel.visible.set(true);
            }
        });
    }
    

Constructor Summary

Scene2D()
Creates a new Scene2D with one layer and with dirty rectangles enabled.

Method Summary

void	add(Sprite sprite) Adds a sprite to the main (bottom) layer.
void	addEvent(TimelineEvent event) Adds a TimelineEvent to this Scene2D.
void	addEventAndWait(TimelineEvent event) Adds a TimelineEvent to this Scene2D and returns after the TimelineEvent executes or when this Scene2D is unloaded (whichever comes first).
void	addLayer(Group layer) Adds the specified Group as the top-most layer.
void	addTimeline(Timeline timeline) Adds a Timeline to this Scene2D.
void	drawScene(CoreGraphics g) Draws all of the sprites in this scene.
int	getCursor() Gets the cursor for this Scene.
Group	getMainLayer() Returns the main (bottom) layer.
int	getMaxElapsedTime() Gets the maximum elapsed time used to update this Scene2D.
int	getNumSprites() Returns the total number of sprites in all layers.
int	getNumTimelines() Gets the number of currently animating timelines.
int	getNumVisibleSprites() Returns the total number of visible sprites in all layers.
void	hideNotify() Notifies that this scene has been hidden by another Scene or immediately before a call to stop().
void	invokeAndWait(Runnable runnable) Causes a runnable to have it's run() method called in the animation thread, and returns after the Runnable executes or when this Scene2D is unloaded (whichever comes first).
void	invokeLater(Runnable runnable) Causes a runnable to have it's run() method called in the animation thread.
boolean	isDirtyRectanglesEnabled() Checks the dirty rectangles are enabled for this Scene2D.
boolean	isPaused() Gets the paused state of this Scene2D.
void	redrawNotify() Notifies that this scene that the Stage or the OS has requested a full redraw.
void	remove(Sprite sprite) Removes a sprite from the main (bottom) layer.
void	removeAllTimelines(boolean gracefully) Removes all timelines from this Scene2D.
void	removeLayer(Group layer) Removes the specified layer.
void	removeTimeline(Timeline timeline, boolean gracefully) Removes a timeline from this Scene2D.
void	setCursor(int cursor) Sets the default cursor for this Scene.
void	setDirtyRectanglesEnabled(boolean dirtyRectanglesEnabled) Sets the dirty rectangle mode on or off.
void	setMaxElapsedTime(int maxElapsedTime) Sets the maximum elapsed time used to update this Scene2D.
void	setPaused(boolean paused) Sets the paused state of this Scene2D.
void	showNotify() Notifies that this scene has been shown after another Scene is hidden or immediately after a call to start().
void	unload() Forces all invokeAndWait() and addEventAndWait() calls to return, and removes all layers, sprites, and timelines.
void	update(int elapsedTime) Allows subclasses to check for input, change scenes, etc.
void	updateScene(int elapsedTime) Updates the scene.

Methods inherited from class pulpcore.scene.Scene

load, reload

Methods inherited from class java.lang.Object

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

Constructor Detail

Scene2D

public Scene2D()

Creates a new Scene2D with one layer and with dirty rectangles enabled.

Method Detail

setPaused

public void setPaused(boolean paused)

Sets the paused state of this Scene2D. A paused Scene2D does not update sprites or timelines, but update() is called as usual. By default, a Scene2D is not paused.

isPaused

public boolean isPaused()

Gets the paused state of this Scene2D.

Returns:

true if this Scene2D is paused.

See Also:

setPaused(boolean)

setCursor

public final void setCursor(int cursor)

Sets the default cursor for this Scene. By default, a Scene2D uses the default cursor.

See Also:

Input, getCursor()

getCursor

public final int getCursor()

Gets the cursor for this Scene.

See Also:

Input, setCursor(int)

setDirtyRectanglesEnabled

public final void setDirtyRectanglesEnabled(boolean dirtyRectanglesEnabled)

Sets the dirty rectangle mode on or off. By default, a Scene2D has dirty rectangles enabled, but some apps may have better performance with dirty rectangles disabled.

isDirtyRectanglesEnabled

public final boolean isDirtyRectanglesEnabled()

Checks the dirty rectangles are enabled for this Scene2D.

Returns:

true if dirty rectangles are enabled.

See Also:

setDirtyRectanglesEnabled(boolean)

setMaxElapsedTime

public void setMaxElapsedTime(int maxElapsedTime)

Sets the maximum elapsed time used to update this Scene2D. If this value is zero, no maximum elapsed time is enforced: the elapsed time always follows system time (while the Scene2D is active.)

If the maximum elapsed time is greater than zero, long pauses between updates (caused by other processes or the garbage collector) effectively slow down the animations rather than create a visible skip in time.

By default, the maximum elapsed time is 100.

getMaxElapsedTime

public int getMaxElapsedTime()

Gets the maximum elapsed time used to update this Scene2D.

See Also:

setMaxElapsedTime(int)

addTimeline

public void addTimeline(Timeline timeline)

Adds a Timeline to this Scene2D. The Timeline is automatically updated in the updateScene() method. The Timeline is removed when is is finished animating.

This method is safe to call from any thread.

removeTimeline

public void removeTimeline(Timeline timeline,
                           boolean gracefully)

Removes a timeline from this Scene2D.

Parameters:

gracefully - if true and the timeline is not looping, the timeline is fast-forwarded to its end before it is removed.

removeAllTimelines

public void removeAllTimelines(boolean gracefully)

Removes all timelines from this Scene2D.

Parameters:

gracefully - if true, all non-looping timelines are fastforwarded to their end before they are removed.

getNumTimelines

public int getNumTimelines()

Gets the number of currently animating timelines.

addEvent

public void addEvent(TimelineEvent event)

Adds a TimelineEvent to this Scene2D. The TimelineEvent is automatically triggered in the updateScene() method. The TimelineEvent is removed after triggering.

This method is safe to call from any thread.

addEventAndWait

public void addEventAndWait(TimelineEvent event)

Adds a TimelineEvent to this Scene2D and returns after the TimelineEvent executes or when this Scene2D is unloaded (whichever comes first).

Throws:

Error - if the current thread is the animation thread.

invokeLater

public void invokeLater(Runnable runnable)

Causes a runnable to have it's run() method called in the animation thread. This method is equivalent to:

        addEvent(new TimelineEvent(0) {
            public void run() {
                runnable.run();
            }
        });
        

This method is safe to call from any thread.

invokeAndWait

public void invokeAndWait(Runnable runnable)

Causes a runnable to have it's run() method called in the animation thread, and returns after the Runnable executes or when this Scene2D is unloaded (whichever comes first). This method is equivalent to:

        addEventAndWait(new TimelineEvent(0) {
            public void run() {
                runnable.run();
            }
        });
        

Throws:

Error - if the current thread is the animation thread.

getMainLayer

public Group getMainLayer()

Returns the main (bottom) layer. This layer cannot be removed.

addLayer

public void addLayer(Group layer)

Adds the specified Group as the top-most layer.

removeLayer

public void removeLayer(Group layer)

Removes the specified layer. If the specified layer is the main layer, this method does nothing.

getNumSprites

public int getNumSprites()

Returns the total number of sprites in all layers.

getNumVisibleSprites

public int getNumVisibleSprites()

Returns the total number of visible sprites in all layers.

add

public void add(Sprite sprite)

Adds a sprite to the main (bottom) layer.

remove

public void remove(Sprite sprite)

Removes a sprite from the main (bottom) layer.

unload

public void unload()

Forces all invokeAndWait() and addEventAndWait() calls to return, and removes all layers, sprites, and timelines.

Overrides:

unload in class Scene

showNotify

public void showNotify()

Notifies that this scene has been shown after another Scene is hidden or immediately after a call to start().

Subclasses that override this method should call super.showNotify();.

Overrides:

showNotify in class Scene

hideNotify

public void hideNotify()

Notifies that this scene has been hidden by another Scene or immediately before a call to stop().

Subclasses that override this method should call super.hideNotify();.

Overrides:

hideNotify in class Scene

redrawNotify

public final void redrawNotify()

Description copied from class: Scene

Notifies that this scene that the Stage or the OS has requested a full redraw. By default, this method does nothing.

Overrides:

redrawNotify in class Scene

updateScene

public final void updateScene(int elapsedTime)

Description copied from class: Scene

Updates the scene. This method is periodically called by the Stage while this Scene is active. A scene will typically update sprites and handle input.

When a Scene is first shown (after a call to showNotify), the elapsedTime is zero.

The Stage starts a synchronized block on this Scene before calling this method and ends the block after Scene.drawScene(CoreGraphics) returns.

Specified by:

updateScene in class Scene

Parameters:

elapsedTime - time, in milliseconds, since the last call to updateScene().

update

public void update(int elapsedTime)

Allows subclasses to check for input, change scenes, etc. By default, this method does nothing.

drawScene

public void drawScene(CoreGraphics g)

Draws all of the sprites in this scene. Most apps will not override this method.

Specified by:

drawScene in class Scene

Parameters:

g - the CoreGraphics object to draw to. The CoreGraphics clip is set to the entire display area.