A scene contains, handles and tracks a group of actors. More...

#include <CzScene.h>

Inheritance diagram for CzScene:

Public Types
enum	eCanvasFit { Fit_None, Fit_Width, Fit_Height, Fit_Both, Fit_Best }
	Values that define how the virtual canvas is fit to the devices screen. More...
enum	eCanvasOrigin { Origin_Centre, Origin_Top, Origin_Left, Origin_TopLeft }
	Values that define the placement of teh canvas origin. More...
enum	eOrientation { Orientation_Landscape, Orientation_Portrait }
	Values that define the orientation of the screen. More...
enum	eDocking { Dock_None, Dock_Top, Dock_Bottom, Dock_Left, Dock_Right, Dock_TopLeft, Dock_TopRight, Dock_BottomLeft, Dock_BottomRight }
	Values that define acor docking. More...
typedef CzList< CzActor * > ::iterator	_Iterator
Public Member Functions
_Iterator	begin ()
_Iterator	end ()
void	setParent (CzApp *parent)
CzApp *	getParent ()
CzSpriteManager *	getSpriteManager ()
CzXomlResourceManager *	getResourceManager ()
CzActionsManager *	getActionsManager ()
CzAnimTimelinesManager *	getTimelinesManager ()
CzTimersManager *	getTimersManager ()
CzXomlVariableManager *	getVariableManager ()
CzProgramManager *	getProgramManager ()
IzScriptEngine *	getScriptEngine ()
void	setScriptEngine (const CzString &type)
	Sets the scenes script engine type.
void	setType (int type)
int	getType () const
CzIVec2	getScreenSize () const
eOrientation	getOrientation () const
CzIVec2	getVirtualSize () const
void	setVirtualTransform (int required_width, int required_height, float angle, bool fix_aspect=false, bool lock_width=false, eCanvasOrigin canvas_origin=Origin_Centre)
	Sets virtual transform.
void	setVirtualTransform (int required_width, int required_height, float angle, eCanvasFit fit=Fit_Best, eCanvasOrigin canvas_origin=Origin_Centre)
	Sets the scenes virtual transform.
CzMatrix3 &	getVirtualTransform ()
CzMatrix3 &	getTransform ()
void	setCanvasFit (eCanvasFit fit)
eCanvasFit	getCanvasFit () const
eCanvasOrigin	getCanvasOrigin () const
void	setCanvasOrigin (eCanvasOrigin org)
CzList< CzActor * > &	getActors ()
void	addActor (CzActor *actor)
	Adds an actor to the scene.
void	removeActorNoDelete (CzActor *actor)
	Removes the actor from the scene without cleaning it up.
void	removeActor (CzActor *actor, bool instant_delete=false)
	Removes the actor from the scene.
void	removeActor (unsigned int name_hash, bool instant_delete=false)
	Removes the actor from the scene.
void	removeActors (unsigned int tag_hash)
	Removes all actors that belong to the spcified group.
void	fixActors (CzActor *parent)
void	removeLinkedActors (CzActor *actor, bool instant_delete=false)
	Removes all actors that link to the specified actor.
bool	findActorInRemovals (CzActor *actor)
	Searches for the actor in the actor removals list.
int	checkActorState (CzActor *actor)
	Checks the actors current state.
CzActor *	findActor (const char *name)
	Searches for the named actor.
CzActor *	findActor (unsigned int name_hash)
	Searches for the named actor.
CzActor *	findActor (int type)
	Searches for the first actor of the specified type.
int	findActors (unsigned int tag_hash, CzVector< CzActor * > &actors)
	Searches for a group of actors that have a specific group tag name.
int	findActorsOfType (int type, CzVector< CzActor * > &actors)
	Searches for a group of actors that have a specific group tag name.
CzActor *	findClosestActor (int x, int y, int type)
	Searches for the actor of the specific type that is nearest to the specified point.
CzActor *	findFurthestActor (int x, int y, int type)
	Searches for the actor of the specific type that is furthest from the specified point.
void	clearActors (bool ignore_visuals=false)
	Clears and destroys all actors in the scene.
void	setExtents (int x, int y, int w, int h)
CzIRect	getExtents () const
void	setCamera (CzCamera *camera)
	Sets the scenes current camera.
CzCamera *	getCamera ()
bool	addCollideable (CzActor *actor)
	Adds n actor to the a collideables list.
CzActor **	getCollidables ()
int	getTotalCollidables () const
void	setAllowSuspend (bool allow_suspend)
bool	getAllowSuspend () const
void	setClippingArea (int x, int y, int w, int h)
CzIRect	getClippingArea ()
void	setClipStatic (bool is_static)
bool	isClipStatic () const
void	setActive (bool active)
bool	isActive () const
void	setVisible (bool visible)
bool	isVisible () const
void	setColour (const CzColour &colour)
void	setColour (uint8 r, uint8 g, uint8 b, uint8 a)
void	setOpacity (int opacity)
int	getOpacity () const
CzColour	getColour () const
void	setTimeline (CzAnimTimeline *timeline)
CzAnimTimeline *	getTimeline ()
void	setBindings (CzXomlBindings *bindings)
CzXomlBindings *	getBindings ()
void	setRunCount (int count)
int	getRunCount () const
void	setDestroyed (bool destroyed)
bool	isDestroyed () const
void	setAllowFocus (bool allow)
bool	getAllowFocus () const
void	setLayer (int layer)
int	getLayer () const
bool	isDragging () const
void	setConstantTimeStep (float step)
float	getConstantTimeStep () const
CzBox2dWorld *	getBox2dWorld ()
void	setUserPropertyList (CzUserPropertyList *props)
CzUserPropertyList *	getUserPropertyList ()
CzEventManager *	getEventsManager ()
void	setModifiers (CzModifierManager *mods)
CzModifierManager *	getModifiers ()
bool	setProperty (const char *property_name, const CzString &data, bool delta)
	Sets the named property of the scene.
virtual bool	setProperty (unsigned int property_name, const CzString &data, bool delta)
	Sets the named property of the scene.
virtual bool	setProperty (unsigned int property_name, const CzXomlProperty &data, bool delta)
	Sets the named property of the scene.
bool	getProperty (const char *property_name, CzXomlProperty &prop)
	Gets the named property of the scene.
virtual bool	getProperty (unsigned int property_name, CzXomlProperty &prop)
void	setBatching (bool enabled)
bool	isBatching () const
int	getMaxLayers () const
bool	getTickEnabled () const
CzIVec2	getOriginalSize () const
void	setPhysicsEnabled (bool enable)
bool	isPhysicsEnabled () const
	CzScene ()
virtual	~CzScene ()
	CzScene destructor.
virtual int	Init (int max_collidables=128, int max_layers=10, bool doSleep=true)
	Initialises this scene.
void	UpdatePhysics (float dt)
	Updates the physics world.
virtual void	Update (float dt)
	Updates the scene.
virtual void	Draw ()
	Draws this scene.
virtual void	PreDestroy ()
CzVec2	ScreenToVirtual (float screen_x, float screen_y, bool ignore_translation=false)
	Returns a virtual position from a screen position.
CzVec2	VirtualToScreen (float virtual_x, float virtual_y, bool ignore_translation=false)
	Returns a screen position frmo a virtual position.
CzVec2	ScreenToCamera (float pos_x, float pos_y, bool ignore_translation=false)
	Returns a virtual position from a position taking into account camera position.
void	ProcessEventActions (unsigned int event_name)
	Process the event actions described by event_name.
virtual void	NotifyPan ()
	This event is called when this scene is panned.
virtual void	NotifyCreate ()
	This event is called when this scene is being created.
virtual void	NotifyDestroy ()
	This event is called when this scene is being destroyed.
virtual void	NotifySuspending (CzScene *new_scene)
	This event is called when this scene is being suspended.
virtual void	NotifyResuming (CzScene *old_scene)
	This event is called when this scene is being resumed.
virtual void	NotifyLostFocus (CzScene *new_scene)
	This event is called when this scene has just lost focus.
virtual void	NotifyGainedFocus (CzScene *old_scene)
	This event is called when this scene has just gained focus.
virtual void	NotifyKeyBack ()
	This event is called when this scene receives a back key press.
virtual void	NotifyKeyMenu ()
	This event is called when this scene receives a menu key press.
virtual void	NotifyOrientationChanged ()
	This event is called when this scene receives an orientatin changed event.
virtual void	NotifySizeChanged ()
	This event is called when this scene receives a size changed event.
virtual void	NotifyDeviceSuspended ()
	This event is called when this scene receives a device suspended event.
virtual void	NotifyDeviceResumed ()
	This event is called when this scene receives a device resumed event.
virtual void	NotifyDeviceVolumeUp ()
	This event is called when this scene receives a device volume up event.
virtual void	NotifyDeviceVolumeDown ()
	This event is called when this scene receives a device volume down event.
virtual void	NotifyDeviceNetworkOnline ()
	This event is called when this scene receives a network online event.
virtual void	NotifyDeviceNetworkOffline ()
	This event is called when this scene receives a network offline event.
void	Suspend (CzScene *new_scene)
	Suspends this scene.
void	Resume (CzScene *old_scene)
	Resumes this scene.
CzActor *	FindTappedActor (int x, int y)
	Searches for the first tapped actor.
void	CleanupRemovedActors ()
	Cleans up removed actors.
void	CheckforInvalidRemovals (const char *check_point)
	Checks the actor removals list for invalid removals.
