SPTexture Class Reference

Inherits from	NSObject
Declared in	SPTexture.h

Overview

A texture stores the information that represents an image. It cannot be displayed directly, but has to be mapped onto a display object. In Sparrow, that display object is SPImage.

Image formats

Sparrow supports different file formats for textures. The most common formats are PNG, which contains an alpha channel, and JPG (without an alpha channel). You can also load files in the PVR format (compressed or uncompressed). That’s a special format of the graphics chip of iOS devices that is very efficient.

HD textures

Furthermore, Sparrow supports development in multiple resolutions, i.e. creating a game simultaneously for normal and retina displays. If HD texture support is activated (it is by default if you start Sparrow with [SPViewController startWithRoot:]) and you load a texture like this:

[[SPTexture alloc] initWithContentsOfFile:@"image.png"];

Sparrow will check if it finds the file image@2x.png, and will load that instead (provided that it is available and the application is running on a HD device). The texture object will then return values for width and height that are the original number of pixels divided by 2 (by setting their scale-factor to 2.0). That way, you will always work with the same values for width and height - regardless of the device type.

It is also possible to switch textures depending on the device the app is executed on. The convention is to add a device modifier (~ipad or ~iphone) to the image name, directly before the file extension (and after the scale modifier, if there is one).

Drawing API

Sparrow lets you create custom graphics directly at run-time by using the Core Graphics API. You access the drawing API with a special init-method of SPTexture, which takes a block-parameter you can fill with your drawing code.

SPTexture *customTexture = [[SPTexture alloc] initWithWidth:200 height:100
    draw:^(CGContextRef context)
    {
        // draw a string
        CGContextSetGrayFillColor(context, 1.0f, 1.0f);
        NSString *string = @"Hello Core Graphics";
        [string drawAtPoint:CGPointMake(20.0f, 20.0f) 
                   withFont:[UIFont fontWithName:@"Arial" size:25]];
    }];

Texture Frame

The frame property of a texture allows you to define the position where the texture will appear within an SPImage. The rectangle is specified in the coordinate system of the texture:

SPTexture *baseTexture = [SPTexture textureWithContentsOfFile:@"10x10.png"];
SPRectangle *frame = [SPRectangle rectangleWithX:-10 y:-10 width:30 height:30];
SPTexture *texture = [SPTexture textureWithRegion:nil frame:frame ofTexture:baseTexture];
SPImage *image = [SPImage imageWithTexture:texture];

This code would create an image with a size of 30x30, with the texture placed at x=10, y=10 within that image (assuming that the base texture has a width and height of 10 pixels, it would appear in the middle of the image). This is especially useful when a texture has transparent areas at its sides. It is then possible to crop the texture (removing the transparent edges) and make up for that by specifying a frame.

The texture class itself does not make any use of the frame data. It’s up to classes that use SPTexture to support that feature.

Tasks

Initialization

– initWithWidth:height:
Initializes an empty texture with a certain size (in points).
– initWithWidth:height:draw:
Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage; no mipmaps will be created.
– initWithWidth:height:generateMipmaps:draw:
Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage.
– initWithWidth:height:generateMipmaps:scale:draw:
Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands.
– initWithContentsOfFile:
Initializes a texture with the contents of a file (supported formats: png, jpg, pvr); no mip maps will be created. Sparrow will automatically pick the optimal file for the current system, using standard iOS naming conventions (“@2x”, “~ipad” etc). If the file name ends with “.gz”, the file will be uncompressed automatically.
– initWithContentsOfFile:generateMipmaps:
Initializes a texture with the contents of a file (supported formats: png, jpg, pvr). Sparrow will automatically pick the optimal file for the current system, using standard iOS naming conventions (“@2x”, “~ipad” etc). If the file name ends with “.gz”, the file will be uncompressed automatically.
– initWithContentsOfImage:
Initializes a texture with the contents of a UIImage; no mip maps will be created. The texture will have the same scale factor as the image.
– initWithContentsOfImage:generateMipmaps:
Initializes a texture with the contents of a UIImage. The texture will have the same scale factor as the image.
– initWithRegion:ofTexture:
Initializes a texture with a region (in points) of another texture. The new texture will reference the base texture; no data is duplicated.
– initWithRegion:frame:ofTexture:
Initializes a texture with a region (in points) of another texture, as well as a frame rectangle that makes up for trimmed parts (see class description). The new texture will reference the base texture; no data is duplicated.
+ textureWithContentsOfFile:
Factory method.
+ textureWithContentsOfFile:generateMipmaps:
Factory method.
+ textureWithRegion:ofTexture:
Factory method.
+ textureWithWidth:height:draw:
Factory method.
+ emptyTexture
Factory method. Creates an empty (transparent) texture.

Methods

– adjustVertexData:atIndex:numVertices:
Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.
– adjustTexCoords:numVertices:stride:
Converts texture coordinates stored at the given memory region into the format required for rendering. While the texture coordinates of an image always use the range [0, 1], the actual coordinates could be different: you might be working with a SubTexture. This method adjusts the coordinates accordingly.
– adjustPositions:numVertices:stride:
Moves the position coordinates stored at the given memory region into the format required for rendering. This happens for SubTextures that contain a ‘frame’.

Loading Textures asynchronously

+ loadFromFile:onComplete:
Loads a texture asynchronously from a local file and executes a callback block when it’s finished. No mip maps will be created; premultiplied alpha state is guessed by file type.
+ loadFromFile:generateMipmaps:onComplete:
Loads a texture asynchronously from a local file and executes a callback block when it’s finished.
+ loadFromURL:onComplete:
Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed; no mip maps are created. The scale factor will be parsed from the file name (default: 1).
+ loadFromURL:generateMipmaps:onComplete:
Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed; the scale factor will be parsed from the file name (default: 1).
+ loadFromURL:generateMipmaps:scale:onComplete:
Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed (i.e. no scale factor suffix will be added).
+ loadFromSuffixedURL:onComplete:
Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The method adds a suffix with the current scale factor to the url (e.g. @2x). If that resource is not found, the method will fail. No mip maps are created.
+ loadFromSuffixedURL:generateMipmaps:onComplete:
Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The method adds a suffix with the current scale factor to the url (e.g. @2x). If that resource is not found, the method will fail.

Properties

width
The width of the image in points.
property
height
The height of the image in points.
property
nativeWidth
The width of the texture in pixels (without scale adjustment).
property
nativeHeight
The height of the texture in pixels (without scale adjustment).
property
root
The SPGLTexture this texture is based on.
property
name
The OpenGL texture identifier.
property
premultipliedAlpha
Indicates if the alpha values are premultiplied into the RGB values.
property
scale
The scale factor, which influences width and height properties.
property
format
The OpenGL texture format of this texture.
property
mipmaps
Indicates if the texture contains mipmaps.
property
frame
The frame indicates how the texture should be displayed within an image. (Default: nil)
property
repeat
Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. Note: this makes sense only in textures with sidelengths that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures). (Default: NO)
property
smoothing
The smoothing type influences how the texture appears when it is scaled up or down. (Default: SPTextureSmoothingBilinear)
property

Properties

format

The OpenGL texture format of this texture.

@property (nonatomic, readonly) SPTextureFormat format

Discussion

The OpenGL texture format of this texture.

Declared In

SPTexture.h

frame

The frame indicates how the texture should be displayed within an image. (Default: nil)

@property (nonatomic, readonly) SPRectangle *frame

Discussion

The frame indicates how the texture should be displayed within an image. (Default: nil)

Declared In

SPTexture.h

height

The height of the image in points.

@property (nonatomic, readonly) float height

Discussion

The height of the image in points.

Declared In

SPTexture.h

mipmaps

Indicates if the texture contains mipmaps.

@property (nonatomic, readonly) BOOL mipmaps

Discussion

Indicates if the texture contains mipmaps.

Declared In

SPTexture.h

name

The OpenGL texture identifier.

@property (nonatomic, readonly) uint name

Discussion

The OpenGL texture identifier.

Declared In

SPTexture.h

nativeHeight

The height of the texture in pixels (without scale adjustment).

@property (nonatomic, readonly) float nativeHeight

Discussion

The height of the texture in pixels (without scale adjustment).

Declared In

SPTexture.h

nativeWidth

The width of the texture in pixels (without scale adjustment).

@property (nonatomic, readonly) float nativeWidth

Discussion

The width of the texture in pixels (without scale adjustment).

Declared In

SPTexture.h

premultipliedAlpha

Indicates if the alpha values are premultiplied into the RGB values.

@property (nonatomic, readonly) BOOL premultipliedAlpha

Discussion

Indicates if the alpha values are premultiplied into the RGB values.

Declared In

SPTexture.h

repeat

Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. Note: this makes sense only in textures with sidelengths that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures). (Default: NO)

@property (nonatomic, assign) BOOL repeat

Discussion

Declared In

SPTexture.h

root

The SPGLTexture this texture is based on.

@property (nonatomic, readonly) SPGLTexture *root

Discussion

The SPGLTexture this texture is based on.

Declared In

SPTexture.h

scale

The scale factor, which influences width and height properties.

@property (nonatomic, readonly) float scale

Discussion

