GLKTextureLoader Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GLKit.framework
Availability
Available in OS X v10.8 and later.
Declared in
GLKTextureLoader.h

Overview

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:

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

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.

Tasks

Initialization

Loading Textures from Files

Loading a Texture From a URL

Creating Textures from In-Memory Representations

Creating Textures from CGImages

Loading Cube Maps from Files

Loading Cube Maps from URLs

Class Methods

cubeMapWithContentsOfFile:options:error:

Loads a cube map texture image from a single file and creates a new texture from the data.

+ (GLKTextureInfo *)cubeMapWithContentsOfFile:(NSString *)fileName options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
fileName

A path to the file to load.

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 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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

cubeMapWithContentsOfFiles:options:error:

Loads a cube map texture image from a series of files and creates a new texture from the data.

+ (GLKTextureInfo *)cubeMapWithContentsOfFiles:(NSArray *)filePaths options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
filePaths

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

cubeMapWithContentsOfURL:options:error:

Loads a cube map texture image from a single URL and creates a new texture from the data.

+ (GLKTextureInfo *)cubeMapWithContentsOfURL:(NSURL *)filePath options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
filePath

A path to the image to load.

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 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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithCGImage:options:error:

Loads a 2D texture image from a Quartz image and creates a new texture from the data.

+ (GLKTextureInfo *)textureWithCGImage:(CGImageRef)cgImage options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
cgImage

The Quartz image to be turned into a texture.

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

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.

Table 1  Supported Bitmap Formats

Color Space

Pixel format and bitmap information constant

Null

8 bpp, 8 bpc, kCGImageAlphaOnly

Gray

8 bpp, 8 bpc,kCGImageAlphaNone

Gray

8 bpp, 8 bpc,kCGImageAlphaOnly

RGB

32 bpp, 8 bpc, kCGImageAlphaNoneSkipFirst

RGB

32 bpp, 8 bpc, kCGImageAlphaPremultipliedFirst

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfData:options:error:

Loads a 2D texture image from a memory range and creates a new texture from the data.

+ (GLKTextureInfo *)textureWithContentsOfData:(NSData *)data options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
data

The memory range to load as a texture.

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfFile:options:error:

Loads a 2D texture image from a file and creates a new texture from the data.

+ (GLKTextureInfo *)textureWithContentsOfFile:(NSString *)fileName options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
fileName

A path to the file to load.

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfURL:options:error:

Loads a 2D texture image from a URL and creates a new texture from the data.

+ (GLKTextureInfo *)textureWithContentsOfURL:(NSURL *)filePath options:(NSDictionary *)textureOperations error:(NSError **)outError
Parameters
filePath

A URL to the file to load.

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

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

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

Instance Methods

cubeMapWithContentsOfFile:options:queue:completionHandler:

Asynchronously loads a cube map texture image from a single file and creates a new texture from the data.

- (void)cubeMapWithContentsOfFile:(NSString *)fileName options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
fileName

A path to the file to load.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

cubeMapWithContentsOfFiles:options:queue:completionHandler:

Asynchronously loads a cube map texture image from a series of files and creates a new texture from the data.

- (void)cubeMapWithContentsOfFiles:(NSArray *)filePaths options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
filePaths

An array of 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”.

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

cubeMapWithContentsOfURL:options:queue:completionHandler:

Asynchronously loads a cube map texture image from a single URL and creates a new texture from the data.

- (void)cubeMapWithContentsOfURL:(NSURL *)filePath options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
filePath

A path to the image to load.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

initWithShareContext:

Initializes a new texture loader object.

- (id)initWithShareContext:(NSOpenGLContext *)context
Parameters
context

The share context used to store new textures.

Return Value

A newly initialized texture loader.

Discussion

You only create a texture loader object when your app needs to load textures asynchronously.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithCGImage:options:queue:completionHandler:

Asynchronously loads a 2D texture image from a Quartz image and creates a new texture from the data.

- (void)textureWithCGImage:(CGImageRef)cgImage options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
cgImage

The Quartz image to be turned into a texture.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfData:options:queue:completionHandler:

Asynchronously loads a 2D texture image from a memory range and creates a new texture from the data.

- (void)textureWithContentsOfData:(NSData *)data options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
data

The memory range to load as a texture.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfFile:options:queue:completionHandler:

Asynchronously loads a 2D texture image from a file and creates a new texture from the data.

- (void)textureWithContentsOfFile:(NSString *)fileName options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
fileName

A path to the file to load.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

textureWithContentsOfURL:options:queue:completionHandler:

Asynchronously loads a 2D texture image from a URL and creates a new texture from the data.

- (void)textureWithContentsOfURL:(NSURL *)filePath options:(NSDictionary *)textureOperations queue:(dispatch_queue_t)queue completionHandler:(GLKTextureLoaderCallback)block
Parameters
filePath

A URL to the file to load.

textureOperations

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.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

Constants

GLKTextureLoaderCallback

Signature for the block executed after an asynchronous texture loading operation completes.

typedef void (^GLKTextureLoaderCallback) (GLKTextureInfo *textureInfo, NSError *outError)
Discussion

The block parameters are defined as follows:

textureInfo

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

error

If the operation was successful, this value is nil; otherwise, this parameter holds an object that describes the problem that occurred.

Availability
  • Available in OS X v10.8 and later.
Declared In
GLKTextureLoader.h

Texture Loading Options

Keys to specify in a textureOperations dictionary.

NSString *const GLKTextureLoaderApplyPremultiplication;
NSString *const GLKTextureLoaderGenerateMipmaps;
NSString *const GLKTextureLoaderOriginBottomLeft;
NSString *const GLKTextureLoaderSRGB;
Constants
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 NO, the data is loaded into the sharegroup without being modified. If YES, 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 NO. Never specify YES for a texture that is in a compressed format.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

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 NO, only the texture is loaded. If YES, 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 NO.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

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 NO, the image data is not flipped. If YES, the image data is flipped before being loaded. If the key is not specified, the default value is YES.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

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 NO, the image data is treated as linear pixel data. If YES, the image data is treated as sRGB pixel data. The default value is NO.

Available in OS X v10.9 and later.

Declared in GLKTextureLoader.h.

Texture Error Handling

Strings used when handling NSError messages returned from a texture loading method.

extern NSString *const GLKTextureLoaderErrorDomain;
extern NSString *const GLKTextureLoaderErrorKey;
extern NSString *const GLKTextureLoaderGLErrorKey;
Constants
GLKTextureLoaderErrorDomain

The error domain used by GLKit when returning texture loading errors.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorKey

A key used to retrieve an error string from an error object’s userInfo dictionary.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderGLErrorKey

A key used to retrieve additional information from an error object’s userInfo dictionary.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

Texture Loading Error Codes

Values to be returned in an NSError when a texture loader encounters an error.

enum {
   GLKTextureLoaderErrorFileOrURLNotFound = 0,
   GLKTextureLoaderErrorInvalidNSData = 1,
   GLKTextureLoaderErrorInvalidCGImage = 2,
   GLKTextureLoaderErrorUnknownPathType = 3,
   GLKTextureLoaderErrorUnknownFileType = 4,
   GLKTextureLoaderErrorPVRAtlasUnsupported = 5,
   GLKTextureLoaderErrorCubeMapInvalidNumFiles = 6,
   GLKTextureLoaderErrorCompressedTextureUpload = 7,
   GLKTextureLoaderErrorUncompressedTextureUpload = 8,
   GLKTextureLoaderErrorUnsupportedCubeMapDimensions = 9,
   GLKTextureLoaderErrorUnsupportedBitDepth = 10,
   GLKTextureLoaderErrorUnsupportedPVRFormat = 11,
   GLKTextureLoaderErrorDataPreprocessingFailure = 12
   GLKTextureLoaderErrorMipmapUnsupported = 13,
   GLKTextureLoaderErrorUnsupportedOrientation = 14,
   GLKTextureLoaderErrorReorientationFailure = 15,
   GLKTextureLoaderErrorAlphaPremultiplicationFailure = 16,
   GLKTextureLoaderErrorInvalidEAGLContext = 17
   GLKTextureLoaderErrorIncompatibleFormatSRGB = 18
};
typedef NSUInteger GLKTextureLoaderError;
Constants
GLKTextureLoaderErrorFileOrURLNotFound

A file could not be found at the path provided.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorInvalidNSData

The data provided is not in a recognized image format.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorInvalidCGImage

The CGImage provided was invalid.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnknownPathType

The path type was unrecognized.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnknownFileType

The file was in an unrecognized format.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorPVRAtlasUnsupported

Cube maps may not be compressed in PVRTC format.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorCubeMapInvalidNumFiles

The incorrect number of files were specified for the cube map.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorCompressedTextureUpload

A compressed texture could not be uploaded.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUncompressedTextureUpload

An uncompressed texture could not be uploaded.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnsupportedCubeMapDimensions

The cube map’s dimensions are incorrect.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnsupportedBitDepth

The data in the source image has an unsupported bit depth.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnsupportedPVRFormat

The data in the PVRTC compressed format is in an unsupported format.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorDataPreprocessingFailure

The data could not be preprocessed correctly.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorMipmapUnsupported

The texture source data does not allow mipmaps to be generated.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorUnsupportedOrientation

The texture source data is stored with an unsupported origin position.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorReorientationFailure

The texture source data does not allow the image to be reoriented.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorAlphaPremultiplicationFailure

The texture source data does not allow the alpha to be premultiplied.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorInvalidEAGLContext

The EAGL context was not a valid context.

Available in OS X v10.8 and later.

Declared in GLKTextureLoader.h.

GLKTextureLoaderErrorIncompatibleFormatSRGB

The decoded data was in an incompatible format for an sRGB texture.

Available in OS X v10.9 and later.

Declared in GLKTextureLoader.h.