com.jme3.cinematic

Class Cinematic

java.lang.Object

com.jme3.cinematic.events.AbstractCinematicEvent

com.jme3.cinematic.Cinematic

All Implemented Interfaces:

AppState, CinematicEvent, Savable

public class Cinematic
extends AbstractCinematicEvent
implements AppState

An appstate for composing and playing cutscenes in a game. The cinematic schedules CinematicEvents over a timeline. Once the Cinematic created it has to be attached to the stateManager. You can add various CinematicEvents to a Cinematic, see package com.jme3.cinematic.events Two main methods can be used to add an event :

See Also:

, that adds an event at the given time form the cinematic start., that enqueue events one after the other according to their initialDuration A Cinematic has convenient methods to manage playback:, AbstractCinematicEvent.play(), AbstractCinematicEvent.pause(), A Cinematic is itself a CinematicEvent, meaning you can embed several cinematics. Embedded cinematics must not be added to the stateManager though. Cinematic can handle several points of view by creating camera nodes and activating them on schedule., bindCamera(java.lang.String, com.jme3.renderer.Camera), activateCamera(float, java.lang.String), setActiveCamera(java.lang.String)

Field Summary

Fields

Modifier and Type	Field and Description
protected TimeLine	timeLine

Fields inherited from class com.jme3.cinematic.events.AbstractCinematicEvent

initialDuration, listeners, loopMode, playState, resuming, speed, time

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Cinematic() Used for serialization creates a cinematic, don't use this constructor directly
	Cinematic(float initialDuration)
	Cinematic(float initialDuration, LoopMode loopMode)
	Cinematic(LoopMode loopMode)
	Cinematic(Node scene) creates a cinematic
	Cinematic(Node scene, float initialDuration) creates a cinematic
	Cinematic(Node scene, float initialDuration, LoopMode loopMode) creates a cinematic
	Cinematic(Node scene, LoopMode loopMode) creates a cinematic

Method Summary

Modifier and Type	Method and Description
void	activateCamera(float timeStamp, java.lang.String cameraName) schedule an event that will activate the camera at the given time
KeyFrame	addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent) Adds a cinematic event to this cinematic at the given timestamp.
CameraNode	bindCamera(java.lang.String cameraName, Camera cam) Binds a camera to this Cinematic, tagged by a unique name.
void	cleanup() called internally
void	clear() Remove all events from the Cinematic.
void	dispose() used internally to clean up the cinematic.
float	enqueueCinematicEvent(CinematicEvent cinematicEvent) Enqueue a cinematic event to a Cinematic.
void	fitDuration() fits the duration of the cinematic to the duration of all its child cinematic events
CameraNode	getCamera(java.lang.String cameraName) returns a cameraNode given its name
java.lang.Object	getEventData(java.lang.String type, java.lang.Object key) used internally return and event data
java.lang.String	getId() Returns the unique ID for this AppState or null if it has no unique ID.
Node	getScene() return the scene where the cinematic occur
void	initialize(AppStateManager stateManager, Application app) used internally
boolean	isEnabled() return true if the cinematic appstate is enabled (the cinematic is playing)
boolean	isInitialized() used internally
void	onPause() called internally
void	onPlay() called internally
void	onStop() called internally
void	onUpdate(float tpf) used internally, don't call this directly.
void	postRender() called internally
void	putEventData(java.lang.String type, java.lang.Object key, java.lang.Object object) used internally put an eventdata in the cinematic
void	read(JmeImporter im) used internally for serialization
boolean	removeCinematicEvent(CinematicEvent cinematicEvent) removes the first occurrence found of the given cinematicEvent.
boolean	removeCinematicEvent(float timeStamp, CinematicEvent cinematicEvent) removes the first occurrence found of the given cinematicEvent for the given time stamp.
boolean	removeCinematicEvent(KeyFrame keyFrame, CinematicEvent cinematicEvent) removes the first occurrence found of the given cinematicEvent for the given keyFrame
void	removeEventData(java.lang.String type, java.lang.Object key) Used internally remove an eventData
void	render(RenderManager rm) called internally
void	setActiveCamera(java.lang.String cameraName) Sets the active camera instantly (use activateCamera if you want to schedule that event)
void	setEnabled(boolean enabled) passing true has the same effect as play() you should use play(), pause(), stop() to handle the cinematic playing state.
protected void	setId(java.lang.String id) Sets the unique ID of this app state.
void	setScene(Node scene) sets the scene to use for this cinematic it is expected that the scene is added before adding events to the cinematic
void	setSpeed(float speed) sets the speed of the cinematic.
void	setTime(float time) This is used internally but can be called to shuffle through the cinematic.
void	stateAttached(AppStateManager stateManager) called internally
void	stateDetached(AppStateManager stateManager) called internally
void	update(float tpf) called internally don't call it directly.
void	write(JmeExporter ex) used internally for serialization

