Inherits from PXDisplayObjectContainer : PXInteractiveObject : PXDisplayObject : PXEventDispatcher : NSObject
Declared in PXStage.h
PXStage.m

Overview

A special display object that represents the entire drawing surface of the Pixelwave engine and contains several global properties such as the screen size and orientation.

Display objects should never be added directly to the stage. instead they should be added to the root display object.

An instace of the PXStage class is automatically created when the display list is created by a PXView object.

The PXStage class should never be instantiated by the user. To access the global stage object, the [PXDisplayObject stage] property may be read on any display object one the main display list. Alternatively you can use the [PXStage mainStage] method.

Tasks

  •   stageWidth

    The width, in points, of the stage.

         property
  •   stageHeight

    The height, in points, of the stage.

         property
  •   orientation

    The orientation of the stage. This value may be changed at any time.

         property
  •   autoOrients

    If YES then the stage automatically rotates to the orientations acceptable It will send out a #PXStageOrientation with the type PXStageOrientationEvent_OrientationChanging. If that event is canceled (using preventDefault) then the orientation will not take affect. If the orientation is accepted then a PXStageOrientationEvent_OrientationChange will be sent.

         property
  •   defaultCaptureTouchesValue

    The value the captureTouches property of a PXInteractiveObject instance should be set to when initialized.

         property
  •   backgroundColor

    The color with which to clear the stage every frame. This values is used if clearScreen is set to YES.

         property
  •   clearScreen

    Whether the screen will be cleared before each draw. This option is set to YES by default, but may be set to NO as an optimization.

         property
  •   dispatchesDisplayListEvents

    Describes whether display list modification events should be dispatched when a PXDisplayObject is added or removed from a display list.

         property
  •   frameRate

    The frame rate at which enterFrame events will be dispatched. 0 < renderFrameRate <= frameRate <= 60. This is due to the iPhone’s screen refresh rate being 60hz.

         property
  •   renderFrameRate

    The frame rate at which the contents of the stage will be rendered to the screen. 0 < renderFrameRate <= frameRate <= 60. This is due to the iPhone’s screen refresh rate being 60hz.

         property
  •   playing

    Defines whether or not the engine is currently running. To pause the engine set this property to code>false. Set it to true to resume normal operations.

         property
  •   contentScaleFactor

    The pixel scale factor.

         property
  •   nativeView

    The PXView instance with which the stage is associated

         property
  • – invalidate

    Signals Pixelwave to dispatch a render event to alert display objects the next time a frame is about to be rendered. After the invalidate method is called, before the rendering phase is about to start, but after all enterFrame events have been fired, a render event is dispatched.
  • + mainStage

    A reference to the main stage associated with the Pixelwave engine.

Properties

autoOrients

If YES then the stage automatically rotates to the orientations acceptable It will send out a #PXStageOrientation with the type PXStageOrientationEvent_OrientationChanging. If that event is canceled (using preventDefault) then the orientation will not take affect. If the orientation is accepted then a PXStageOrientationEvent_OrientationChange will be sent.

@property (nonatomic, assign) BOOL autoOrients

Discussion

Default: NO

Declared In

PXStage.h

backgroundColor

The color with which to clear the stage every frame. This values is used if clearScreen is set to YES.

@property (nonatomic, assign) unsigned backgroundColor

Discussion

Represented as a hexadecimal number with the format: RRGGBB

Example: The following examples set the stage’s background color to red.

stage.backgroundColor = 0xFF0000;

Declared In

PXStage.h

clearScreen

Whether the screen will be cleared before each draw. This option is set to YES by default, but may be set to NO as an optimization.

@property (nonatomic) BOOL clearScreen

Discussion

Default: YES

Declared In

PXStage.h

contentScaleFactor

The pixel scale factor.

@property (nonatomic, readonly) float contentScaleFactor

Declared In

PXStage.h

defaultCaptureTouchesValue

The value the captureTouches property of a PXInteractiveObject instance should be set to when initialized.

@property (nonatomic, assign) BOOL defaultCaptureTouchesValue

Discussion

Default: YES

Declared In

PXStage.h

dispatchesDisplayListEvents

Describes whether display list modification events should be dispatched when a PXDisplayObject is added or removed from a display list.

@property (nonatomic) BOOL dispatchesDisplayListEvents

Discussion

If set to YES, the following display list modification events may be dispatched:

  • added – When a display object is added to a display list.
  • addedToStage – When a display object or any of its ancestors are added to the main display list.
  • removed – When a display object is removed from the display list.
  • removedFromStage – When a display object or any of its ancestors are removed from the main display list.

The value of this property may be changed at any time and has an immediate effect.

This option is set to YES by default, but may be set to NO to avoid the overhead involved with dispatching display list modification events.

Declared In

PXStage.h

frameRate

The frame rate at which enterFrame events will be dispatched. 0 < renderFrameRate <= frameRate <= 60. This is due to the iPhone’s screen refresh rate being 60hz.

@property (nonatomic) float frameRate

Declared In

PXStage.h

nativeView

The PXView instance with which the stage is associated

@property (nonatomic, readonly) PXView *nativeView

Declared In

PXStage.h

orientation

The orientation of the stage. This value may be changed at any time.

@property (nonatomic, assign) PXStageOrientation orientation

Discussion

Must be one of the following:

–PXStageOrientation_Portrait –PXStageOrientation_PortraitUpsideDown –PXStageOrientation_LandscapeLeft –PXStageOrientation_LandscapeRight

Declared In

PXStage.h

playing

Defines whether or not the engine is currently running. To pause the engine set this property to code>false. Set it to true to resume normal operations.

@property (nonatomic) BOOL playing

Discussion

Important note: The engine will not dispatch any events when not playing. These include the ENTER_FRAME event and touch related events.

Declared In

PXStage.h

renderFrameRate

The frame rate at which the contents of the stage will be rendered to the screen. 0 < renderFrameRate <= frameRate <= 60. This is due to the iPhone’s screen refresh rate being 60hz.

@property (nonatomic) float renderFrameRate

Declared In

PXStage.h

stageHeight

The height, in points, of the stage.

@property (nonatomic, readonly) int stageHeight

Declared In

PXStage.h

stageWidth

The width, in points, of the stage.

@property (nonatomic, readonly) int stageWidth

Declared In

PXStage.h

Class Methods

mainStage

A reference to the main stage associated with the Pixelwave engine.

+ (PXStage *)mainStage

Declared In

PXStage.h

Instance Methods

invalidate

Signals Pixelwave to dispatch a render event to alert display objects the next time a frame is about to be rendered. After the invalidate method is called, before the rendering phase is about to start, but after all enterFrame events have been fired, a render event is dispatched.

- (void)invalidate

Discussion

this method must be called every time you need a render event to be dispatched.

The render event lets you make changes to the display list right before the rendering phase. This allows to write more optimized code which only updates the display list when it is absolutely necessary.

Declared In

PXStage.m