The scale factor, which influences width and height properties.

Declared In

SPTexture.h

smoothing

The smoothing type influences how the texture appears when it is scaled up or down. (Default: SPTextureSmoothingBilinear)

@property (nonatomic, assign) SPTextureSmoothing smoothing

Discussion

The smoothing type influences how the texture appears when it is scaled up or down. (Default: SPTextureSmoothingBilinear)

Declared In

SPTexture.h

width

The width of the image in points.

@property (nonatomic, readonly) float width

Discussion

The width of the image in points.

Declared In

SPTexture.h

Class Methods

emptyTexture

Factory method. Creates an empty (transparent) texture.

+ (instancetype)emptyTexture

Discussion

Factory method. Creates an empty (transparent) texture.

Declared In

SPTexture.h

loadFromFile:generateMipmaps:onComplete:

Loads a texture asynchronously from a local file and executes a callback block when it’s finished.

+ (void)loadFromFile:(NSString *)path generateMipmaps:(BOOL)mipmaps onComplete:(SPTextureLoadingBlock)callback

Discussion

Loads a texture asynchronously from a local file and executes a callback block when it’s finished.

Declared In

SPTexture.h

loadFromFile:onComplete:

Loads a texture asynchronously from a local file and executes a callback block when it’s finished. No mip maps will be created; premultiplied alpha state is guessed by file type.

+ (void)loadFromFile:(NSString *)path onComplete:(SPTextureLoadingBlock)callback

Discussion

Loads a texture asynchronously from a local file and executes a callback block when it’s finished. No mip maps will be created; premultiplied alpha state is guessed by file type.

Declared In

SPTexture.h

loadFromSuffixedURL:generateMipmaps:onComplete:

Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The method adds a suffix with the current scale factor to the url (e.g. @2x). If that resource is not found, the method will fail.

+ (void)loadFromSuffixedURL:(NSURL *)url generateMipmaps:(BOOL)mipmaps onComplete:(SPTextureLoadingBlock)callback

Discussion

Declared In

SPTexture.h

loadFromSuffixedURL:onComplete:

+ (void)loadFromSuffixedURL:(NSURL *)url onComplete:(SPTextureLoadingBlock)callback

Discussion

Declared In

SPTexture.h

loadFromURL:generateMipmaps:onComplete:

Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed; the scale factor will be parsed from the file name (default: 1).

+ (void)loadFromURL:(NSURL *)url generateMipmaps:(BOOL)mipmaps onComplete:(SPTextureLoadingBlock)callback

Discussion

Declared In

SPTexture.h

loadFromURL:generateMipmaps:scale:onComplete:

Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed (i.e. no scale factor suffix will be added).

+ (void)loadFromURL:(NSURL *)url generateMipmaps:(BOOL)mipmaps scale:(float)scale onComplete:(SPTextureLoadingBlock)callback

Discussion

Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed (i.e. no scale factor suffix will be added).

Declared In

SPTexture.h

loadFromURL:onComplete:

Loads a texture asynchronously from an URL and executes a callback block when it’s finished. The url will be used exactly as it is passed; no mip maps are created. The scale factor will be parsed from the file name (default: 1).

+ (void)loadFromURL:(NSURL *)url onComplete:(SPTextureLoadingBlock)callback

Discussion

Declared In

SPTexture.h

textureWithContentsOfFile:

Factory method.

+ (instancetype)textureWithContentsOfFile:(NSString *)path

Discussion

Factory method.

Declared In

SPTexture.h

textureWithContentsOfFile:generateMipmaps:

Factory method.

+ (instancetype)textureWithContentsOfFile:(NSString *)path generateMipmaps:(BOOL)mipmaps

Discussion

Factory method.

Declared In

SPTexture.h

textureWithRegion:ofTexture:

Factory method.

+ (instancetype)textureWithRegion:(SPRectangle *)region ofTexture:(SPTexture *)texture

Discussion

Factory method.

Declared In

SPTexture.h

textureWithWidth:height:draw:

Factory method.

+ (instancetype)textureWithWidth:(float)width height:(float)height draw:(SPTextureDrawingBlock)drawingBlock

Discussion

Factory method.

Declared In

SPTexture.h

Instance Methods

adjustPositions:numVertices:stride:

Moves the position coordinates stored at the given memory region into the format required for rendering. This happens for SubTextures that contain a ‘frame’.

- (void)adjustPositions:(void *)data numVertices:(int)count stride:(int)stride

Parameters

data: A pointer to the first coordinate pair (x and y given as floats).

count: The number of coordinate pairs.

stride: The byte offset between consecutive coordinate pairs. If stride is 0, the coordinates are tightly packed.

Discussion

Moves the position coordinates stored at the given memory region into the format required for rendering. This happens for SubTextures that contain a ‘frame’.

Declared In

SPTexture.h

adjustTexCoords:numVertices:stride:

Converts texture coordinates stored at the given memory region into the format required for rendering. While the texture coordinates of an image always use the range [0, 1], the actual coordinates could be different: you might be working with a SubTexture. This method adjusts the coordinates accordingly.

- (void)adjustTexCoords:(void *)data numVertices:(int)count stride:(int)stride

Parameters

data: A pointer to the first coordinate pair (u and v given as floats).

count: The number of coordinate pairs.

stride: The byte offset between consecutive coordinate pairs. If stride is 0, the coordinates are tightly packed.

Discussion

Declared In

SPTexture.h

adjustVertexData:atIndex:numVertices:

Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.

- (void)adjustVertexData:(SPVertexData *)vertexData atIndex:(int)index numVertices:(int)count

Discussion

Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.

Declared In

SPTexture.h

initWithContentsOfFile:

Initializes a texture with the contents of a file (supported formats: png, jpg, pvr); no mip maps will be created. Sparrow will automatically pick the optimal file for the current system, using standard iOS naming conventions (“@2x”, “~ipad” etc). If the file name ends with “.gz”, the file will be uncompressed automatically.

- (instancetype)initWithContentsOfFile:(NSString *)path

Discussion

Declared In

SPTexture.h

initWithContentsOfFile:generateMipmaps:

Initializes a texture with the contents of a file (supported formats: png, jpg, pvr). Sparrow will automatically pick the optimal file for the current system, using standard iOS naming conventions (“@2x”, “~ipad” etc). If the file name ends with “.gz”, the file will be uncompressed automatically.

- (instancetype)initWithContentsOfFile:(NSString *)path generateMipmaps:(BOOL)mipmaps

Discussion

Declared In

SPTexture.h

initWithContentsOfImage:

Initializes a texture with the contents of a UIImage; no mip maps will be created. The texture will have the same scale factor as the image.

- (instancetype)initWithContentsOfImage:(UIImage *)image

Discussion

Initializes a texture with the contents of a UIImage; no mip maps will be created. The texture will have the same scale factor as the image.

Declared In

SPTexture.h

initWithContentsOfImage:generateMipmaps:

Initializes a texture with the contents of a UIImage. The texture will have the same scale factor as the image.

- (instancetype)initWithContentsOfImage:(UIImage *)image generateMipmaps:(BOOL)mipmaps

Discussion

Initializes a texture with the contents of a UIImage. The texture will have the same scale factor as the image.

Declared In

SPTexture.h

initWithRegion:frame:ofTexture:

Initializes a texture with a region (in points) of another texture, as well as a frame rectangle that makes up for trimmed parts (see class description). The new texture will reference the base texture; no data is duplicated.

- (instancetype)initWithRegion:(SPRectangle *)region frame:(SPRectangle *)frame ofTexture:(SPTexture *)texture

Discussion

Declared In

SPTexture.h

initWithRegion:ofTexture:

Initializes a texture with a region (in points) of another texture. The new texture will reference the base texture; no data is duplicated.

- (instancetype)initWithRegion:(SPRectangle *)region ofTexture:(SPTexture *)texture

Discussion

Initializes a texture with a region (in points) of another texture. The new texture will reference the base texture; no data is duplicated.

Declared In

SPTexture.h

initWithWidth:height:

Initializes an empty texture with a certain size (in points).

- (instancetype)initWithWidth:(float)width height:(float)height

Discussion

Initializes an empty texture with a certain size (in points).

Declared In

SPTexture.h

initWithWidth:height:draw:

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage; no mipmaps will be created.

- (instancetype)initWithWidth:(float)width height:(float)height draw:(SPTextureDrawingBlock)drawingBlock

Discussion

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage; no mipmaps will be created.

Declared In

SPTexture.h

initWithWidth:height:generateMipmaps:draw:

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage.

- (instancetype)initWithWidth:(float)width height:(float)height generateMipmaps:(BOOL)mipmaps draw:(SPTextureDrawingBlock)drawingBlock

Discussion

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands. The texture will have the current scale factor of the stage.

Declared In

SPTexture.h

initWithWidth:height:generateMipmaps:scale:draw:

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands.

- (instancetype)initWithWidth:(float)width height:(float)height generateMipmaps:(BOOL)mipmaps scale:(float)scale draw:(SPTextureDrawingBlock)drawingBlock

Discussion

Initializes a texture with a certain size (in points), as well as a block containing Core Graphics commands.

Declared In

SPTexture.h