Inherits from SPEventDispatcher : NSObject
Declared in SPDisplayObject.h

Overview

The SPDisplayObject class is the base class for all objects that are rendered on the screen.

In Sparrow, all displayable objects are organized in a display tree. Only objects that are part of the display tree will be displayed (rendered).

The display tree consists of leaf nodes (SPImage, SPQuad) that will be rendered directly to the screen, and of container nodes (subclasses of SPDisplayObjectContainer, like SPSprite). A container is simply a display object that has child nodes - which can, again, be either leaf nodes or other containers.

A display object has properties that define its position in relation to its parent (x, y), as well as its rotation, skewing and scaling factors (scaleX, scaleY). Use the alpha and visible properties to make an object translucent or invisible.

Every display object may be the target of touch events. If you don’t want an object to be touchable, you can disable the touchable property. When it’s disabled, neither the object nor its children will receive any more touch events.

Points vs. Pixels

All sizes and distances are measured in points. What this means in pixels depends on the contentScaleFactor of the device. On a low resolution device (iPhone 3GS / iPad 1+2), one point corresponds to one pixel. On devices with a retina display, one point may be 2 pixels.

Transforming coordinates

Within the display tree, each object has its own local coordinate system. If you rotate a container, you rotate that coordinate system - and thus all the children of the container.

Sometimes you need to know where a certain point lies relative to another coordinate system. That’s the purpose of the method transformationMatrixToSpace:. It will create a matrix that represents the transformation of a point in one coordinate system to another.

Subclassing SPDisplayObject

As SPDisplayObject is an abstract class, you can’t instantiate it directly, but have to use one of its subclasses instead. There are already a lot of them available, and most of the time they will suffice.

However, you can create custom display objects as well. That’s especially useful when you want to create an object with a custom render function.

You will need to implement the following methods when you subclass SPDisplayObject:

- (void)render:(SPRenderSupport *)support;
- (SPRectangle *)boundsInSpace:(SPDisplayObject *)targetSpace;

Have a look at SPQuad for a sample implementation of those methods.

Tasks

Methods

Properties

  •   x

    The x coordinate of the object relative to the local coordinates of the parent.

         property
  •   y

    The y coordinate of the object relative to the local coordinates of the parent.

         property
  •   pivotX

    The x coordinate of the object’s origin in its own coordinate space (default: 0).

         property
  •   pivotY

    The y coordinate of the object’s origin in its own coordinate space (default: 0).

         property
  •   scale

    The scale factor. “1” means no scale, a negative value inverts the object. Note: Accessing this property will always return scaleX, even if scaleX and scaleY are not equal.

         property
  •   scaleX

    The horizontal scale factor. “1” means no scale, negative values flip the object.

         property
  •   scaleY

    The vertical scale factor. “1” means no scale, negative values flip the object.

         property
  •   skewX

    The horizontal skew angle in radians.

         property
  •   skewY

    The vertical skew angle in radians.

         property
  •   width

    The width of the object in points.

         property
  •   height

    The height of the object in points.

         property
  •   rotation

    The rotation of the object in radians. (In Sparrow, all angles are measured in radians.)

         property
  •   alpha

    The opacity of the object. 0 = transparent, 1 = opaque.

         property
  •   visible

    The visibility of the object. An invisible object will be untouchable.

         property
  •   touchable

    Indicates if this object (and its children) will receive touch events.

         property
  •   bounds

    The bounds of the object relative to the local coordinates of the parent.

         property
  •   parent

    The display object container that contains this display object.

         property
  •   root

    The root object the display object is connected to (i.e. an instance of the class that was passed to [SPViewController startWithRoot:]), or nil if the object is not connected to it.

         property
  •   stage

    The stage the display object is connected to, or nil if it is not connected to a stage.

         property
  •   base

    The topmost object in the display tree the object is part of.

         property
  •   transformationMatrix

    The transformation matrix of the object relative to its parent.

         property
  •   name

    The name of the display object (default: nil). Used by childByName: of display object containers.

         property
  •   filter

    The filter that is attached to the display object. Beware that you should NOT use the same filter on more than one object (for performance reasons).

         property
  •   blendMode

    The blend mode determines how the object is blended with the objects underneath. Default: AUTO

         property
  •   hasVisibleArea

    Indicates if an object occupies any visible area. (Which is the case when its alpha, scaleX and scaleY values are not zero, and its visible property is enabled.)

         property
  •   physicsBody

    The physics body associated with the display object. Sparrow does not provide physics on its own, but this property may be used by any physics library to link an object to its physical body.

         property

Properties

alpha

The opacity of the object. 0 = transparent, 1 = opaque.

@property (nonatomic, assign) float alpha

Discussion

The opacity of the object. 0 = transparent, 1 = opaque.

Declared In

SPDisplayObject.h

base

The topmost object in the display tree the object is part of.

@property (weak, nonatomic, readonly) SPDisplayObject *base

Discussion

The topmost object in the display tree the object is part of.

Declared In

SPDisplayObject.h

blendMode

The blend mode determines how the object is blended with the objects underneath. Default: AUTO

@property (nonatomic, assign) uint blendMode

Discussion

The blend mode determines how the object is blended with the objects underneath. Default: AUTO

Declared In

SPDisplayObject.h

bounds

The bounds of the object relative to the local coordinates of the parent.

@property (weak, nonatomic, readonly) SPRectangle *bounds

Discussion

The bounds of the object relative to the local coordinates of the parent.

Declared In

SPDisplayObject.h

filter

The filter that is attached to the display object. Beware that you should NOT use the same filter on more than one object (for performance reasons).

@property (nonatomic, strong) SPFragmentFilter *filter

Discussion

The filter that is attached to the display object. Beware that you should NOT use the same filter on more than one object (for performance reasons).

Declared In

SPDisplayObject.h

hasVisibleArea

Indicates if an object occupies any visible area. (Which is the case when its alpha, scaleX and scaleY values are not zero, and its visible property is enabled.)

@property (nonatomic, readonly) BOOL hasVisibleArea

Discussion

Indicates if an object occupies any visible area. (Which is the case when its alpha, scaleX and scaleY values are not zero, and its visible property is enabled.)

Declared In

SPDisplayObject.h

height

The height of the object in points.

@property (nonatomic, assign) float height

Discussion

The height of the object in points.

Declared In

SPDisplayObject.h

name

The name of the display object (default: nil). Used by childByName: of display object containers.

@property (nonatomic, copy) NSString *name

Discussion

The name of the display object (default: nil). Used by childByName: of display object containers.

Declared In

SPDisplayObject.h

parent

The display object container that contains this display object.

@property (weak, nonatomic, readonly) SPDisplayObjectContainer *parent

Discussion

The display object container that contains this display object.

Declared In

SPDisplayObject.h

physicsBody

The physics body associated with the display object. Sparrow does not provide physics on its own, but this property may be used by any physics library to link an object to its physical body.

@property (nonatomic, strong) SP_PHYSICS_CLASS *physicsBody

Discussion

The physics body associated with the display object. Sparrow does not provide physics on its own, but this property may be used by any physics library to link an object to its physical body.

Declared In

SPDisplayObject.h

pivotX

The x coordinate of the object’s origin in its own coordinate space (default: 0).

@property (nonatomic, assign) float pivotX

Discussion

The x coordinate of the object’s origin in its own coordinate space (default: 0).

Declared In

SPDisplayObject.h

pivotY

The y coordinate of the object’s origin in its own coordinate space (default: 0).

@property (nonatomic, assign) float pivotY

Discussion

The y coordinate of the object’s origin in its own coordinate space (default: 0).

Declared In

SPDisplayObject.h

root

The root object the display object is connected to (i.e. an instance of the class that was passed to [SPViewController startWithRoot:]), or nil if the object is not connected to it.

@property (weak, nonatomic, readonly) SPDisplayObject *root

Discussion

The root object the display object is connected to (i.e. an instance of the class that was passed to [SPViewController startWithRoot:]), or nil if the object is not connected to it.

Declared In

SPDisplayObject.h

rotation

The rotation of the object in radians. (In Sparrow, all angles are measured in radians.)

@property (nonatomic, assign) float rotation

Discussion

The rotation of the object in radians. (In Sparrow, all angles are measured in radians.)

Declared In

SPDisplayObject.h

scale

The scale factor. “1” means no scale, a negative value inverts the object. Note: Accessing this property will always return scaleX, even if scaleX and scaleY are not equal.

@property (nonatomic, assign) float scale

Discussion

The scale factor. “1” means no scale, a negative value inverts the object. Note: Accessing this property will always return scaleX, even if scaleX and scaleY are not equal.

Declared In

SPDisplayObject.h

scaleX

The horizontal scale factor. “1” means no scale, negative values flip the object.

@property (nonatomic, assign) float scaleX

Discussion

The horizontal scale factor. “1” means no scale, negative values flip the object.

Declared In

SPDisplayObject.h

scaleY

The vertical scale factor. “1” means no scale, negative values flip the object.

@property (nonatomic, assign) float scaleY

Discussion

The vertical scale factor. “1” means no scale, negative values flip the object.

Declared In

SPDisplayObject.h

skewX

The horizontal skew angle in radians.

@property (nonatomic, assign) float skewX

Discussion

The horizontal skew angle in radians.

Declared In

SPDisplayObject.h

skewY

The vertical skew angle in radians.

@property (nonatomic, assign) float skewY

Discussion

The vertical skew angle in radians.

Declared In

SPDisplayObject.h

stage

The stage the display object is connected to, or nil if it is not connected to a stage.

@property (weak, nonatomic, readonly) SPStage *stage

Discussion

The stage the display object is connected to, or nil if it is not connected to a stage.

Declared In

SPDisplayObject.h

touchable

Indicates if this object (and its children) will receive touch events.

@property (nonatomic, assign) BOOL touchable

Discussion

Indicates if this object (and its children) will receive touch events.

Declared In

SPDisplayObject.h

transformationMatrix

The transformation matrix of the object relative to its parent.

@property (nonatomic, copy) SPMatrix *transformationMatrix

Return Value

CAUTION: not a copy, but the actual object!

Discussion

The transformation matrix of the object relative to its parent.

Declared In

SPDisplayObject.h

visible

The visibility of the object. An invisible object will be untouchable.

@property (nonatomic, assign) BOOL visible

Discussion

The visibility of the object. An invisible object will be untouchable.

Declared In

SPDisplayObject.h

width

The width of the object in points.

@property (nonatomic, assign) float width

Discussion

The width of the object in points.

Declared In

SPDisplayObject.h

x

The x coordinate of the object relative to the local coordinates of the parent.

@property (nonatomic, assign) float x

Discussion

The x coordinate of the object relative to the local coordinates of the parent.

Declared In

SPDisplayObject.h

y

The y coordinate of the object relative to the local coordinates of the parent.

@property (nonatomic, assign) float y

Discussion

The y coordinate of the object relative to the local coordinates of the parent.

Declared In

SPDisplayObject.h

Instance Methods

alignPivotToCenter

Moves the pivot point to the center of the object.

- (void)alignPivotToCenter

Discussion

Moves the pivot point to the center of the object.

Declared In

SPDisplayObject.h

alignPivotX:pivotY:

Moves the pivot point to a certain position within the local coordinate system of the object.

- (void)alignPivotX:(SPHAlign)hAlign pivotY:(SPVAlign)vAlign

Discussion

Moves the pivot point to a certain position within the local coordinate system of the object.

Declared In

SPDisplayObject.h

boundsInSpace:

Returns a rectangle that completely encloses the object as it appears in another coordinate system.

- (SPRectangle *)boundsInSpace:(SPDisplayObject *)targetSpace

Discussion

Returns a rectangle that completely encloses the object as it appears in another coordinate system.

Declared In

SPDisplayObject.h

broadcastEvent:

Dispatches an event on all children (recursively). The event must not bubble. */

- (void)broadcastEvent:(SPEvent *)event

Discussion

Dispatches an event on all children (recursively). The event must not bubble. */

Declared In

SPDisplayObject.h

broadcastEventWithType:

Creates an event and dispatches it on all children (recursively). */

- (void)broadcastEventWithType:(NSString *)type

Discussion

Creates an event and dispatches it on all children (recursively). */

Declared In

SPDisplayObject.h

globalToLocal:

Transforms a point from global (stage) coordinates to the local coordinate system.

- (SPPoint *)globalToLocal:(SPPoint *)globalPoint

Discussion

Transforms a point from global (stage) coordinates to the local coordinate system.

Declared In

SPDisplayObject.h

hitTestPoint:

Returns the object that is found topmost on a point in local coordinates, or nil if the test fails.

- (SPDisplayObject *)hitTestPoint:(SPPoint *)localPoint

Discussion

Returns the object that is found topmost on a point in local coordinates, or nil if the test fails.

Declared In

SPDisplayObject.h

localToGlobal:

Transforms a point from the local coordinate system to global (stage) coordinates.

- (SPPoint *)localToGlobal:(SPPoint *)localPoint

Discussion

Transforms a point from the local coordinate system to global (stage) coordinates.

Declared In

SPDisplayObject.h

removeFromParent

Removes the object from its parent, if it has one.

- (void)removeFromParent

Discussion

Removes the object from its parent, if it has one.

Declared In

SPDisplayObject.h

render:

Renders the display object with the help of a support object.

- (void)render:(SPRenderSupport *)support

Discussion

Renders the display object with the help of a support object.

Declared In

SPDisplayObject.h

transformationMatrixToSpace:

Creates a matrix that represents the transformation from the local coordinate system to another.

- (SPMatrix *)transformationMatrixToSpace:(SPDisplayObject *)targetSpace

Discussion

Creates a matrix that represents the transformation from the local coordinate system to another.

Declared In

SPDisplayObject.h