int	LoadFromXoml (IzXomlResource parent, bool load_children, CzXmlNode node)
	Creates an instance of this class from XOML.
bool	PostLoadFromXoml (IzXomlResource parent, CzXmlNode node)
	Carries out any post XOML loading tasks.
bool	UpdateFromAnimation (CzAnimInstance *animation)
	Updates scene property from supplied animation.
void	RestoreClipping ()
	Restore the scenes clipping rectangle.
Static Public Member Functions
static void	InitClass ()
	Initialises the class.
static void	ReleaseClass ()
static bool	_setName (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getName (IzXomlResource *target)
static bool	_setType (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getType (IzXomlResource *target)
static bool	_setLayer (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getLayer (IzXomlResource *target)
static bool	_setPosition (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPosition (IzXomlResource *target)
static bool	_setPositionX (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPositionX (IzXomlResource *target)
static bool	_setPositionY (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPositionY (IzXomlResource *target)
static bool	_setAngle (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAngle (IzXomlResource *target)
static bool	_setScale (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScale (IzXomlResource *target)
static bool	_setColour (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getColour (IzXomlResource *target)
static bool	_setOpacity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getOpacity (IzXomlResource *target)
static bool	_setTargetX (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setTargetY (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setCanvasSize (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCanvasSize (IzXomlResource *target)
static bool	_setCanvasFit (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCanvasFit (IzXomlResource *target)
static bool	_setCanvasOrigin (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCanvasOrigin (IzXomlResource *target)
static bool	_setExtents (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getExtents (IzXomlResource *target)
static bool	_setAllowSuspend (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAllowSuspend (IzXomlResource *target)
static bool	_setClipping (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getClipping (IzXomlResource *target)
static bool	_setClipStatic (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getClipStatic (IzXomlResource *target)
static bool	_setActive (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getActive (IzXomlResource *target)
static bool	_setVisible (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getVisible (IzXomlResource *target)
static CzXomlProperty	_getLayers (IzXomlResource *target)
static bool	_setCurrent (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCurrent (IzXomlResource *target)
static bool	_setTimeline (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTimeline (IzXomlResource *target)
static bool	_setBindings (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBindings (IzXomlResource *target)
static bool	_setTimeScale (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getTimeScale (IzXomlResource *target)
static bool	_setCamera (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getCamera (IzXomlResource *target)
static bool	_setBatch (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBatch (IzXomlResource *target)
static bool	_setAllowFocus (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAllowFocus (IzXomlResource *target)
static bool	_setOnSuspend (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnResume (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnLostFocus (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnGainedFocus (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnCreate (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDestroy (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnKeyBack (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnKeyMenu (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnOrientationChange (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnTick (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnPan (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceSuspended (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceResumed (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceVolumeUp (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceVolumeDown (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceNetworkOnline (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setOnDeviceNetworkOffline (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setScriptEngine (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getScriptEngine (IzXomlResource *target)
static bool	_setWorldScale (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getWorldScale (IzXomlResource *target)
static bool	_setPhysics (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPhysics (IzXomlResource *target)
static bool	_setGravity (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getGravity (IzXomlResource *target)
static bool	_setPhysicsTimeStep (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getPhysicsTimeStep (IzXomlResource *target)
static CzXomlProperty	_getUserProperties (IzXomlResource *target)
Static Public Attributes
static const char *	DockingNames []
Protected Member Functions
virtual void	UpdateBindings (bool force_modified=false)
	Update data bindings.
void	UpdateActorResizing ()
	Updates the parents of any actors that have resized themselves.
Protected Attributes
CzSpriteManager *	SpriteManager
	Manages sprites for the whole scene.
CzXomlResourceManager *	ResourceManager
	Manages all types of resources.
CzXomlVariableManager *	VariableManager
	Manages XOML variables.
CzActionsManager *	ActionsManager
	Manages actions.
CzAnimTimelinesManager *	TimelinesManager
	Manages timelines.
CzTimersManager *	TimersManager
	Manages attached timers.
CzProgramManager *	ProgramManager
	Manages the execution of a collection of programs.
CzXomlBindings *	Bindings
	Manages any attached bindings.
IzScriptEngine *	ScriptEngine
	Mnaages scene scripts.
CzApp *	Parent
	Parent game controller.
int	Type
	Type of scene.
eOrientation	Orientation
	Current display orientation.
CzIVec2	ScreenSize
	Native screen size.
CzIVec2	VirtualSize
	The virtual size is not the actual size of the scene. but a static pretend size that we can use to render to without having to cater for different sized displays.
CzMatrix3	VirtualTransform
	Virtual transform is used to scale, translate and rotate scene to fit different display sizes and orientations.
CzMatrix3	Transform
	Scene transform.
CzList< CzActor * >	Actors
	Collection of scene actors.
CzIRect	Extents
	Extents of scenes world.
CzCamera *	Camera
	Current camera.
CzActor **	Collidables
	List of collidable objects built this frame.
bool	AllowSuspend
	If true then this processing of this scene will be suspended when the scene manager changes away from this scene.
CzIRect	ClippingArea
	A rectangular area of the virtual screen that this scene will be clipped to.
bool	ClipStatic
	If ClipStatic is true then camera transform is not applied to clipping rect.
bool	IsActive
	Active state of scene.
bool	IsVisible
	Visible state of scene.
bool	AllowFocus
	If true this scene can receive input events if it is not the current scene.
CzColour	Colour
	Colour.
CzAnimTimeline *	Timeline
	Timeline, controls animation of the scene.
int	RunCount
	NUmber of times the scene has been updated.
bool	Destroyed
	A scene is marked asd destroyed when it has been marked for deletion.
int	Layer
	Scenes layer.
bool	PhysicsEnabled
	True if physics is enabled in this scene.
bool	IsDragging
	True if user is draggnig their finger on the scene.
bool	PrevTouching
	True if user is draggnig their finger on the scene.
CzVec2	PrevTouchVel
	Previous touch velocity.
float	ConstantTimeStep
	If 0 then time step will be calculated from frame rate.
CzBox2dWorld *	Box2dWorld
CzUserPropertyList *	UserPropertyList
	User properties list.
CzEventManager *	EventsManager
	List of events that the scene handles.
CzModifierManager *	Modifiers
	Class modifiers manager.
bool	TickEnabled
	true if OnTick event specified
CzIVec2	OriginalSize
	Original size of scene.
eCanvasFit	CanvasFit
	Fit method for scalnig canvas.
eCanvasOrigin	CanvasOrigin
	Origin type.
CzVec2	TransformedClipRect [2]
	Transformed clipping rect for the scene.
CzList< CzActor * >	Removals
int	MaxCollidables
	Maximum allowed collidables.
int	NextFreeCollidable
	Points to next free slot in sollidables list pool.
int	MaxLayers
	Maximum visible layers.
Static Protected Attributes
static CzXomlClassDef *	ClassDef = NULL

Detailed Description

A scene contains, handles and tracks a group of actors.

Introduction

Sometimes understanding concepts are much easier when compared to something that one is already familiar with. In this case we will compare the making of apps and games using XOML to the making of a movie. In the movie business a scene (or set) is a place where the action takes place, it contains all of the actors, the cameras and scenery. Each actor has its own specific instructions, behaviours and purpose.

A CzScene is responsible for the following functionality:

Setup and handling of the virtual canvas
- Managing, updating and cleaning up actors
- Managing, updating, rendering and cleaning up sprites
- Managing and clean up of animation data
- Managing and clean up of animation timelines
- Managing and clean up of animation timers
- Managing and clean up of events / actions
- Managing and clean up of resources such as images and sounds
- Managing and clean up of physics materials and shapes
- Managing and clean up of XOML variables
- Managing and clean up of XOML data bindings
- Managing and clean up of XOML programs
- Managing and clean up of scripts
- Clipping sprites against the scenes visible extents
- Updating the camera
- Tracking actors that can potentially collide
- Transitions between scenes
- Updating the scenes animation timeline
- Instantiating itself from XOML
- Updating physics

Its worth noting at this point that any actors that live inside a scene will be transformed by the same transform as the scene, so if you move, scale or spin the scene then the contained actors will also move, scale and spin with it. The same can also be said about the base colour of the scene.

Creating a Scene

There are a number of ways to create a scene, lets take a look at some basic examples:

XOML Example:

<?xml version="1.0"?>
<xml>
    <Scene Name="AppScene" Current="true" CanvasSize="800, 480">
    </Scene>
</xml>

Code Example:

CzScene* scene = new CzScene();
scene->setName("AppScene");
scene->setAllowFocus(true);
scene->Init();
scene->setVirtualTransform(800, 400, 0, CzScene::Fit_None);
APP->addScene(scene);
APP->changeScene(scene);

Code Example (using macros):

CZ_NEW_SCENE_CUSTOM(scene, "AppScene", 800, 400, CzScene::Fit_None);
APP->addScene(scene);
APP->changeScene(scene);

Lua Script Example:

local my_scene = scene.create("Scene1", 800, 600, "best", "centre", false, false, "lua")
scene.setCurrent(my_scene)

Here we create a scene called AppScene that has a canvas size of 800x480 pixels. Once a scene is set-up we can begin adding the actors and other content that form our game or app.

Scene Properties

Now that we know how to create a scene lets take a look at the extensive list of properties that scenes support:

General Properties

Name - The name of the scene is a very important property and should be chosen so that it does not conflict with names of other scenes that are present at the same time. It is possible to have multiple scenes with the same name, but only one of those scenes can be created. It is possible to destroy a scene and create a new scene of the same name. A scene name should also be memorable as you may want to refer to the scene from other areas of XOML or even script.
Type (whole number) - The type of scene is a simple number that can be used to identify specific scene types. For example, you could create multiple scenes that are all related and assign them all the same type.
Extents (x, y, width, height) - A rectangular area that describes the extents of the scenes world
AllowSuspend (boolean) - Determines if the scene can be suspended when other scenes are activated
Clipping (x, y, width, height) - A rectangular area that represents the visible area of the scene
ClipStatic (boolean) � When true camera transform is not applied to the clipping rect
Active - The active state of a scene determines if the scene is processing its contents. If not active then scene processing will stop and any content that is contained within the scene will also stop processing
Visible - If a scene is not visible then it will be hidden from view, although the scene and its contents will still be processed.
Layers (number, read-only) - The number of visible actor layers that the scene should use (10 is default value)
Current (boolean) - If true then the scene is made the current scene
Camera (camera name) - Current camera
Batch (boolean) - Tells the system to batch sprites for optimised rendering, default is disabled
AllowFocus (boolean) - If set to true then this scene will receive input focus events that the current scene would usually receive exclusively. This is useful if you have a HUD overlay that has functionality but it cannot be the current scene as the game scene is currently the current scene
Style (style) - Sets scene properties from a pre-defined style (see Style tag)
UserProperties (object, read-only) � The scenes user properties list
TargetX (actor name, write-only) � Sets the actor that the camera will be used to track its x-axis
TargetY (actor name, write-only) � Sets the actor that the camera will be used to track its y-axis
Bindings (bindings name) � Defines a bindings list that binds variables to scene properties. Reading this property will return a bindings object
TimeScale (number) � Changes the speed at which an attached timeline is played. This property cannot be set when initially declaring the scene

Visual Properties

Position (x, y) - The position of the scene on screen
PositionX (number) - The X position of the scene on screen
PositionY (number) - The Y position of the scene on screen
Angle (degrees) - The orientation of the scene in degrees
Scale (scale) - The scale of the scene
CanvasSize (x, y) - The virtual canvas size of the screen
CanvasFit (none, best, both, width, or height) - The type of method to use when scaling the canvas to the devices native screen resolution
CanvasOrigin (top, left, topleft or centre) - Where to locate the canvas origin
Layer (whole number)- The visual layer that this scene should be rendered on (Valid values are 0 to 9)
Colour (r, g, b, a)- The colour of the scene, Each component red, green, blue and alpha should be between the value of 0 and 255 (0 is no colour, whilst 255 is full colour)
Opacity (opacity) - The opacity of the scene (how see-through the scene appears). Opacity value ranges from 0 (invisible) to 255 (fully visible)
Timeline (timeline) - The time line that should be used to animate the scene. Reading this property will return a timeline object

Event Properties

OnSuspend (actions list) - Provides an actions group that is called when the scene is suspended
OnResume (actions list) - Provides an actions group that is called when the scene is resumed
OnCreate (actions list) - Provides an actions group that is called when the scene is created
OnDestroy (actions list) - Provides an actions group that is called when the scene is destroyed
OnKeyBack (actions list) - Provides an actions group that is called when the user presses the back key
OnKeyMenu (actions list) - Provides an actions group that is called when the user presses the menu key
OnOrientationChanged (actions list) - Provides an actions group that is called when the user changes the devices orientation
OnTick (actions list) - Provides an actions group that is called every time the scene is updated (30 to 60 times per second)
OnDeviceSuspended (actions list, write-only) - Provides an actions group that is called when the app is suspended
OnDeviceResumed (actions list, write-only) - Provides an actions group that is called when the app is resumed
OnDeviceVolumeUp (actions list, write-only) - Provides an actions group that is called when the volume up button was pressed
OnDeviceVolumeDown (actions list, write-only) - Provides an actions group that is called when the volume down button was pressed
OnDeviceNetworkOnline (actions list, write-only) - Provides an actions group that is called when the network goes online
OnDeviceNetworkOffline (actions list, write-only) - Provides an actions group that is called when the network goes offline

Physical Properties

Gravity (x, y) - Box2D directional world gravity
WorldScale (x, y) - Box2D world scale
DoSleep (boolean) - If set to true then actors that utilise physics will be allowed to sleep when they are not moving / interacting
Physics (boolean) - Enables or disables physics processing in the scene
PhysicsTimestep (number) - Sets how fast the physics engine updates the physics world. This value is specified in number of 1/60th's of a second. So passing a value of 1 will update physics as though the frame rate of the app is running at 60 frames per second. A value of 3 would would update physics at a rate of 20 frames per second. Setting this to a value of 0 will use a variable time step based on the current frame rate of the app. The default value is 2.0 We will now take a closer look at how these properties function.

Scene Virtual Canvas

Targeting a large selection of different phones, tablets and other devices with a variety of different screen sizes and aspect ratios can be difficult to manage. Luckily scenes can take care of this for you. A scene is quite clever in that it can render itself to any sized / configuration display using the virtual canvas concept. A virtual canvas is basically our own ideal screen size that we want to render to. The scene will scale and translate its visuals to fit our canvas onto the devices display allowing us to get on with developing our app using a static resolution. Lets take a look at an example that creates a scene with a virtual canvas of 800x480:

<xml>
    <!-- Create a scene to hold our game / app actors -->
    <Scene Name="AppScene" Current="true" CanvasSize="800, 480" CanvasFit="best" >
        <!-- Actors go here -->
    </Scene>
</xml>

Using the AppScene above regardless of whatever size screen we run our app on our content will be scaled to fit an 800x480 pixel display resolution because we specified a CanvasSize of "800x480". We also told the scene to use its best judgement when scaling the scene by specifying CanvasFit="best". As an example if we run our app on an iPhone retina display at 960x640 pixels and using a canvas fit method of best fit then our app will be scaled to best fit the 960x640 resolution, which would be 960x576 pixels. The scene would be centred on the screen leaving a little space at the top and bottom of the display.

Scenes support a number of ways of fitting the the virtual canvas to the device screen including:

none - No scaling is performed. This is ideal if you want a 1:1 pixel ratio and mostly used by apps and games that use proportional sizing and positioning.
both - The scene is scaled to fit the exact size of the display ignoring aspect ratio (aspect ratio is the ratio of the screens width to the screens height). The problem with this method of scaling is that the scene will be stretched on displays with different aspect ratios which can make certain apps look odd.
best - The scene is scaled to best fit the devices display size whilst maintaining aspect ratio. This method of scaling prevents stretched graphics, however it can leave gaps to the top and bottom or left and right
width / height - This method of scaling is the same as best except scaling is locked to either the width or the height.

Scenes also provide a way to allow you to specify how coordinates are interpreted allowing you to place content relative to either the centre, left, top-left or top of the screen. The scenes origin is by default set to the centre of the scene, but it can be changed by supplying the CanvasOrigin property when declaring the scene, e.g.:

<Scene Name="AppScene" Current="true" CanvasOrigin="topleft">

This scene places actors relative to the top-left hand corner of the scene instead of relative to the centre. However, we find that having the scenes origin at the centre is much better and feels more natural when designing apps an games for a variety of screen sizes as content can be allowed to extend from the centre and beyond the scenes size. The default canvas size for a scene is the devices native display resolution

Scene Layers and Actor Layering

Because an app can contain multiple scenes that are visible at the same time, its sometimes required to sort the order in which these scenes are displayed. For example, you may have a game that has a background layer, a game object layer and a foreground layer. The visibility ordering of these scenes will be displayed in the opposite order to which you create them. For example, if you create the foreground scene and then the background scene afterwards then the background scene will be drawn on top of the foreground scene, which is the wrong way around. You could remedy this problem by adding the background scene first, but sometimes this is not practical. To eliminate the problem, scenes can be placed on a layer of depth by setting the Layer="layer number" (layer numbers 0 to 9 are supported with 9 being the highest layer) property of the scene. Scenes that are placed on the same layer will be sorted in the order they were added, with more recent additions appearing on top. Each scene also determines how actors are sorted in a scene (we will discuss actors in great depth later). We can define how many layers are available for the actor system to use by adding the Layers="number of layers" property to the scene definition. The default is 16 which is fine for most applications.

An example has been provided that demonstrates scene layering (see SceneLayers example). Lets take a quick look at an extract of the XOML for this example:

<!-- Create scene 1 on highest layer -->
<Scene Name="Scene1" Layer="9">
</Scene>
<!-- Create scene 2 on middle layer -->
<Scene Name="Scene2" Layer="5">
</Scene>
<!-- Create scene 3 on highest layer -->
<Scene Name="Scene3" Layer="0">
</Scene>

Here we create 3 scenes and assign each one a different layer.

Current Scene

An app generally consists of a number of different scenes that all contain their own objects. However only one scene can normally receive input. This scene is known as the current or focus scene. When you declare a scene it can be made to be the current scene by adding Current="true" to the scene definition. By comparison, you could think of all of the different windows on your PC or Mac as separate scenes, but only one of those windows can usually accept user input at one time. When a scene is made current it is brought to the front of any scenes that are on the same layer (more on layers later).

It is also possible to mark scenes so that more than one scene can receive input events at the same time. This can be useful if you have two scenes on lower layers that need to also receive input. For example, you may have a heads-up display that has functional buttons on the highest layer and the game scene on a lower layer that also needs to receive input events. To mark a scene to receive input events you need to add the AllowFocus="true" attribute to your scene definition.

Suspending and Resuming Scenes

By default all active scenes in your app will be processed continuously. However this is not always required and for apps that contain a lot of active scenes it can slow down your app. Scenes can be suspended so that they stop processing (they will still be visible). In fact, scenes that allow suspending / resuming are automatically suspended when you change the current scene to another scene. To enable suspending / resuming for a scene you should set its AllowSuspend="true" property. When a scene is suspended or resumed it will fire a suspend or resume event which allows you to perform actions (more on this later).

The follownig two methods handle scene suspend / resume:

NotifySuspending(CzScene* new_scene); - This event is called when this scene is being suspended
NotifyResuming(CzScene* old_scene); - This event is called when this scene is being resumed

Like all event handlers its possible to override these if you derive your own scene class from CzScene and handle these events as you see fit.

Scenes can be suspended and resumed using the following actions in XOML:

ChangeScene - The previous scene will be suspended and the new scene will be resumed (provided that the scenes have AllowSuspend="true" defined)
SuspendScene - Suspends the scene even if suspend / resume is disabled for the scene
ResumeScene - Resumes the scene even if suspend / resume is disabled for the scene

Scene Extents

Scenes can be as large or as small as you like, they can even be many times larger than the devices screen size. This enables you to create content that exists in a much larger space than the screen can display. You can then allow the user to pan around the scene to view more of the content. The size of your scenes world can be set using the Extents property which accepts 4 values which represent the rectangular area that objects can exist in. Actors can be made so that when they hit the edge of the scenes extents they re-appear on the opposite side (much like asteroids in the old Atari game Asteroids does), this is called wrapping. An example called SceneExtents has been provided that shows an actor moving across the scene, it wraps back around to the opposite end of the scene when it hits the scenes extents. Lets take a quick look at the XOML for this example:

<!-- Create scene with narrow extents -->
<Scene Name="Scene1" Extents="-100, -100, 200, 200" Current="true">
    <!-- Create a label object -->
    <Label Font="serif" Background="Button1Brush" BackgroundColour="255, 80, 80, 255" Text="Wrapping" WrapPosition="true" OnTick="Update">
        <Actions Name="Update">
            <Action Method="AddProperty" Param1="Position" Param2="2, 2" />
        </Actions>
    </Label>
</Scene>

This example introduces some concepts that you have not yet met such as actions and events. You do not need to worry about these for now as we are only focusing on the bold sections. Note how we have set the scenes extents using Extents="-100, -100, 200, 200". This collection of 4 value represent the left, top, width and height of the scenes extents. Also note that our Label has been given a new property called WrapPosition which is set to true. This tells the Label actor to wrap its position when it hits the edges of the scenes extents.

Scene Clipping

When a scene is smaller than the devices display size its sometimes useful to be able to ensure that anything that is drawn within the scene is not drawn outside the scene. To accomplish this we need to clip content that falls outside the scenes area of coverage. To tell a Scene to clip its contents you add the Clipping property which takes 4 values (left, top, width, height). An example has been provided called SceneClipping which demonstrates how to apply scene clipping. Lets take a quick look at this example:

<!-- Create scene with narrow extents -->
<Scene Name="Scene1" Extents="-100, -100, 200, 200" Clipping="-100, -100, 200, 200" Current="true" />

In this example we limit the scenes extents and set the clipping area to -100, -100, 200, 200. By default the scenes clipping area will move around with the scene, although you can modify this behaviour to force the clipping area to remain in place on screen. To force clipping to remain in place add ClipStatic="true" to your scene definition.

Scene Events

An event is something that occurs in your app that you may or may not want to know about and act upon. For example, when the scene is first created the OnCreate event is raised. Using actions (explained later) you can react to these events and modify your apps behaviour.

Internally the scene handles events using the Events Manager (EventsManager). This manager handles the mapping between events and actions lists that should be called when the events take place. To add an event to the events manager we call EventsManager->addEvent(event_name, action_list_name), e.g:

 EventsManager->addEvent("OnSuspend", "SuspendedActions");

This example ties the SuspendedActions list that was previously defined in XOML using the Actions tag to the OnSuspend event. When an event takes place the corresponding event notification method of CzScene is called, for example NotifyCreate() is called when the scene is created. This in turn calls CzScene::ProcessEventActions() to handle the event. ProcessEventActions examines its list of subscribed events to see if the event has been subsribed to. If it has then the corresponding actions list will be called. if you do not wish to use actions lists to respond to events then yuo can simply derive your own sceen class from CzScene, override the event notification methods such as NotifyCreate() and write your own implementation.

You can listen to events by adding an OnEvent property to the scene. Lets take a look at the list of events that can occur in a scene:

OnSuspend - This event is raised when the scene is suspended. A scene is suspended if it is the current scene and another scene becomes the current scene (for scenes that support suspend / resume) or when a SuspendScene action is called
OnResume - This event is raised when a scene is resumed (become the current scene) or when a ResumeScene action is called
OnCreate - This event is raised when the scene is first created and gives you the opportunity to handle post scene creation logic. You could use this event to for example play a sound or hide another scene etc..
OnDestroy - This event is raised when the scene is about to be destroyed, this gives you the opportunity to clean-up certain elements
OnKeyBack - This event is raised when the user pressed the back button
OnKeyMenu - This event is raised when the user pressed the menu button
OnOrientationChanged - This event is raised when the devices orientation changes an allows yo to for example modify the scenes layout.
OnTick - This event handler is raised every time the scene is updated (30 to 60 times per second)
OnDeviceSuspended (actions list, write-only) - Provides an actions group that is called when the app is suspended
OnDeviceResumed (actions list, write-only) - Provides an actions group that is called when the app is resumed
OnDeviceVolumeUp (actions list, write-only) - Provides an actions group that is called when the volume up button was pressed
OnDeviceVolumeDown (actions list, write-only) - Provides an actions group that is called when the volume down button was pressed
OnDeviceNetworkOnline (actions list, write-only) - Provides an actions group that is called when the network goes online
OnDeviceNetworkOffline (actions list, write-only) - Provides an actions group that is called when the network goes offline

The SceneEvents example shows an example showing how to handle the scenes OnTick event.

Scene Animation Properties

Scenes can be animated using animations defined in XOML. Whilst not all properties of a scene can be animated many can including:

Position (x, y) - The position of the scene on screen
Angle (degrees) - The orientation of the scene in degrees
Scale (scale) - The scale of the scene
Colour (r, g, b, a)- The colour of the scene, Each component red, green, blue and alpha should be between the value of 0 and 255 (0 is no colour, whilst 255 is full colour)
Opacity (opacity)- The opacity of the scene (how see-through the scene appears). Opacity value ranges from 0 (invisible) to 255 (fully visible)
Clipping (x, y, width, height) - The clipping area of the scene
Visible (boolean) - The visibility of the scene
Timeline (timeline) - The animation timeline that is currently being used to animate the scene. Timelines are great for creating complex scene transitions
Camera (camera) - The current camera that is viewing the scene The SceneAnimation example has been provided that shows how to apply animation to a scene
PhysicsTimestep (number) - This can be used to modify the speed at which physics updates allowing you to slow down or speed up physics.

Scene Modifiable Properties

Scenes can be queried and modified after their creation using actions, command and scripts. The following properties are includes:

General Properties

Name (string)
Type (number)
Extents (x, y, width, height)
AllowSuspend (boolean)
Clipping (x, y, width, height)
Active (boolean)
Visible (boolean)
Current (boolean)
Camera (camera)
AllowFocus (boolean)

Visual Properties

Layer (number)
Colour (r, g, b, a)
Opacity (opacity)
Timeline (timeline)
TimeScale (number) - Speed at which to play back any attached timelines

Event Properties

OnCreate (actions list)
OnDestroy (actions list)
OnKeyBack (actions list)
OnKeyMenu (actions list)
OnOrientationChanged (actions list)
OnTick (actions list)

Physical Properties

Gravity (x, y)
WorldScale (x, y)

Scene Rendering

A scene has no actual visible component, instead it renders all of its contained actor objects. All actor objects are moved, rotated and scaled by the same amount that the scene is. For example, if you move the scene to the left, all contained actors will also moved to the left. If you rotate the scene to the right 45 degrees then all actors also rotate 45 degrees to the right. In addition, all scene actors will be scaled by the scenes colour and opacity settings, so if you fad down the scene all actors will also fade down with it.

Scenes support a method of optimisation known as batch rendering. This is the process of combining actors together at render time to render them all in one go, which can substantially speed up rendering for scenes that contain many actors. To force a scene to use batch rendering add Batch="true" to the scene definition. However, scenes that are marked as batch enabled will not sort their contained actors properly with the likes of fonts, so you will need to use actor layers to force the sorting.

When a scene is hidden from view, all of its actors will also be hidden. When a scene is deleted all of its actors are also deleted.

Scene Cameras

A camera is a view into the scene from a specific position, angle and scale. In order to move, rotate and scale a scene a camera should be created and attached to it. To create a camera you use the Camera XOML tag:

<!-- Create a camera -->
<Camera Name="Camera1" />

To attach the camera to the scene we add the Camera attribute to the scene definition:

<Scene Name="Scene1" Current="true" Camera="Camera1">

When we navigate a scene we are actually moving the camera view within the scene. When we move the camera objects tend to move in the opposite direction, for example moving the camera left moves the scene actors move to the right. If you think about how a real camera works, when you move the camera in one direction the view seen by the camera moves in the opposite direction.

Its possible to create a number of different cameras and switch between them to offer different views into the scene. Cameras offer a great out of the box feature called touch panning, which enables the user to pan the camera a round a scene on the x and y axis by dragging their finger around the scene. Take a look at the ScenePanning example for an example showing how to use touch panning.

Scene Augmentation

A scene once declared in XOML can later be updated / augmented with additional XOML elsewhere. For example, lets say that you declare some common scene that contains a basic background and some other elements that are common across a number of screens. You can later load the scene and then augment it by declaring the scene again supplying the additional elements inside the newly declared scene:

<Scene Name="CommonScene" ............ >
    <Original_Element1 />
    <Original_Element2 />
    <Original_Element3 />
</Scene>

Now declare a 2nd scene with the same name:

<Scene Name="CommonScene">
    <Extra_Element1 />
    <Extra_Element2 />
    <Extra_Element3 />
</Scene>

In memory the scene now looks like this:

<Scene Name="CommonScene" ............ >
    <Original_Element1 />
    <Original_Element2 />
    <Original_Element3 />
    <Extra_Element1 />
    <Extra_Element2 />
    <Extra_Element3 />
</Scene>

For a working example of augmented scenes take a look at the SceneAugmentation example.

Scene Physics

XOML scenes can run actors that are under the influence of the Box2D physics systems. The scene system allows you to specify some scene global information about the physics simulation. The following scene global properties can be set by adding the relevant tags to the scene definition:

Gravity (x, y) - Box2D directional world gravity. Box2D uses directional gravity which means you can have gravity act in any direction.
WorldScale (x, y) - Box2D world scale. This value determines how your visible world scales to the Box2D world (default is 10, 10)
DoSleep (boolean) - If set to true then actors that utilise physics will be allowed to sleep when they are not moving / interacting, this can help speed up scenes that contain many actors that are under Box2D control.
Physics (boolean) - Enables or disables physics processing in the scene, enabled by default. Disable in scenes that do not use physics to maximise performance.
PhysicsTimestep (number) - Sets how fast the physics engine updates the physics world. This value is specified in number of 1/60th's of a second. So passing a value of 1 will update physics as though the frame rate of the app is running at 60 frames per second. A value of 3 would would update physics at a rate of 20 frames per second. Setting this to a value of 0 will use a variable time step based on the current frame rate of the app. The default value is 2.0 To see how scene physics is used please take a look at the ScenePhysics example.

Creating a Custom Scene

Generally and for the most part a standard CzScene can be used to accomplish most things with AppEasy scenes, especiallu if devloping most if not all of your aoo in XOML / Lua, however for those that require a little more control its possible to derive your own scene from CzScene and implement the supplied virtual methods to override certain functionality. The main 3 methods that you should consider re-implementing includes:

int Init(int max_collidables = 128, int max_layers = 10, bool doSleep = true)
void Update(float dt)
void Draw()

Here's a quick example:

class MyGameScene : public CzScene
{
public:
    MyGameScene() : CzScene() {}
    virtual ~MyGameScene();

    int     Init(int max_collidables = 128, int max_layers = 10, bool doSleep = true)
    {
        CzScene::Init(max_collidables, max_layers, doSleep);
    }
    void    Update(float dt)
    {
        CzScene::Update(dt);
    }
    void    Draw()
    {
        CzScene::Draw();
    }
};

We have provided a very basic implementation of Init(), Update() and Draw() which call the base CzScene class methods so we keep its functionality in-tact.

You can take the implementation one step further (or maybe two) by implementing both the IzXomlResource and IzAnimTarget interfaces to allow instantiation of your custom class from XOML and to allow your class to be a target for animation time lines.

Firstly lets take a look at XOML enabling your custom scene class. To get AppEasy to recognise your class whilst parsing XOML files you need to do a few things:

Derive your class from IzXomlResource and implement the LoadFromXoml method
Create a class creator that creates an instance of your class then add this to the XOML engine

Lets start by taking a look at step 1.

Because we have derived our class from CzScene (which is derived from IzXomlResource) we already have the support for step 1. However we would like to insert our own custom attribute tags so we need to make a few changes.

Lets take a look at our new class with those changes:

class MyGameScene : public CzScene
{
public:
    // Properties
protected:
    float       Gravity;
public:
    void        setGravity(float gravity)   { Gravity = gravity; }
    float       getGravity() const          { return Gravity; }
    // Properties End
public:
    MyGameScene() : CzScene(), Gravity(10.0f) {}
    virtual ~MyGameScene();

    virtual int     Init(int max_collidables = 128, int max_layers = 10, bool doSleep = true)
    {
        CzScene::Init(max_collidables, max_layers, doSleep);
    }
    virtual void    Update(float dt)
    {
        CzScene::Update(dt);
    }
    virtual void    Draw()
    {
        CzScene::Draw();
    }

    // Implementation of IzXomlResource interface
    bool            LoadFromXoml(IzXomlResource* parent, bool load_children, CzXmlNode* node)
    {
        if (!CzScene::LoadFromXoml(parent, load_children, node))
            return false;

        // Add our own custom attribute parsing
        for (CzXmlNode::_AttribIterator it = node->attribs_begin(); it != node->attribs_end(); it++)
        {
            unsigned int name_hash = (*it)->getName().getHash();

            if (name_hash == CzString::CalculateHash("Gravity"))
            {
                setGravity((*it)->getValueAsFloat());
            }
        }

        return true;
    }
};

Our new class now basically supports a Gravity attribute that we will eventually be able to set in XOML using something like:

<MyGameScene Name="GameScene" Gravity="9.8">
</MyGameScene>

However, before we can do that we need to let the XOML system know about our new type of class (MyGameScene), so it can be instantiated when the XOM parser comes across it. To do this we need to create a creator:

class MyGameSceneCreator : public IzXomlClassCreator
{
public:
    MyGameSceneCreator()
    {
        setClassName("MyGameScene");
    }
    IzXomlResource* CreateInstance(IzXomlResource* parent) { return new MyGameScene(); }
};

The creator basically defines the tag name "MyGameScene" and returns an instance of the MyGameScene class when CreateInstance() is called.

To get the XOML system to recognise our creator we need to add it to the XOML parsing system using:

// Add custom MyGameScene to XOML system
CZ_XOML->addClass(new MyGameSceneCreator());

Now XOML integration is out of the way, lets take a quick look at enabling our class as an animation target.

To enable a class as an animation target we derive it from IzAnimTarget and implement the UpdateFromAnimation() method. Luckily we derived our MyGameScene class from the CzScene class which already provides this functionality. Lets take a quick look at how we extend the animation update method to account for animating our gravity variable.

bool MyGameScene::UpdateFromAnimation(CzAnimInstance *animation)
{
    if (CzScene::UpdateFromAnimation(animation))
        return true;

    // Add our own custom animating property
    unsigned int property_name = animation->getTargetPropertyHash();

    if (property_name == CzString::CalculateHash("Gravity"))
    {
        CzAnimFrameFloat* frame = (CzAnimFrameFloat*)animation->getCurrentData();
        setGravity(frame->data);
        return true;
    }

    return false;
}

We added the above code to our MyGameScene class definition. We begin by calling the base UpdateFromAnimation() method so we can keep the existing animation properties of the scene. We then add our own custom check for the Gravity variable. If the animation property matches Gravity then we set the gravity to the provided interpolated value.

Member Typedef Documentation

typedef CzList<CzActor*>::iterator CzScene::_Iterator

Member Enumeration Documentation

enum CzScene::eCanvasFit

Values that define how the virtual canvas is fit to the devices screen.

Enumerator:

Fit_None	No scaling is performed. This is ideal if you want a 1:1 pixel ratio and mostly used by apps and games that use proportional sizing and positioning.
Fit_Width	This method of scaling is the same as best except scaling is locked to the width.
Fit_Height	This method of scaling is the same as best except scaling is locked to the height.
Fit_Both	The scene is scaled to fit the exact size of the display ignoring aspect ratio (aspect ratio is the ratio of the screens width to the screens height). The problem with this method of scaling is that the scene will be stretched on displays with different aspect ratios which can make certain apps look odd.
Fit_Best	The scene is scaled to best fit the devices display size whilst maintaining aspect ratio. This method of scaling prevents stretched graphics, however it can leave gaps to the top and bottom or left and right.

enum CzScene::eCanvasOrigin

Values that define the placement of teh canvas origin.

Enumerator:

Origin_Centre	Origin is at the centre of the screen.
Origin_Top	Origin is at the top centre of the screen.
Origin_Left	Origin is at the left middle of the screen.
Origin_TopLeft	Origin is at the rop left of the screen.

enum CzScene::eDocking

Values that define acor docking.

Enumerator:

Dock_None
Dock_Top
Dock_Bottom
Dock_Left
Dock_Right
Dock_TopLeft
Dock_TopRight
Dock_BottomLeft
Dock_BottomRight

enum CzScene::eOrientation

Values that define the orientation of the screen.

Enumerator:

Orientation_Landscape	Landscape orientation (width > height)
Orientation_Portrait	Portrait orientation (width < height)

Constructor & Destructor Documentation

CzScene::CzScene ( ) [inline]

CzScene::~CzScene ( ) [virtual]

CzScene destructor.

Cleans up the scene and all of iots contents.

Member Function Documentation

CzXomlProperty CzScene::_getActive ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getAllowFocus ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getAllowSuspend ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getAngle ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getBatch ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getBindings ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getCamera ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getCanvasFit ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getCanvasOrigin ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getCanvasSize ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getClipping ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getClipStatic ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getColour ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getCurrent ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getExtents ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getGravity ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getLayer ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getLayers ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getName ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getOpacity ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getPhysics ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getPhysicsTimeStep ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getPosition ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getPositionX ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getPositionY ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getScale ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getScriptEngine ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getTimeline ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getTimeScale ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getType ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getUserProperties ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getVisible ( IzXomlResource * target ) [static]

CzXomlProperty CzScene::_getWorldScale ( IzXomlResource * target ) [static]

bool CzScene::_setActive	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setAllowFocus	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setAllowSuspend	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setAngle	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setBatch	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setBindings	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setCamera	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setCanvasFit	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setCanvasOrigin	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setCanvasSize	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setClipping	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setClipStatic	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setColour	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setCurrent	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setExtents	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setGravity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setLayer	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setName	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnCreate	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDestroy	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceNetworkOffline	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceNetworkOnline	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceResumed	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceSuspended	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceVolumeDown	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnDeviceVolumeUp	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnGainedFocus	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnKeyBack	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnKeyMenu	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnLostFocus	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnOrientationChange	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnPan	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnResume	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnSuspend	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOnTick	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setOpacity	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setPhysics	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setPhysicsTimeStep	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setPosition	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setPositionX	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setPositionY	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setScale	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setScriptEngine	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setTargetX	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setTargetY	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setTimeline	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setTimeScale	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setType	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setVisible	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzScene::_setWorldScale	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

void CzScene::addActor ( CzActor * actor )

Adds an actor to the scene.

Parameters:

[in,out] actor If non-null, the actor.

bool CzScene::addCollideable ( CzActor * actor )

Adds n actor to the a collideables list.

Parameters:

[in] actor If non-null, the actor.

Returns:: true if it succeeds, false if it fails.

_Iterator CzScene::begin ( ) [inline]

int CzScene::checkActorState ( CzActor * actor )

Checks the actors current state.

Parameters:

[in] actor If non-null, the actor.

Returns:: 0 - actor not found 1 - actor is destroyed 2 - actor is not destroyed.

void CzScene::CheckforInvalidRemovals ( const char * check_point )

Checks the actor removals list for invalid removals.

Parameters:

check_point The check point name.

void CzScene::CleanupRemovedActors ( )

Cleans up removed actors.

Cleans up any actors that were destroyed during the last frame. Also removes any desdtrpyed actors from the touch and key focus lists.

void CzScene::clearActors ( bool ignore_visuals = false )

Clears and destroys all actors in the scene.

ignore_visuals - When a scene closes down we dont want actors to delete their own visuals as the sprite manager will auto clean them up when it shuts down

Parameters:

ignore_visuals true to ignore visuals.

void CzScene::Draw ( ) [virtual]

Draws this scene.

Renders the scene and all of its contents. This includes:

Updating actor visuals
Setting the scenes transformed clipping rectangle
Drwing the scenes sprite manager

_Iterator CzScene::end ( ) [inline]

CzActor * CzScene::findActor ( const char * name )

Searches for the named actor.

Parameters:

name	The actors name.

Returns:: null if not found, else the found actor.

CzActor * CzScene::findActor ( unsigned int name_hash )

Searches for the named actor.

Parameters:

name_hash The actors name as a strnig hash.

Returns:: null if not found, else the found actor.

CzActor * CzScene::findActor ( int type )

Searches for the first actor of the specified type.

Parameters:

type	The actor type.

Returns:: null if not found, else the found actor.

bool CzScene::findActorInRemovals ( CzActor * actor )

Searches for the actor in the actor removals list.

When an actor is removed during scene processing, it is added to a removals list which gets cleaned up at the end of scene. This method will search the rmovals list to check if the actor is already in the removals list.

Parameters:

[in] actor If non-null, the actor.

Returns:: true if it succeeds, false if it fails.

int CzScene::findActors	(	unsigned int	tag_hash,
		CzVector< CzActor * > &	actors
	)

Searches for a group of actors that have a specific group tag name.

Parameters:

	tag_hash	The group tag as a string hash.
[out]	actors	[out] The actors that were found.

Returns:: The number of found actors.

int CzScene::findActorsOfType	(	int	type,
		CzVector< CzActor * > &	actors
	)

Searches for a group of actors that have a specific group tag name.

Parameters:

	type	The type of actor
[out]	actors	[out] The actors that were found.

Returns:: The number of found actors.

CzActor * CzScene::findClosestActor	(	int	x,
		int	y,
		int	type
	)

Searches for the actor of the specific type that is nearest to the specified point.

Parameters:

x	The x coordinate of the point in scene coordinates.
y	The y coordinate of the point in scene coordinates.
type	The actor type.

Returns:: null if not found, else the found actor.

CzActor * CzScene::findFurthestActor	(	int	x,
		int	y,
		int	type
	)

Searches for the actor of the specific type that is furthest from the specified point.

Parameters:

x	The x coordinate of the point in scene coordinates.
y	The y coordinate of the point in scene coordinates.
type	The actor type.

Returns:: null if not found, else the found actor.

CzActor * CzScene::FindTappedActor	(	int	x,
		int	y
	)

Searches for the first tapped actor.

Searches this scene to see if the supplied point lies within the boundaries of an actor. If one is found then it is returned. Actors on higher actor layers will be chosen over actors on lower layers.

Parameters:

x	The x screen coordinate to test.
y	The y screen coordinate to test.

Returns:: null if none found, else the found tapped actor.

void CzScene::fixActors ( CzActor * parent )

CzActionsManager* CzScene::getActionsManager ( ) [inline]

CzList<CzActor*>& CzScene::getActors ( ) [inline]

bool CzScene::getAllowFocus ( ) const [inline]

bool CzScene::getAllowSuspend ( ) const [inline]

CzXomlBindings* CzScene::getBindings ( ) [inline]

CzBox2dWorld* CzScene::getBox2dWorld ( ) [inline]

CzCamera* CzScene::getCamera ( ) [inline]

eCanvasFit CzScene::getCanvasFit ( ) const [inline]

eCanvasOrigin CzScene::getCanvasOrigin ( ) const [inline]

CzIRect CzScene::getClippingArea ( ) [inline]

CzActor** CzScene::getCollidables ( ) [inline]

CzColour CzScene::getColour ( ) const [inline]

float CzScene::getConstantTimeStep ( ) const [inline]

CzEventManager* CzScene::getEventsManager ( ) [inline]

CzIRect CzScene::getExtents ( ) const [inline]

int CzScene::getLayer ( ) const [inline]

int CzScene::getMaxLayers ( ) const [inline]

CzModifierManager* CzScene::getModifiers ( ) [inline]

int CzScene::getOpacity ( ) const [inline]

eOrientation CzScene::getOrientation ( ) const [inline]

CzIVec2 CzScene::getOriginalSize ( ) const [inline]

CzApp* CzScene::getParent ( ) [inline]

Reimplemented from IzXomlResource.

CzProgramManager* CzScene::getProgramManager ( ) [inline]

bool CzScene::getProperty	(	const char *	property_name,
		CzXomlProperty &	prop
	)

Gets the named property of the scene.

Returns the named property of the scene. The properties value is returned in a CzXomlProperty which is a structure that contains a union of all possible property types.

Parameters:

	property_name	Name of the property.
[out]	prop	The property data.

Returns:: true if it succeeds, false if property does not exist.

bool CzScene::getProperty	(	unsigned int	property_name,
		CzXomlProperty &	prop
	)		`[virtual]`

Returns the named property of the scene. The properties value is returned in a CzXomlProperty which is a structure that contains a union of all possible property types.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in,out]	prop	The property.

Returns:: true if it succeeds, false if property does not exist.

CzXomlResourceManager* CzScene::getResourceManager ( ) [inline]

int CzScene::getRunCount ( ) const [inline]

CzIVec2 CzScene::getScreenSize ( ) const [inline]

IzScriptEngine* CzScene::getScriptEngine ( ) [inline]

CzSpriteManager* CzScene::getSpriteManager ( ) [inline]

bool CzScene::getTickEnabled ( ) const [inline]

CzAnimTimeline* CzScene::getTimeline ( ) [inline]

CzAnimTimelinesManager* CzScene::getTimelinesManager ( ) [inline]

CzTimersManager* CzScene::getTimersManager ( ) [inline]

int CzScene::getTotalCollidables ( ) const [inline]

CzMatrix3& CzScene::getTransform ( ) [inline]

int CzScene::getType ( ) const [inline]

CzUserPropertyList* CzScene::getUserPropertyList ( ) [inline]

CzXomlVariableManager* CzScene::getVariableManager ( ) [inline]

CzIVec2 CzScene::getVirtualSize ( ) const [inline]

CzMatrix3& CzScene::getVirtualTransform ( ) [inline]

int CzScene::Init	(	int	max_collidables = `128`,
		int	max_layers = `10`,
		bool	doSleep = `true`
	)		`[virtual]`

Initialises this scene.

Parameters:

max_collidables	The maximum number of collidables.
max_layers	The maximum number of layers.
doSleep	true to allow physics object sleeping.

Returns:: 1 for success.

void CzScene::InitClass ( ) [static]

Initialises the class.

Sets up the classes avaiiable properties. Used by the XOML system to find, set amd get class properties.

bool CzScene::isActive ( ) const [inline]

bool CzScene::isBatching ( ) const [inline]

bool CzScene::isClipStatic ( ) const [inline]

bool CzScene::isDestroyed ( ) const [inline]

bool CzScene::isDragging ( ) const [inline]

bool CzScene::isPhysicsEnabled ( ) const [inline]

bool CzScene::isVisible ( ) const [inline]

int CzScene::LoadFromXoml	(	IzXomlResource *	parent,
		bool	load_children,
		CzXmlNode *	node
	)		`[virtual]`

Creates an instance of this class from XOML.

LoadFromXoml is the main method used by all classes that can be instantiated from XOML mark-up. This method creates an instance of this class from the supplied XML node structure specified by node. Note that a scene can only be loaded into the main app, so parent must be of type CzApp.

Parameters:

[in]	parent	If non-null, the parent.
	load_children	true to load child nodes.
[in]	node	If non-null, the XOML markup node that defines this object

Returns:: nergative value for error. if 0 then processing of further XOML will stop.

Implements IzXomlResource.

void CzScene::NotifyCreate ( ) [virtual]

This event is called when this scene is being created.

void CzScene::NotifyDestroy ( ) [virtual]

This event is called when this scene is being destroyed.

void CzScene::NotifyDeviceNetworkOffline ( ) [virtual]

This event is called when this scene receives a network offline event.

void CzScene::NotifyDeviceNetworkOnline ( ) [virtual]

This event is called when this scene receives a network online event.

void CzScene::NotifyDeviceResumed ( ) [virtual]

This event is called when this scene receives a device resumed event.

void CzScene::NotifyDeviceSuspended ( ) [virtual]

This event is called when this scene receives a device suspended event.

void CzScene::NotifyDeviceVolumeDown ( ) [virtual]

This event is called when this scene receives a device volume down event.

void CzScene::NotifyDeviceVolumeUp ( ) [virtual]

This event is called when this scene receives a device volume up event.

void CzScene::NotifyGainedFocus ( CzScene * old_scene ) [virtual]

This event is called when this scene has just gained focus.

void CzScene::NotifyKeyBack ( ) [virtual]

This event is called when this scene receives a back key press.

void CzScene::NotifyKeyMenu ( ) [virtual]

This event is called when this scene receives a menu key press.

void CzScene::NotifyLostFocus ( CzScene * new_scene ) [virtual]

This event is called when this scene has just lost focus.

void CzScene::NotifyOrientationChanged ( ) [virtual]

This event is called when this scene receives an orientatin changed event.

void CzScene::NotifyPan ( ) [virtual]

This event is called when this scene is panned.

void CzScene::NotifyResuming ( CzScene * old_scene ) [virtual]

This event is called when this scene is being resumed.

void CzScene::NotifySizeChanged ( ) [virtual]

This event is called when this scene receives a size changed event.

void CzScene::NotifySuspending ( CzScene * new_scene ) [virtual]

This event is called when this scene is being suspended.

bool CzScene::PostLoadFromXoml	(	IzXomlResource *	parent,
		CzXmlNode *	node
	)		`[virtual]`

Carries out any post XOML loading tasks.

PostLoadFromXoml adds the opportunity to carry out post load events, such as when the scene has finished loading all of its content. In this case we update the scenes bindings for the first time to ensure that the scenes bound properties have the same values as the variables that they are bound to. We also first off ht OnCreate event.

Parameters:

[in]	parent	If non-null, the parent.
[in]	node	If non-null, the XOML markup node that defines this object

Returns:: true if it succeeds, false if it fails.

Reimplemented from IzXomlResource.

virtual void CzScene::PreDestroy ( ) [inline, virtual]

void CzScene::ProcessEventActions ( unsigned int event_name )

Process the event actions described by event_name.

Processes the actions list that is associated with the event named event_name (event_name is a hash of the actual event name to speed up searches)

Parameters:

event_name Name of the event as a string hash

void CzScene::ReleaseClass ( ) [static]

void CzScene::removeActor	(	CzActor *	actor,
		bool	instant_delete = `false`
	)

Removes the actor from the scene.

If instant_delete is false (as by default) then the specified actor will be marked as destroyed and added to the scenes actor removal list, which is cleaned up at the end of the scene. If instant_delete is true then the actor will instead of removed from the scene and instantly deleted.

Note that when an actor is removed from the scene, all actors that link to the actor will also be removed.

Parameters:

[in,out]	actor	If non-null, the actor.
	instant_delete	true to instant delete the actor.

void CzScene::removeActor	(	unsigned int	name_hash,
		bool	instant_delete = `false`
	)

Removes the actor from the scene.

If instant_delete is false (as by default) then the specified actor will be marked as destroyed and added to the scenes actor removal list, which is cleaned up at the end of the scene. If instant_delete is true then the actor will instead of removed from the scene and instantly deleted.

Note that when an actor is removed from the scene, all actors that link to the actor will also be removed.

Parameters:

name_hash	Actor name as a string hash.
instant_delete	true to instant delete the actor.

void CzScene::removeActorNoDelete ( CzActor * actor )

Removes the actor from the scene without cleaning it up.

Sometimes you may want to remove an actor from a scene without destroying, for example if you want to take an actor frop one scene and place it in another scene.

Parameters:

[in] actor If non-null, the actor.

void CzScene::removeActors ( unsigned int tag_hash )

Removes all actors that belong to the spcified group.

Parameters:

tag_hash The group tag as a string hash hash.

void CzScene::removeLinkedActors	(	CzActor *	actor,
		bool	instant_delete = `false`
	)

Removes all actors that link to the specified actor.

Parameters:

[in,out]	actor	If non-null, the actor.
	instant_delete	true to instant delete.

void CzScene::RestoreClipping ( )

Restore the scenes clipping rectangle.

void CzScene::Resume ( CzScene * old_scene )

Resumes this scene.

Parameters:

[in,out] old_scene If non-null, the old scene.

CzVec2 CzScene::ScreenToCamera	(	float	pos_x,
		float	pos_y,
		bool	ignore_translation = `false`
	)

Returns a virtual position from a position taking into account camera position.

Converts a device screen coordinates to the scenes camera coordinates.

Parameters:

pos_x	The position x coordinate in screen coordinates.
pos_y	The position y coordinate in screen coordinates.
ignore_translation	true to ignore translation.

Returns:: Scene camera coordinate.

CzVec2 CzScene::ScreenToVirtual	(	float	screen_x,
		float	screen_y,
		bool	ignore_translation = `false`
	)

Returns a virtual position from a screen position.

Converts a device screen coordinates to scene virtual canvas coordinates.

Parameters:

screen_x	The screen x coordinate.
screen_y	The screen y coordinate.
ignore_translation	true to ignore translation.

Returns:: Scene virtual canvas coordinate.

void CzScene::setActive ( bool active ) [inline]

void CzScene::setAllowFocus ( bool allow ) [inline]

void CzScene::setAllowSuspend ( bool allow_suspend ) [inline]

void CzScene::setBatching ( bool enabled ) [inline]

void CzScene::setBindings ( CzXomlBindings * bindings ) [inline]

void CzScene::setCamera ( CzCamera * camera )

Sets the scenes current camera.

Parameters:

[in,out] camera If non-null, the camera.

void CzScene::setCanvasFit ( eCanvasFit fit ) [inline]

void CzScene::setCanvasOrigin ( eCanvasOrigin org ) [inline]

void CzScene::setClippingArea	(	int	x,
		int	y,
		int	w,
		int	h
	)		`[inline]`

void CzScene::setClipStatic ( bool is_static ) [inline]

void CzScene::setColour ( const CzColour & colour ) [inline]

void CzScene::setColour	(	uint8	r,
		uint8	g,
		uint8	b,
		uint8	a
	)		`[inline]`

void CzScene::setConstantTimeStep ( float step ) [inline]

void CzScene::setDestroyed ( bool destroyed ) [inline]

void CzScene::setExtents	(	int	x,
		int	y,
		int	w,
		int	h
	)		`[inline]`

void CzScene::setLayer ( int layer ) [inline]

void CzScene::setModifiers ( CzModifierManager * mods ) [inline]

void CzScene::setOpacity ( int opacity ) [inline]

void CzScene::setParent ( CzApp * parent ) [inline]

void CzScene::setPhysicsEnabled ( bool enable ) [inline]

bool CzScene::setProperty	(	const char *	property_name,
		const CzString &	data,
		bool	delta
	)

Sets the named property of the scene.

Sets the named property of this scene. The properties value (data) is supplied as a string and will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property.
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:: true if it succeeds, false if property does not exist.

bool CzScene::setProperty	(	unsigned int	property_name,
		const CzString &	data,
		bool	delta
	)		`[virtual]`

Sets the named property of the scene.

Sets the named property of this scene. The properties value (data) is supplied as a string and will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:: true if it succeeds, false if property does not exist.

bool CzScene::setProperty	(	unsigned int	property_name,
		const CzXomlProperty &	data,
		bool	delta
	)		`[virtual]`

Sets the named property of the scene.

Sets the named property of this scene to the supplied property data. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:: true if it succeeds, false if property does not exist.

void CzScene::setRunCount ( int count ) [inline]

void CzScene::setScriptEngine ( const CzString & type )

Sets the scenes script engine type.

When set creates and assigns a script engine too the scene. Currently supported script engine types include:

Lua

Parameters:

[in] type Script engine type.

void CzScene::setTimeline ( CzAnimTimeline * timeline ) [inline]

void CzScene::setType ( int type ) [inline]

void CzScene::setUserPropertyList ( CzUserPropertyList * props ) [inline]

void CzScene::setVirtualTransform	(	int	required_width,
		int	required_height,
		float	angle,
		bool	fix_aspect = `false`,
		bool	lock_width = `false`,
		eCanvasOrigin	canvas_origin = `Origin_Centre`
	)

Sets virtual transform.

Calls through to setVirtualTransform(int required_width, int required_height, float angle, eCanvasFit fit, eCanvasOrigin canvas_origin)

Parameters:

required_width	Width of the required canvas.
required_height	Height of the required canvas.
angle	The angle of the canvas in degrees.
fix_aspect	true to fix aspect ratio.
lock_width	true to lock scaling to screen width.
canvas_origin	The canvas origin.

void CzScene::setVirtualTransform	(	int	required_width,
		int	required_height,
		float	angle,
		eCanvasFit	fit = `Fit_Best`,
		eCanvasOrigin	canvas_origin = `Origin_Centre`
	)

Sets the scenes virtual transform.

Targeting a large selection of different phones, tablets and other devices with a variety of screen sizes and aspect ratios is a bit of a nightmare when it comes to game development. Luckily the CzScene class takes care of this for us. A scene is quite a clever object in that it can render itself to any sized / configuration display using the virtual canvas concept. A virtual canvas is basically our own ideal screen size that we want to render to. The scene will scale and translate int visuals to fit our canvas onto the devices display allowing us to get on with developing our app or game using a static resolution. Lets take a look at the prototype for setting a scenes virtual canvas:

Parameters:

required_width	Width of the required canvas.
required_height	Height of the required canvas.
angle	The angle of the canvas in degrees.
fit	Defines how canvas fits to the screen.
canvas_origin	The canvas origin.

void CzScene::setVisible ( bool visible ) [inline]

void CzScene::Suspend ( CzScene * new_scene )

Suspends this scene.

Parameters:

[in,out] new_scene If non-null, the new scene.

void CzScene::Update ( float dt ) [virtual]

Updates the scene.

Updates the scenes logic, including:

Processing scene OnTick event
Updating scene bindings
Updating scene modifiers
Updating scene programs
Updating physics world
Updating camera
Updating actors
Removing old destroyed actors
Updating scene timeline
Clearing collision lists

This method should be overriden by derived scenes to provide the scene specific logic.

Note that dt is used to scale scene internals that rely on time. This value enables the actor run in an environment where time (the frame rate of the device) can vary allowing animation to keep up without slowing down or speeding up when the frame rate varies.

Parameters:

dt	The number of seconds since the app was last updated

void CzScene::UpdateActorResizing ( ) [protected]

Updates the parents of any actors that have resized themselves.

Causes UI based actors to resize themselves.

Checks all UI based actors in the scene to see if they need their size updating. If so then the UI actor will call its ResizeToContent() method to update its size.

void CzScene::UpdateBindings ( bool force_modified = false ) [protected, virtual]

Update data bindings.

Updates the scenes internal bindings.

Walks the scenes bindings list updating all of its bindings and an attached simple data binding if attached. Passing to true to force_modified will force the bindings to be updated, even if the system does not think the bound variables have not changed.

Parameters:

force_modified true to force an update.

bool CzScene::UpdateFromAnimation ( CzAnimInstance * animation ) [virtual]

Updates scene property from supplied animation.

Updates the scenes property that is specified by the supplied animation. When a timeline animation targets the property of an scene this method will be called by the animation to move the animations frame data into its target property.

    <Timeline name="Anim1" autoplay="true">
        <Animation anim="PosAnim" target="Position">
    </Timeline>

In the above example PosAnim targets the Position property. Internally the animation will call UpdateFromAnimation() passing in itself. UpdateFromAnimation() will examine the target preoperty name of the animation as see that it wants to update "Position".

Parameters:

[in] animation If non-null, the animation.

Returns:: true if it succeeds, false if property does not exist.

Implements IzAnimTarget.

void CzScene::UpdatePhysics ( float dt )

Updates the physics world.

Parameters:

dt	The number of seconds since physics was last updated

CzVec2 CzScene::VirtualToScreen	(	float	virtual_x,
		float	virtual_y,
		bool	ignore_translation = `false`
	)

Returns a screen position frmo a virtual position.

Convetrs scene virtual canvas coordinates to device screen coordinates.

Parameters:

virtual_x	The virtual x coordinate.
virtual_y	The virtual y coordinate.
ignore_translation	true to ignore translation.

Returns:: Screen coordinate.

Member Data Documentation

CzActionsManager* CzScene::ActionsManager [protected]

Manages actions.

CzList<CzActor*> CzScene::Actors [protected]

Collection of scene actors.

bool CzScene::AllowFocus [protected]

If true this scene can receive input events if it is not the current scene.

bool CzScene::AllowSuspend [protected]

If true then this processing of this scene will be suspended when the scene manager changes away from this scene.

CzXomlBindings* CzScene::Bindings [protected]

Manages any attached bindings.

CzBox2dWorld* CzScene::Box2dWorld [protected]

CzCamera* CzScene::Camera [protected]

Current camera.

eCanvasFit CzScene::CanvasFit [protected]

Fit method for scalnig canvas.

eCanvasOrigin CzScene::CanvasOrigin [protected]

Origin type.

CzXomlClassDef * CzScene::ClassDef = NULL [static, protected]

CzIRect CzScene::ClippingArea [protected]

A rectangular area of the virtual screen that this scene will be clipped to.

bool CzScene::ClipStatic [protected]

If ClipStatic is true then camera transform is not applied to clipping rect.

CzActor** CzScene::Collidables [protected]

List of collidable objects built this frame.

CzColour CzScene::Colour [protected]

Colour.

float CzScene::ConstantTimeStep [protected]

If 0 then time step will be calculated from frame rate.

bool CzScene::Destroyed [protected]

A scene is marked asd destroyed when it has been marked for deletion.

const char* CzScene::DockingNames[] [static]

CzEventManager* CzScene::EventsManager [protected]

List of events that the scene handles.

CzIRect CzScene::Extents [protected]

Extents of scenes world.

bool CzScene::IsActive [protected]

Active state of scene.

bool CzScene::IsDragging [protected]

True if user is draggnig their finger on the scene.

bool CzScene::IsVisible [protected]

Visible state of scene.

int CzScene::Layer [protected]

Scenes layer.

int CzScene::MaxCollidables [protected]

Maximum allowed collidables.

int CzScene::MaxLayers [protected]

Maximum visible layers.

CzModifierManager* CzScene::Modifiers [protected]

Class modifiers manager.

int CzScene::NextFreeCollidable [protected]

Points to next free slot in sollidables list pool.

eOrientation CzScene::Orientation [protected]

Current display orientation.

CzIVec2 CzScene::OriginalSize [protected]

Original size of scene.

CzApp* CzScene::Parent [protected]

Parent game controller.

Reimplemented from IzXomlResource.

bool CzScene::PhysicsEnabled [protected]

True if physics is enabled in this scene.

bool CzScene::PrevTouching [protected]

True if user is draggnig their finger on the scene.

CzVec2 CzScene::PrevTouchVel [protected]

Previous touch velocity.

CzProgramManager* CzScene::ProgramManager [protected]

Manages the execution of a collection of programs.

CzList<CzActor*> CzScene::Removals [protected]

CzXomlResourceManager* CzScene::ResourceManager [protected]

Manages all types of resources.

int CzScene::RunCount [protected]

NUmber of times the scene has been updated.

CzIVec2 CzScene::ScreenSize [protected]

Native screen size.

IzScriptEngine* CzScene::ScriptEngine [protected]

Mnaages scene scripts.

CzSpriteManager* CzScene::SpriteManager [protected]

Manages sprites for the whole scene.

bool CzScene::TickEnabled [protected]

true if OnTick event specified

CzAnimTimeline* CzScene::Timeline [protected]

Timeline, controls animation of the scene.

CzAnimTimelinesManager* CzScene::TimelinesManager [protected]

Manages timelines.

CzTimersManager* CzScene::TimersManager [protected]

Manages attached timers.

CzMatrix3 CzScene::Transform [protected]

Scene transform.

CzVec2 CzScene::TransformedClipRect[2] [protected]

Transformed clipping rect for the scene.

int CzScene::Type [protected]

Type of scene.

CzUserPropertyList* CzScene::UserPropertyList [protected]

User properties list.

CzXomlVariableManager* CzScene::VariableManager [protected]

Manages XOML variables.

CzIVec2 CzScene::VirtualSize [protected]

The virtual size is not the actual size of the scene. but a static pretend size that we can use to render to without having to cater for different sized displays.

CzMatrix3 CzScene::VirtualTransform [protected]

Virtual transform is used to scale, translate and rotate scene to fit different display sizes and orientations.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Introduction

Creating a Scene

Scene Properties

Scene Virtual Canvas

Scene Layers and Actor Layering

Current Scene

Suspending and Resuming Scenes

Scene Extents

Scene Clipping

Scene Events

Scene Animation Properties

Scene Modifiable Properties

Scene Rendering

Scene Cameras

Scene Augmentation

Scene Physics

Creating a Custom Scene

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation