Inherits from NSObject
Declared in CC3STBImage.h

Overview

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: – JPEG baseline (no JPEG progressive) – PNG 8-bit-per-channel only – TGA (not sure what subset, if a subset) – BMP non-1bpp, non-RLE – PSD (composited view only, no extra channels) – GIF (*comp always reports as 4-channel) – HDR (radiance rgbE format) – PIC (Softimage PIC)

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.

Tasks

Properties

componentCount

Returns the number of color components per pixel.

@property (nonatomic, readonly) GLuint componentCount

Declared In

CC3STBImage.h

imageData

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

@property (nonatomic, readonly) GLubyte *imageData

Discussion

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.

Declared In

CC3STBImage.h

pixelFormat

Returns the pixel format of the texture.

@property (nonatomic, readonly) GLenum pixelFormat

Discussion

The returned value may be one of the following: – GL_RGBA – GL_RGB – GL_LUMINANCE_ALPHA – GL_LUMINANCE

Declared In

CC3STBImage.h

pixelType

Returns the pixel data type. Always returns GL_UNSIGNED_BYTE.

@property (nonatomic, readonly) GLenum pixelType

Declared In

CC3STBImage.h

size

Returns the size of this texture in pixels.

@property (nonatomic, readonly) CC3IntSize size

Declared In

CC3STBImage.h

Class Methods

imageFromFile:

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

+ (id)imageFromFile:(NSString *)aFilePath

Declared In

CC3STBImage.h

shouldUseForFileExtension:

  • 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.
+ (BOOL)shouldUseForFileExtension:(NSString *)fileExtension

Discussion

  • 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

Declared In

CC3STBImage.h

useForFileExtensions

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

+ (NSMutableSet *)useForFileExtensions

Discussion

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.

Declared In

CC3STBImage.h

Instance Methods

extractImageData

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

- (GLubyte *)extractImageData

Discussion

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.

Declared In

CC3STBImage.h

initFromFile:

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

- (id)initFromFile:(NSString *)aFilePath

Declared In

CC3STBImage.h

loadFromFile:

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

- (BOOL)loadFromFile:(NSString *)aFilePath

Declared In

CC3STBImage.h