The GLKTextureLoader class simplifies the effort required to load your texture data. The GLKTextureLoader class can load two-dimensional or cubemap textures in most image formats supported by the Image I/O framework. On iOS, it can also load textures compressed in the pvrtc format. It can load the data synchronously or asynchronously.

To load textures synchronously, make a context with the desired sharegroup the current context, and then call one or more of the class methods. The returned texture info object includes details about the loaded texture.

To load textures asynchronously, your initialization code allocates and initializes a new GLKTextureLoader object using the sharegroup object that should be the destination for new textures. Then, to load a texture, your app calls one of the texture loader’s instance methods, passing in a completion handler block to be called when the texture has been loaded.

The following OpenGL properties are set for a newly created, non-mipmapped texture:

GL_TEXTURE_MIN_FILTER:GL_LINEAR

GL_TEXTURE_MAG_FILTER:GL_LINEAR

GL_TEXTURE_WRAP_S:GL_CLAMP_TO_EDGE

GL_TEXTURE_WRAP_T:GL_CLAMP_TO_EDGE

The following OpenGL properties are set for a newly created, mipmapped texture:

GL_TEXTURE_MIN_FILTER:GL_LINEAR_MIPMAP_LINEAR

GL_TEXTURE_MAG_FILTER:GL_LINEAR

GL_TEXTURE_WRAP_S:GL_CLAMP_TO_EDGE

GL_TEXTURE_WRAP_T:GL_CLAMP_TO_EDGE

The GLKTextureLoader and GLKTextureInfo classes do not manage the OpenGL texture for you. Once the texture is returned to your app, you are responsible for it. This means that after your app is finished using an OpenGL texture, it must explicitly deallocate it by calling the glDeleteTextures function.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to textureWithContentsOfFile:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to textureWithContentsOfURL:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to textureWithContentsOfData:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

outError

If an error occurs, upon return contains an NSError object that describes the problem.

If you are not interested in this information, pass NULL.

Return Value

A texture info object that describes the loaded texture or nil if an error occurred.

Discussion

This class method loads the texture into the sharegroup attached to the current context for the thread this method is called on.

If the image was created using the CGBitmapImageContextCreate function, it must use one of the pixel formats described in Table 1. CGImages loaded from files typically are already in one of these formats.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to textureWithCGImage:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

outError

If an error occurs, upon return contains an NSError object that describes the problem.

If you are not interested in this information, pass NULL.

Return Value

A texture info object that describes the loaded texture or nil if an error occurred.

Discussion

The file is assumed to be a single image that includes the six faces of the cube map. The image’s height must be six times the width, and the images should be arranged in the following order from top to bottom: north, south, east, west, top, bottom. Alternatively, the image can have a width that is six times the height, and arranged from left to right, but this takes additional processing to load.

This class method loads the texture into the sharegroup attached to the current context for the thread this method is called on.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to cubeMapWithContentsOfFile:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

An array of NSURL or NSString objects that provide the paths to the six files that make up the cube map.

textureOperations

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

outError

If an error occurs, upon return contains an NSError object that describes the problem.

If you are not interested in this information, pass NULL.

Return Value

A texture info object that describes the loaded texture or nil if an error occurred.

Discussion

The array of file paths must include six entries for the six faces of the cube map. The URLs should be arranged in the following order: Right(+x), Left(-x), Top(+y), Bottom(-y), Front(+z), Back(-z). This coordinate system is left-handed if you think of yourself within the cube. The coordinate system is right-handed if you think of yourself outside of the cube.

This class method loads the texture into the sharegroup attached to the current context for the thread this method is called on.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to cubeMapWithContentsOfURL:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

outError

If an error occurs, upon return contains an NSError object that describes the problem.

If you are not interested in this information, pass NULL.

Return Value

A texture info object that describes the loaded texture or nil if an error occurred.

Discussion

The file is assumed to be a single image that includes the six faces of the cube map. The image’s height must be six times the width, and the images should be arranged in the following order from top to bottom: Right(+x), Left(-x), Top(+y), Bottom(-y), Front(+z), Back(-z). This coordinate system is left-handed if you think of yourself within the cube. The coordinate system is right-handed if you think of yourself outside of the cube.

Alternatively, the image can have a width that is six times the height, and arranged from left to right, but this takes additional processing to load.

This class method loads the texture into the sharegroup attached to the current context for the thread this method is called on.

Parameters

A dictionary that describes any additional steps you want the texture loader to take when loading the texture. See “Texture Loading Options”.

queue

A dispatch queue that your block is called on when the task completes. If NULL is passed, the block is called on the main dispatch queue.

block

A block to be called when the task completes.

Discussion

This method is identical to cubeMapWithContentsOfURL:options:error:, except that it loads the texture asynchronously. When this method is called, it creates a new background task to handle the request and then returns control to your app. Later, when the task is complete, GLKit calls your completion handler on the queue you provided.

Constants

GLKTextureLoaderApplyPremultiplication

GLKTextureLoaderApplyPremultiplication

This key specifies whether the data in the image should be premultiplied before being loaded into the sharegroup. The value for this key is an NSNumber object that specifies a boolean value. If NOfalse, the data is loaded into the sharegroup without being modified. If YEStrue, the red, green and blue components of each pixel are multiplied by the alpha value. If the key is not specified, the default value is NOfalse. Never specify YEStrue for a texture that is in a compressed format.

Available in iOS 5.0 and later.

GLKTextureLoaderGenerateMipmaps

GLKTextureLoaderGenerateMipmaps

This key specifies whether mipmaps should be created for the texture. The value for this key is an NSNumber object that specifies a boolean value. If NOfalse, only the texture is loaded. If YEStrue, a full set of mipmap levels are generated for the texture when the texture is created. The GL_TEXTURE_MIN_FILTER parameter for the texture is changed to GL_LINEAR_MIPMAP_LINEAR when mipmaps are generated. If the key is not specified, the default value is NOfalse.

Available in iOS 5.0 and later.

GLKTextureLoaderOriginBottomLeft

GLKTextureLoaderOriginBottomLeft

This key specifies whether the image data should be vertically flipped to match OpenGL’s coordinate system. The value for this key is an NSNumber object that specifies a boolean value. If NOfalse, the image data is not flipped. If YEStrue, the image data is flipped before being loaded. If the key is not specified, the default value is NOfalse.

Available in iOS 5.0 and later.

GLKTextureLoaderGrayscaleAsAlpha

GLKTextureLoaderGrayscaleAsAlpha

This key specifies whether the image data in a grayscale image should be treated as alpha information. The value for this key is an NSNumber object that specifies a boolean value. If NOfalse, the image data is treated as luminance data. If YEStrue, the image data is treated as alpha data. The default value is NOfalse. This key is ignored if the source image is not a grayscale image.

Available in iOS 5.0 and later.

GLKTextureLoaderSRGB

GLKTextureLoaderSRGB

This key specifies whether the image data in the texture should be treated as sRGB data. The value for this key is an NSNumber object that specifies a boolean value. If NOfalse, the image data is treated as linear pixel data. If YEStrue, the image data is treated as sRGB pixel data. The default value is NOfalse.