Inherits from NSObject
Declared in PXTextureAtlas.h
PXTextureAtlas.m

Overview

Abstracts the concept of a texture atlas (several images arranged into one larger image) into a simple object containing a ‘frame’ for each sub-image.

The PXTextureAtlas class supports atlases backed by one or multiple images.

Frames within the texture atlas are represented by the PXAtlasFrame class. Each frame contains information about a sub image within the atlas, such as its position within the master image, angular offset, anchor position, etc.

CREATION

A Texture atlas can be created manually, requiring the user to specify the master image and a PXAtlasFrame object for each subimage within. Alternatively a texture atlas definition file can be loaded and used to create the texture atlas. Currently the following texture atlas format are supported:

  • Zwoptex (.plist)
  • TexturePacker (.json)

USAGE

Once a texture atlas has been created (either manually or with an external file), using it is quite simple. To quickly create a PXTexture containing a specific subimage, use the textureForFrame: method, specifying the name of the frame to use.

To set a specific sub-image in the atlas to a PXTexture that already exists use the setFrame:toTexture: method instead.

If more control is needed, the actual PXAtlasFrame object can be grabbed with the frameWithName: method and inspected as necessary.

Tasks

Other Methods

  •   textureDatas

    A list of all the PXTextureData objects associated with the texture atlas. The list is a collection of all the unique texture datas references within the frames of the texture atlas.

         property
  •   allNames

    A list of the names (NSString objects) of all the frames within the texture atlas.

         property
  •   allFrames

    A list of all the frames (PXTextureAtlas objects) within the texture atlas.

         property
  • – initWithContentsOfFile:

    Loads the texture atlas definition file specified by path and initializes the texture atlas with it.
  • – initWithContentsOfFile:modifier:

    Loads the texture atlas definition file specified by path and initializes the texture atlas with it. Also allows to specify an optional PXTextureModifier, which will be applied to the entire loaded texture atlas image.
  • – initWithData:

    Initializes and populates the texture atlas with data representing a texture atlas definition file.
  • – initWithData:modifier:

    Initializes and populates the texture atlas with data representing a texture atlas definition file. Also allows for an optional PXTextureModifier.
  • – addFrame:withName:

    Adds the given frame to the atlas. Useful when creating a custom PXTextureAtlas object (as opposed to loading one from file).
  • – removeFrame:

    Removes the frame associated with the given name. If a frame with that name doesn’t exist, nothing happens.
  • – frameWithName:

    Returns the frame associated with the given name. returns nil if the given name isn’t associated with any frame.
  • – addFrameWithName:clipRect:textureData:anchorX:anchorY:

    A utility method for quickly adding a frame without the need to create and manage a PXAtlasFrame object.
  • – textureForFrame:

    A utility method for quickly creating a PXTexture object representing the frame with the given name.
  • – setFrame:toTexture:

    A utility method for quickly modifying the given PXTexture object to represent the frame with the given name.
  • + textureAtlas

    A utility method for quickly creating an empty texture atlas.
  • + textureAtlasWithContentsOfFile:modifier:

    A utility method for quickly creating a texture atlas with the contents of an atlas definition file on the hard drive.

Other Methods

  • – init

    Initializes an empty texture atlas. The texture atlas can be populated with frames using the addFrame:withName: and removeFrame: methods.

Utils Methods

Properties

allFrames

A list of all the frames (PXTextureAtlas objects) within the texture atlas.

@property (nonatomic, readonly) NSArray *allFrames

Declared In

PXTextureAtlas.h

allNames

A list of the names (NSString objects) of all the frames within the texture atlas.

@property (nonatomic, readonly) NSArray *allNames

Declared In

PXTextureAtlas.h

textureDatas

A list of all the PXTextureData objects associated with the texture atlas. The list is a collection of all the unique texture datas references within the frames of the texture atlas.

@property (nonatomic, readonly) NSArray *textureDatas

Declared In

PXTextureAtlas.h

Class Methods

textureAtlas

A utility method for quickly creating an empty texture atlas.

+ (PXTextureAtlas *)textureAtlas

Return Value

An empty, autoreleased PXTextureAtlas object.

Declared In

PXTextureAtlas.m

textureAtlasWithContentsOfFile:modifier:

A utility method for quickly creating a texture atlas with the contents of an atlas definition file on the hard drive.

+ (PXTextureAtlas *)textureAtlasWithContentsOfFile:(NSString *)path modifier:(id<PXTextureModifier>)modifier

Return Value

An autoreleased PXTextureAtlas object.

Declared In

PXTextureAtlas.m

Instance Methods

addFrame:withName:

Adds the given frame to the atlas. Useful when creating a custom PXTextureAtlas object (as opposed to loading one from file).

- (void)addFrame:(PXAtlasFrame *)frame withName:(NSString *)name

Parameters

frame

The frame to add to the atlas. The frame object is retained by the atlas and can be safely released by the caller after this method is called.

name

The name to associate the given frame with. This is the name used to dereference the frame later on. If the name specified is already associated with a different frame, that frame is removed and is replaced by the one passed in.

See Also

Declared In

PXTextureAtlas.m

addFrameWithName:clipRect:textureData:anchorX:anchorY:

A utility method for quickly adding a frame without the need to create and manage a PXAtlasFrame object.

- (PXAtlasFrame *)addFrameWithName:(NSString *)name clipRect:(PXClipRect *)clipRect textureData:(PXTextureData *)textureData anchorX:(float)anchorX anchorY:(float)anchorY

Parameters

name

The name to associate the frame with.

clipRect

A PXClipRect object representing the location of the sub-image represented by this frame, within the atlas image.

textureData

A PXTextureData object representing the master atlas image.

anchorX

The anchorX value (in percent) to set for the created frame.

anchorY

The anchorY value (in percent) to set for the created frame.

See Also

Declared In

PXTextureAtlas.m

frameWithName:

Returns the frame associated with the given name. returns nil if the given name isn’t associated with any frame.

- (PXAtlasFrame *)frameWithName:(NSString *)name

Declared In

PXTextureAtlas.m

framesWithNames:

Returns the frames with the given names. If a frame doesn’t exist for any of the given names, those names are simply ignored.

- (NSArray *)framesWithNames:(NSArray *)names

Parameters

names

An NSArray object containing the names of the frames requested.

Return Value

An NSArray containing the frame objects matching the given names. The frames in the returned array are in the same order as the names provided.

Declared In

PXTextureAtlas.m

framesWithPattern:

Finds and returns all frames whose names match the given regex pattern.

- (NSArray *)framesWithPattern:(PXRegexPattern *)pattern

Parameters

pattern

The regex pattern to match against the names of all frames in this atlas.

Return Value

An NSArray containing all frames whithin the atlas whose names match the given regex pattern.

Declared In

PXTextureAtlas.m

init

Initializes an empty texture atlas. The texture atlas can be populated with frames using the addFrame:withName: and removeFrame: methods.

- (id)init

See Also

Declared In

PXTextureAtlas.m

initWithContentsOfFile:

Loads the texture atlas definition file specified by path and initializes the texture atlas with it.

- (id)initWithContentsOfFile:(NSString *)path

Parameters

path

An absolute path or one relative to the resource bundle, representing the texture atlas definition file to load.

See Also

Declared In

PXTextureAtlas.m

initWithContentsOfFile:modifier:

Loads the texture atlas definition file specified by path and initializes the texture atlas with it. Also allows to specify an optional PXTextureModifier, which will be applied to the entire loaded texture atlas image.

- (id)initWithContentsOfFile:(NSString *)path modifier:(id<PXTextureModifier>)modifier

Parameters

path

An absolute path or one relative to the resource bundle, representing the texture atlas definition file to load.

modifier

An optional modifier, to be applied to the loaded atlas image. Default value is nil

Declared In

PXTextureAtlas.m

initWithData:

Initializes and populates the texture atlas with data representing a texture atlas definition file.

- (id)initWithData:(NSData *)data

Parameters

data

An NSDate object representing the bytes of a texture definition file.

Declared In

PXTextureAtlas.m

initWithData:modifier:

Initializes and populates the texture atlas with data representing a texture atlas definition file. Also allows for an optional PXTextureModifier.

- (id)initWithData:(NSData *)data modifier:(id<PXTextureModifier>)modifier

Parameters

data

An NSDate object representing the bytes of a texture definition file.

modifier

An optional PXTextureModifier to be applied to the loaded atlas texture data.

Declared In

PXTextureAtlas.m

removeFrame:

Removes the frame associated with the given name. If a frame with that name doesn’t exist, nothing happens.

- (void)removeFrame:(NSString *)name

Discussion

Note: Once a frame is removed from the texture atlas, the atlas’s retain on it is released. If you need to keep a reference to the frame you’re about to remove, it’s best to get the reference before calling this method via the frameWithName: method.

Declared In

PXTextureAtlas.m

sequentialFramesWithPrefix:suffix:inRange:

Finds all frames with the given prefix and suffix in their name, assuming the value between them is numerical.

- (NSArray *)sequentialFramesWithPrefix:(NSString *)prefix suffix:(NSString *)suffix inRange:(NSRange)inRange

Parameters

prefix

The string to the left of the numerical value in the frame’s name.

suffix

The string to the right of the numerical value in the frame’s name

range

The range of numerical values to include in the returned list. If you’d like all numerical values to be considered just pass {NSNotFound, 0} for this parameter.

Return Value

An NSArray containing PXAtlasFrame objects matching the prefix and suffix provided. The list is sorted according to the numerical value between the prefix and suffix. If no frame’s name matches the pattern, an empty list is returned.

Discussion

The returned list of frames is sorted according to the numerical value between the prefix and suffix. If the numerical value has any leading zeros they are safely ignored; only the underlying integer value is used when sorting the list. Note that this method assumes the numerical value is always an integer.

Declared In

PXTextureAtlas.m

setFrame:toTexture:

A utility method for quickly modifying the given PXTexture object to represent the frame with the given name.

- (void)setFrame:(NSString *)name toTexture:(PXTexture *)texture

Parameters

name

The name of the frame to use. If a frame isn’t associated with that name, nothing happens.

texture

A PXTexture object who’s contents will be modified to represent the given frame.

Declared In

PXTextureAtlas.m

textureForFrame:

A utility method for quickly creating a PXTexture object representing the frame with the given name.

- (PXTexture *)textureForFrame:(NSString *)name

Parameters

name

The name of the frame to use.

Return Value

An autoreleased PXTexture object representing the frame associated with the given name. If name is nil, or isn’t associated with any frame in the atlas, nil is returned.

Declared In

PXTextureAtlas.m