iOS Developer Library

Developer

SpriteKit Framework Reference SKTexture Class Reference

Options
Deployment Target:

On This Page
Language:

SKTexture

An SKTexture object is an image that can be applied to SKSpriteNode and SKShapeNode objects or particles created by an SKEmitterNode object. A texture object manages the texture data and graphics resources that are needed to render the image.

Most texture objects are created from source images stored in your app bundle—your game’s artwork. Once created, a texture object’s contents are immutable. Multiple sprites can share the same texture object, sharing a single resource.

Use the textureWithImageNamed: method to create the SKTexture object. When the texture object is initialized using an image file, Sprite Kit must perform two steps before it can use the texture to render sprites. First, it must load the texture data from the file. Second, it must prepare the texture data to be used by the graphics hardware. Both of these steps can be expensive compared to other Sprite Kit operations. In particular, loading a texture from a file is very expensive. Sprite Kit defers loading and preparing the texture as long as possible and also provides methods you can use to control these steps.

The texture data is loaded when:

  • The size method on the texture object is called.

  • Another method is called that requires the texture’s size, such as creating a new SKSpriteNode object that uses the texture object.

  • One of the preload methods is called (See Preloading the Texture Data.)

The texture data is prepared for rendering when:

  • A sprite or particle that uses the texture is part of a node tree that is being rendered.

Once the SKTexture object is ready for rendering, it stays ready until all strong references to the texture object are removed.

Texture objects can be created from data generated at runtime. For example, you can create the texture from a Quartz 2D image, from raw pixel data, or by applying a Core Image filter to an existing texture. You can also call the textureFromNode: method to render a node tree into a texture. None of these textures must be loaded because their data is already in memory when the texture is created. However, the texture must still be prepared by Sprite Kit before it can be used for rendering.

If you have textures that must be updated at runtime, see the SKMutableTexture class.

Managing Texture Memory

Texture objects can consume a lot of memory, depending on the size of your source data. And often, the memory available to prepared textures is limited by the hardware, because the textures need to be loaded into VRAM. So, most games must carefully manage the memory used by textures. Consider the following tips when creating your game:

  • Access a texture object only when needed and dispose of the object when you are confident that it is no longer needed by your game. This frees the memory and makes it available to other texture objects.

  • Avoid loading too many textures in a single pass through the rendering loop. If you do, Sprite Kit may skip one or more frames to finish loading the texture data. Instead, preload your content before starting your game.

  • If you frequently use the same textures at the same time to render your sprites, do not load each texture from a separate image file. Instead, group the texture images logically into one or more texture atlases. Using a texture atlas reduces the total amount of memory required to load the texture and can also reduce the number of drawing passes required to render the scene.

For a longer discussion of texture management, see Working with Sprites.

Normal Map Textures

A normal map texture is similar to an image texture, but instead of holding image data to be displayed onscreen, every texel represents a normal vector. Normal map textures are used to simulate 3D lighting (see the normalTexture property) or used to generate velocity values (see the SKVelocityFieldNode class).

You can create normal maps in two different ways. First, you can take an existing image map and use it to generate a normal map. Sprite Kit filters the color data in the texture and then uses it to generate a map based on pixel contrast. Alternatively, you can load a regular image file but treat it as a normal map. To do this, provide a texture with 32-bit RGBx pixel data. Each component’s 8-bit integer value is mapped to a floating point number between the values of -1.0 and 1.0. Use a 0 to represent -1.0f, a value of 127 to represent 0.0, and a value of 255 to represent +1.0.

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.
  • Create a new texture object from an image file stored in the app bundle.

    Declaration

    Swift

    convenience init!(imageNamed name: String)

    Objective-C

    + (instancetype)textureWithImageNamed:(NSString *)name

    Parameters

    name

    The name of the image file.

    Return Value

    A new texture object.

    Discussion

    The new texture object is initialized with the name of the image file and then control returns immediately to your game. Sprite Kit loads and prepares the texture data when it is needed by your game.

    When loading the texture data, Sprite Kit searches the app bundle for an image file with the specified filename. If a matching image file cannot be found, Sprite Kit searches for the texture in any texture atlases stored in the app bundle. If the specified image does not exist anywhere in the bundle, Sprite Kit creates a placeholder texture image.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Create a new texture object from an image object.

    Declaration

    Swift

    convenience init(image image: UIImage)

    Objective-C

    + (instancetype)textureWithImage:(UIImage *)image

    Parameters

    image

    An image.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Create a new texture object from a Quartz 2D image.

    Declaration

    Swift

    convenience init(CGImage image: CGImage!)

    Objective-C

    + (instancetype)textureWithCGImage:(CGImageRef)image

    Parameters

    image

    A Quartz 2D image (CGImageRef) object. For more information, see Quartz 2D Programming Guide and CGImage Reference.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture from a subset of an existing texture.

    Declaration

    Swift

    convenience init(rect rect: CGRect, inTexture texture: SKTexture)

    Objective-C

    + (instancetype)textureWithRect:(CGRect)rect inTexture:(SKTexture *)texture

    Parameters

    rect

    A rectangle in the unit coordinate space that specifies the portion of the texture to use.

    texture

    The texture to create the new texture from.

    Return Value

    A new texture object.

    Discussion

    The returned texture object shares the same texture data as the original texture object, meaning that only one copy of the texture data is kept in memory.

    If you call this method on a texture that itself was created using this method, the original texture is used as the source instead. That is, the rectangle is considered to be in the source texture’s coordinate system. Put another way, you cannot make a subtexture of a subtexture without calculating the coordinates yourself.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture by applying a Core Image filter to an existing texture.

    Declaration

    Swift

    func textureByApplyingCIFilter(_ filter: CIFilter) -> Self!

    Objective-C

    - (instancetype)textureByApplyingCIFilter:(CIFilter *)filter

    Parameters

    filter

    A Core Image filter that requires a single inputImage parameter and produces an outputImage parameter.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture from raw pixel data.

    Declaration

    Swift

    convenience init!(data pixelData: NSData!, size size: CGSize)

    Objective-C

    + (instancetype)textureWithData:(NSData *)pixelData size:(CGSize)size

    Parameters

    pixelData

    An NSData object that holds the bitmap data. The pixels must be 32 bpp, 8bpc (unsigned integer) RGBA pixel data. The color components should have been already multiplied by the alpha value.

    size

    The size of the new texture in points.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture from custom formatted raw pixel data.

    Declaration

    Swift

    convenience init!(data pixelData: NSData!, size size: CGSize, rowLength rowLength: UInt32, alignment alignment: UInt32)

    Objective-C

    + (instancetype)textureWithData:(NSData *)pixelData size:(CGSize)size rowLength:(unsigned int)rowLength alignment:(unsigned int)alignment

    Parameters

    pixelData

    An NSData object that holds the bitmap data. The pixels must be 32 bpp, 8bpc (unsigned integer) RGBA pixel data. The color components should have been already multiplied by the alpha value.

    size

    The size of the new texture in points.

    rowLength

    The number of bytes of memory to use per row of the bitmap.

    alignment

    The offset between individual pixels of the pixel data. Specify 0 for tightly packed data.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Creates a new texture from raw pixel data.

    Declaration

    Swift

    convenience init!(data pixelData: NSData!, size size: CGSize, flipped flipped: Bool)

    Objective-C

    + (instancetype)textureWithData:(NSData *)pixelData size:(CGSize)size flipped:(BOOL)flipped

    Parameters

    pixelData

    An NSData object that holds the bitmap data. The pixels must be 32 bpp, 8bpc (unsigned integer) RGBA pixel data. The color components should have been already multiplied by the alpha value.

    size

    The size of the new texture in points.

    flipped

    A Boolean value that indicates whether the image data should be vertically flipped before creating the texture.

    Return Value

    A new texture object.

    Discussion

    The image data is copied before control is returned to your game.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • Creates a normal map texture by analyzing the contents of an existing texture.

    Declaration

    Swift

    func textureByGeneratingNormalMap() -> Self!

    Objective-C

    - (instancetype)textureByGeneratingNormalMap

    Return Value

    A new texture object that contains a normal map.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • Creates a normal map texture by analyzing the contents of an existing texture.

    Declaration

    Swift

    func textureByGeneratingNormalMapWithSmoothness(_ smoothness: CGFloat, contrast contrast: CGFloat) -> Self!

    Objective-C

    - (instancetype)textureByGeneratingNormalMapWithSmoothness:(CGFloat)smoothness contrast:(CGFloat)contrast

    Parameters

    smoothness

    A number between 0.0 and 1.0 indicating how much the texture should be smoothed before the normal map is generated. A value of 0.0 means that the texture is not smoothed at all before being processed.

    contrast

    A value used to magnify the effect of the generated normal map. A value of 1.0 indicates no magnification is applied.

    Return Value

    A new texture object that contains a normal map.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • Creates a new texture whose contents are procedurally generated directional noise data.

    Declaration

    Swift

    convenience init!(vectorNoiseWithSmoothness smoothness: CGFloat, size size: CGSize)

    Objective-C

    + (instancetype)textureVectorNoiseWithSmoothness:(CGFloat)smoothness size:(CGSize)size

    Parameters

    smoothness

    A value that indicates how similar neighboring texels will be in the resulting texture. The value should be between 0.0 and 1.0. A value of 1.0 generates a smooth surface.

    size

    The size of the new texture in points.

    Return Value

    A new noise texture.

    Discussion

    The noise texture is tileable with itself. The RGB values stored in the texture can be used as directional (XYZ) data. The alpha values are also randomized and can be used as magnitude data, if desired.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • Creates a new texture whose contents are procedurally generated colored noise data.

    Declaration

    Swift

    convenience init!(noiseWithSmoothness smoothness: CGFloat, size size: CGSize, grayscale grayscale: Bool)

    Objective-C

    + (instancetype)textureNoiseWithSmoothness:(CGFloat)smoothness size:(CGSize)size grayscale:(BOOL)grayscale

    Parameters

    smoothness

    A value that indicates how similar neighboring texels will be in the resulting texture. The value should be between 0.0 and 1.0. A value of 1.0 generates a smooth surface.

    size

    The size of the new texture in points.

    grayscale

    If YEStrue, all four components of each texel will have equal values. If NOfalse, all four values are completely randomized.

    Return Value

    A new noise texture.

    Discussion

    Unlike other textures produced by Sprite Kit, the texels are not premultiplied by the alpha value. Your custom shaders should compensate for this as necessary.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • The filtering mode used when the size of a sprite drawn with the texture is not drawn at the texture’s native size.

    Declaration

    Swift

    var filteringMode: SKTextureFilteringMode

    Objective-C

    @property(nonatomic) SKTextureFilteringMode filteringMode

    Discussion

    The possible values for this property are listed in “Texture Filtering Modes”. The default value is SKTextureFilteringLinear.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • The size of the texture.

    Declaration

    Swift

    func size() -> CGSize

    Objective-C

    - (CGSize)size

    Return Value

    The dimensions of the texture, measured in points.

    Discussion

    If the texture was created using an image file and that image file hasn’t been loaded, calling this method forces the texture data to be loaded from the file.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • A rectangle that defines the portion of the texture used to render its image.

    Declaration

    Swift

    func textureRect() -> CGRect

    Objective-C

    - (CGRect)textureRect

    Return Value

    A rectangle in the unit coordinate space.

    Discussion

    The default value is a rectangle that covers the entire texture (0,0) - (1,1). You cannot set this value directly; to use only a portion of a texture, use the textureWithRect:inTexture: method to create a new texture.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that indicates whether the texture attempts to generate mipmaps.

    Declaration

    Swift

    var usesMipmaps: Bool

    Objective-C

    @property(nonatomic) BOOL usesMipmaps

    Discussion

    The default value is NOfalse. If you set this to YEStrue, Sprite Kit creates mipmaps for the texture when it prepares the texture for rendering. Mipmaps take up additional memory (usually one-third more) but can improve rendering quality and performance when the texture is reduced in size (such as when you reduce the scale of a sprite rendered using the texture).

    You can only request mipmaps if both of the texture’s dimensions are a power of two.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Load the texture data 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 data is loaded.

    Discussion

    Sprite Kit creates a background task to load the texture data from the associated file, then returns control to your game. After the texture data is loaded, your completion handler is called. Typically, you use this method when you want to guarantee that a particular texture is in memory before accessing it.

    If you need to preload multiple textures at once, use the preloadTextures:withCompletionHandler: method instead.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Load the texture data of multiple textures into memory.

    Declaration

    Swift

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

    Objective-C

    + (void)preloadTextures:(NSArray *)textures withCompletionHandler:(void (^)(void))completionHandler

    Parameters

    textures

    An array of SKTexture objects.

    completionHandler

    A block called after all of the textures are loaded.

    Discussion

    Sprite Kit creates a background task that loads the texture data for all of the textures in the array, then returns control to your game. Your completion handler is called after all of the textures are loaded.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • Texture filtering modes to use when the texture is drawn in a size other than its native size.

    Declaration

    Swift

    enum SKTextureFilteringMode : Int { case Nearest case Linear }

    Objective-C

    typedef enum SKTextureFilteringMode : NSInteger { SKTextureFilteringNearest, SKTextureFilteringLinear, } SKTextureFilteringMode;

    Constants

    • Nearest

      SKTextureFilteringNearest

      Each pixel is drawn using the nearest point in the texture. This mode is faster, but the results are often pixelated.

      Available in iOS 7.0 and later.

    • Linear

      SKTextureFilteringLinear

      Each pixel is drawn by using a linear filter of multiple texels in the texture. This mode produces higher quality results but may be slower.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.