Methods inherited from class com.jme3.cinematic.events.AbstractCinematicEvent

addListener, forceStop, getDuration, getInitialDuration, getLoopMode, getPlayState, getSpeed, getTime, initEvent, internalUpdate, pause, play, removeListener, setInitialDuration, setLoopMode, stop

Methods inherited from class java.lang.Object

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

Field Detail

timeLine

protected TimeLine timeLine

Constructor Detail

Cinematic

protected Cinematic()

Used for serialization creates a cinematic, don't use this constructor directly

Cinematic

public Cinematic(float initialDuration)

Cinematic

public Cinematic(LoopMode loopMode)

Cinematic

public Cinematic(float initialDuration,
                 LoopMode loopMode)

Cinematic

public Cinematic(Node scene)

creates a cinematic

Parameters:

scene - the scene in which the cinematic should take place

Cinematic

public Cinematic(Node scene,
                 float initialDuration)

creates a cinematic

Parameters:

scene - the scene in which the cinematic should take place

initialDuration - the duration of the cinematic (without considering the speed)

Cinematic

public Cinematic(Node scene,
                 LoopMode loopMode)

creates a cinematic

Parameters:

scene - the scene in which the cinematic should take place

loopMode - tells if this cinematic should be looped or not

Cinematic

public Cinematic(Node scene,
                 float initialDuration,
                 LoopMode loopMode)

creates a cinematic

Parameters:

scene - the scene in which the cinematic should take place

initialDuration - the duration of the cinematic (without considering the speed)

loopMode - tells if this cinematic should be looped or not

Method Detail

onPlay

public void onPlay()

called internally

Specified by:

onPlay in class AbstractCinematicEvent

onStop

public void onStop()

called internally

Specified by:

onStop in class AbstractCinematicEvent

onPause

public void onPause()

called internally

Specified by:

onPause in class AbstractCinematicEvent

write

public void write(JmeExporter ex)
           throws java.io.IOException

used internally for serialization

Specified by:

write in interface Savable

Overrides:

write in class AbstractCinematicEvent

Parameters:

ex - the exporter (not null)

Throws:

java.io.IOException - from the exporter

read

public void read(JmeImporter im)
          throws java.io.IOException

used internally for serialization

Specified by:

read in interface Savable

Overrides:

read in class AbstractCinematicEvent

Parameters:

im - the importer (not null)

Throws:

java.io.IOException - from the importer

setSpeed

public void setSpeed(float speed)

sets the speed of the cinematic. Note that it will set the speed of all events in the cinematic. 1 is normal speed. use 0.5f to make the cinematic twice slower, use 2 to make it twice faster

Specified by:

setSpeed in interface CinematicEvent

Overrides:

setSpeed in class AbstractCinematicEvent

Parameters:

speed - the speed

initialize

public void initialize(AppStateManager stateManager,
                       Application app)

used internally

Specified by:

initialize in interface AppState

Parameters:

stateManager - the state manager

app - the application

isInitialized

public boolean isInitialized()

used internally

Specified by:

isInitialized in interface AppState

Returns:

true if initialized, otherwise false

setId

protected void setId(java.lang.String id)

Sets the unique ID of this app state. Note: that setting this while an app state is attached to the state manager will have no effect on ID-based lookups.

Parameters:

id - the desired ID

getId

public java.lang.String getId()

Description copied from interface: AppState

Returns the unique ID for this AppState or null if it has no unique ID.

Specified by:

getId in interface AppState

Returns:

the ID, or null if none

setEnabled

public void setEnabled(boolean enabled)

passing true has the same effect as play() you should use play(), pause(), stop() to handle the cinematic playing state.

Specified by:

setEnabled in interface AppState

Parameters:

enabled - true or false

isEnabled

public boolean isEnabled()

return true if the cinematic appstate is enabled (the cinematic is playing)

Specified by:

isEnabled in interface AppState

Returns:

true if enabled

See Also:

AppState.setEnabled(boolean)

stateAttached

public void stateAttached(AppStateManager stateManager)

called internally

Specified by:

stateAttached in interface AppState

Parameters:

stateManager - the state manager

stateDetached

public void stateDetached(AppStateManager stateManager)

called internally

Specified by:

stateDetached in interface AppState

Parameters:

stateManager - the state manager

update

public void update(float tpf)

called internally don't call it directly.

Specified by:

update in interface AppState

Parameters:

tpf - time per frame (in seconds)

onUpdate

public void onUpdate(float tpf)

used internally, don't call this directly.

Specified by:

onUpdate in class AbstractCinematicEvent

Parameters:

tpf - time per frame (in seconds)

setTime

public void setTime(float time)

This is used internally but can be called to shuffle through the cinematic.

Specified by:

setTime in interface CinematicEvent

Overrides:

setTime in class AbstractCinematicEvent

Parameters:

time - the time to shuffle to.

addCinematicEvent

public KeyFrame addCinematicEvent(float timeStamp,
                                  CinematicEvent cinematicEvent)

Adds a cinematic event to this cinematic at the given timestamp. This operation returns a keyFrame

Parameters:

timeStamp - the time when the event will start after the beginning of the cinematic

cinematicEvent - the cinematic event

Returns:

the keyFrame for that event.

enqueueCinematicEvent

public float enqueueCinematicEvent(CinematicEvent cinematicEvent)

Enqueue a cinematic event to a Cinematic. This is handy when you want to chain events without knowing their durations.

Parameters:

cinematicEvent - the cinematic event to enqueue

Returns:

the timestamp the event was scheduled.

removeCinematicEvent

public boolean removeCinematicEvent(CinematicEvent cinematicEvent)

removes the first occurrence found of the given cinematicEvent.

Parameters:

cinematicEvent - the cinematicEvent to remove

Returns:

true if the element has been removed

removeCinematicEvent

public boolean removeCinematicEvent(float timeStamp,
                                    CinematicEvent cinematicEvent)

removes the first occurrence found of the given cinematicEvent for the given time stamp.

Parameters:

timeStamp - the timestamp when the cinematicEvent has been added

cinematicEvent - the cinematicEvent to remove

Returns:

true if the element has been removed

removeCinematicEvent

public boolean removeCinematicEvent(KeyFrame keyFrame,
                                    CinematicEvent cinematicEvent)

removes the first occurrence found of the given cinematicEvent for the given keyFrame

Parameters:

keyFrame - the keyFrame returned by the addCinematicEvent method.

cinematicEvent - the cinematicEvent to remove

Returns:

true if the element has been removed

render

public void render(RenderManager rm)

called internally

Specified by:

render in interface AppState

Parameters:

rm - RenderManager

See Also:

AppState.render(com.jme3.renderer.RenderManager)

postRender

public void postRender()

called internally

Specified by:

postRender in interface AppState

See Also:

AppState.postRender()

cleanup

public void cleanup()

called internally

Specified by:

cleanup in interface AppState

See Also:

AppState.cleanup()

fitDuration

public void fitDuration()

fits the duration of the cinematic to the duration of all its child cinematic events

bindCamera

public CameraNode bindCamera(java.lang.String cameraName,
                             Camera cam)

Binds a camera to this Cinematic, tagged by a unique name. This method creates and returns a CameraNode for the cam and attaches it to the scene. The control direction is set to SpatialToCamera. This camera Node can then be used in other events to handle the camera movements during playback.

Parameters:

cameraName - the unique tag the camera should have

cam - the scene camera.

Returns:

the created CameraNode.

getCamera

public CameraNode getCamera(java.lang.String cameraName)

returns a cameraNode given its name

Parameters:

cameraName - the camera name (as registered in Cinematic#bindCamera())

Returns:

the cameraNode for this name

setActiveCamera

public void setActiveCamera(java.lang.String cameraName)

Sets the active camera instantly (use activateCamera if you want to schedule that event)

Parameters:

cameraName - the camera name (as registered in Cinematic#bindCamera())

activateCamera

public void activateCamera(float timeStamp,
                           java.lang.String cameraName)

schedule an event that will activate the camera at the given time

Parameters:

timeStamp - the time to activate the cam

cameraName - the camera name (as registered in Cinematic#bindCamera())

putEventData

public void putEventData(java.lang.String type,
                         java.lang.Object key,
                         java.lang.Object object)

used internally put an eventdata in the cinematic

Parameters:

type - the type of data

key - the key

object - the data

getEventData

public java.lang.Object getEventData(java.lang.String type,
                                     java.lang.Object key)

used internally return and event data

Parameters:

type - the type of data

key - the key

Returns:

the pre-existing object, or null

removeEventData

public void removeEventData(java.lang.String type,
                            java.lang.Object key)

Used internally remove an eventData

Parameters:

type - the type of data

key - the key of the data

setScene

public void setScene(Node scene)

sets the scene to use for this cinematic it is expected that the scene is added before adding events to the cinematic

Parameters:

scene - the scene where the cinematic should take place.

getScene

public Node getScene()

return the scene where the cinematic occur

Returns:

the scene

clear

public void clear()

Remove all events from the Cinematic.

dispose

public void dispose()

used internally to clean up the cinematic. Called when the clear() method is called

Specified by:

dispose in interface CinematicEvent

Overrides:

dispose in class AbstractCinematicEvent