iOS Developer Library

Developer

SpriteKit Framework Reference SKTextureAtlas Class Reference

Options
Deployment Target:

On This Page
Language:

SKTextureAtlas

An SKTextureAtlas object is a collection of related texture objects created from a texture atlas stored inside the app bundle. Sprite Kit implicitly loads atlases when a texture image stored inside the atlas is accessed. Use the SKTextureAtlas class when you want to explicitly access a texture atlas’s contents.

Texture atlases can improve memory usage and rendering performance. For example, if you have a scene with sprites drawn with different textures, Sprite Kit performs one drawing pass for each texture. However, if all of the textures were loaded from the same texture atlas, Sprite Kit can render the sprites in a single drawing pass—and use less memory to do so. Whenever you have textures that are always used together, store them in an atlas.

Typically, you create texture atlases using Xcode. Add a folder with the .atlas extension to your project and place the artwork to be included in the atlas inside this folder. Xcode builds a texture atlas from the artwork and adds it to the app bundle. The format for a compiled texture atlas is private and subject to change. For more information about creating texture atlases, see Texture Atlas Help. You can also create a texture atlas at runtime by providing a dictionary that points to the various image files that should be part of the atlas; see the atlasWithDictionary: class method.

To access an atlas directly, call the atlasNamed: class method, passing in the name of the folder (without any filename extension). You can also create an atlas at runtime from a set of images; see the atlasWithDictionary: class method.

Subclassing Notes

This class cannot be subclassed.

Inheritance


Conforms To


Import Statement


Swift

import SpriteKit

Objective-C

@import SpriteKit;

Availability


Available in iOS 7.0 and later.
  • Creates an atlas from data stored in the app bundle.

    Declaration

    Swift

    convenience init!(named name: String)

    Objective-C

    + (instancetype)atlasNamed:(NSString *)name

    Parameters

    name

    The name of the texture atlas, without the .atlas extension.

    Return Value

    A new texture atlas.

    Discussion

    If the texture atlas cannot be found, an exception is thrown.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture atlas object from a set of image files.

    Declaration

    Swift

    convenience init!(dictionary properties: [NSObject : AnyObject])

    Objective-C

    + (instancetype)atlasWithDictionary:(NSDictionary *)properties

    Parameters

    properties

    A dictionary that defines which textures are to be merged into the atlas.

    Return Value

    A new texture atlas.

    Discussion

    Normally, Xcode creates texture atlases at compile time from the image files included in your project. These atlases are compiled and installed inside the app bundle. However, sometimes the assets needed to create a texture atlas are not available at compile time. For example, those assets might be procedurally generated or downloaded from the network. However, you still want the benefit of texture atlases to reduce the number of state changes required in the hardware. You can use this method to generate an atlas at runtime. This is a potentially expensive operation best performed when your game loop is not running.

    The keys in the dictionary represent the names of the individual textures. The associated object for each key can be:

    • An NSString object that contains a file system path to a file that contains the texture

    • An NSURL object that contains a file system path to a file that contains the texture

    • A UIImage object

    • An NSImage object

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • Creates a texture from data stored in the texture atlas.

    Declaration

    Swift

    func textureNamed(_ name: String) -> SKTexture!

    Objective-C

    - (SKTexture *)textureNamed:(NSString *)name

    Parameters

    name

    The name of a texture stored in the atlas.

    Return Value

    The Sprite Kit texture associated with the name. If the specified image does not exist in the atlas, Sprite Kit returns a placeholder texture image.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

    See Also

    textureNames

  • Load the atlas’s textures into memory, calling a completion handler after the task completes.

    Declaration

    Swift

    func preloadWithCompletionHandler(_ completionHandler: () -> Void)

    Objective-C

    - (void)preloadWithCompletionHandler:(void (^)(void))completionHandler

    Parameters

    completionHandler

    A block called after the texture atlas is loaded.

    Discussion

    Sprite Kit creates a background task that loads the texture data from the atlas. Then, Sprite Kit returns control to your game. After the texture atlas is loaded, your completion handler is called.

    If you need to preload multiple texture atlases at once, use the preloadTextureAtlases:withCompletionHandler: method instead.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Loads the textures of multiple atlases into memory, calling a completion handler after the task completes.

    Declaration

    Swift

    class func preloadTextureAtlases(_ textureAtlases: [AnyObject]!, withCompletionHandler completionHandler: (() -> Void)!)

    Objective-C

    + (void)preloadTextureAtlases:(NSArray *)textureAtlases withCompletionHandler:(void (^)(void))completionHandler

    Parameters

    textureAtlases

    An array of SKTextureAtlas objects.

    completionHandler

    A block called after all of the texture atlases are loaded.

    Discussion

    Sprite Kit creates a background task that loads the texture data from all of the specified atlases. Then, Sprite Kit returns control to your game. After the atlases are loaded, your completion handler is called.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The names of the texture images stored in the atlas. (read-only)

    Declaration

    Swift

    var textureNames: [AnyObject] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *textureNames

    Discussion

    The property holds an array of NSString objects. Each string is the name of a texture stored in the atlas. The count of the array is the number of textures stored in the atlas.

    If the atlas is not currently loaded into memory, this method forces it to be loaded from the app bundle. Your game blocks until the atlas is loaded.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.