Instance Methods | Class Methods | Properties | List of all members
CC3STBImage Class Reference

#import <CC3STBImage.h>

Inheritance diagram for CC3STBImage:
Inheritance graph

Instance Methods

(GLubyte *) - extractImageData
(id) - initFromFile:
(BOOL) - loadFromFile:

Class Methods

(id) + imageFromFile:
(BOOL) + shouldUseForFileExtension:
(NSMutableSet *) + useForFileExtensions


GLuint componentCount
GLubyte * imageData
GLenum pixelFormat
GLenum pixelType
CC3IntSize size

Detailed Description

CC3STBImage represents an image file loaded using the STBImage library.

This class can be used to bypass the OS image loaders. When building for iOS, raw PNG and TGA images are pre-processed by Xcode to pre-multiply alpha, and to reorder the pixel component byte order, to optimize the image for the iOS platform.

However, these changes are not compatible with images that are not used strictly for standard texture blending, including textures used as normal maps, or textures whose components contain data unrelated to blending.

This class can be use to load the following file types:

Note that most file types contain certain restrictions on content. This class is not designed to be a general, all purpose image loader, but rather, is designed to handle most common cases where the file content can be controlled during image creation.

The set returned by the class-side useForFileExtensions property can be used to determine which file-type extensions will be loaded using this class. The remaining file types will be loaded using the standard OS image file loaders. See the notes for that property for the default list of file extensions that will be loaded using this class.

Method Documentation

- (GLubyte*) extractImageData

Returns a pointer to the pixel image data, and sets the imageData property to NULL.

This effectively surrenders ownership of the pixel memory to the invoking object. Subsequent invocations of the imageData property, or this method will return NULL, and this instance will not attempt to free the memory referenced by the returned pointer when this instance is deallocated.

+ (id) imageFromFile: (NSString *)  aFilePath

Allocates and initializes an instance by loading the image file at the specified file path.

- (id) initFromFile: (NSString *)  aFilePath

Initializes this instance by loading the image file at the specified file path.

- (BOOL) loadFromFile: (NSString *)  aFilePath

Loads the specified file, and returns whether the file was successfully loaded.

+ (BOOL) shouldUseForFileExtension: (NSString *)  fileExtension

Returns whether this class should be used to load a file with the specified file extension, by comparing it to the list of file extensions defined in the useForFileExtensions property.

The case of the specified file extension does not matter. It is converted to a lowercase string before being compared against the file extensions in the useForFileExtensions property

+ (NSMutableSet*) useForFileExtensions

Returns a list of file extensions that will be loaded using this class.

You can retrieve and modify this list directly in order to change the file extensions that will be loaded using this class. File extensions added to this list should be completely lowercase.

The shouldUseForFileExtension: method is used to compare a specific file extension against this list.

By default, special extensions are used, but you can add a primary extension, such as "png", to have ALL PNG files loaded using this library, if that suits your purposes. However, keep in mind that Xcode performs a pre-processing optimization on known PNG and TGA files, so loading them as such may produce unexpected results.

Initially, this list contains:

  • "ppng" - @"pjpg" - @"ptga" - @"pbmp" - @"ppsd" - @"pgif" - @"phdr" - @"ppic"

The 'p' prefix is a reference to the use of this class to load "pure", or "proper" files that have not been pre-processed by Xcode. The use of a modified file extension ensures that Xcode will not pre-process them.

Property Documentation

- (GLuint) componentCount

Returns the number of color components per pixel.

- (GLubyte*) imageData

Returns a pointer to the pixel image data, without reliquishing ownership of the memory referenced by the returned pointer.

When this instance is deallocated, it will free the memory referenced by the returned pointer. To claim ownership of the memory, invoke the extractImageData method instead.

- (GLenum) pixelFormat

Returns the pixel format of the texture.

The returned value may be one of the following:

  • GL_RGB
- (GLenum) pixelType

Returns the pixel data type.

Always returns GL_UNSIGNED_BYTE.

- (CC3IntSize) size

Returns the size of this texture in pixels.

The documentation for this class was generated from the following file: