v2.0.2
Instance Methods | Class Methods | Properties | List of all members
CC3Texture Class Reference

#import <CC3Texture.h>

Inheritance diagram for CC3Texture:
Inheritance graph
[legend]

Instance Methods

(CCTexture *) - __deprecated
 
(NSString *) - constructorDescription
 
(void) - drawWithVisitor:
 
(void) - generateMipmap
 
(id) - initCubeColoredForAxes
 
(id) - initCubeFromFilePattern:
 
(id) - initCubeFromFilesPosX:negX:posY:negY:posZ:negZ:
 
(id) - initCubeWithPixelFormat:andPixelType:
 
(id) - initCubeWithPixelFormat:withPixelType:
 
(id) - initCubeWithSideLength:withPixelFormat:withPixelType:
 
(id) - initCubeWithSize:andPixelFormat:andPixelType:
 
(id) - initFromFile:
 
(id) - initWithCCTexture:
 
(id) - initWithCGImage:
 
(id) - initWithPixelFormat:andPixelType:
 
(id) - initWithPixelFormat:withPixelType:
 
(id) - initWithSize:andPixelFormat:andPixelType:
 
(id) - initWithSize:withColor:
 
(id) - initWithSize:withPixelFormat:withPixelType:
 
(void) - remove
 
(void) - replacePixels:inTarget:withContent:
 
(void) - resizeTo:
 
- Instance Methods inherited from CC3Identifiable
(id) - copy
 
(id) - copyAsClass:
 
(void) - copyUserDataFrom:
 
(id) - copyWithName:
 
(id) - copyWithName:asClass:
 
(id) - copyWithZone:withName:
 
(id) - copyWithZone:withName:asClass:
 
(BOOL) - deriveNameFrom:
 
(BOOL) - deriveNameFrom:usingSuffix:
 
(NSString *) - fullDescription
 
(id) - init
 
(id) - initAtIndex:fromPODResource:
 
(void) - initUserData
 
(id) - initWithName:
 
(id) - initWithTag:
 
(id) - initWithTag:withName:
 
(GLuint) - nextTag
 
(void) - populateFrom:
 

Class Methods

(void) + addTexture:
 
(NSString *) + cachedTexturesDescription
 
(BOOL) + defaultShouldFlipHorizontallyOnLoad
 
(BOOL) + defaultShouldFlipVerticallyOnLoad
 
(ccTexParams) + defaultTextureParameters
 
(CC3Texture *) + getTextureNamed:
 
(BOOL) + isPreloading
 
(void) + removeAllTextures
 
(void) + removeTexture:
 
(void) + removeTextureNamed:
 
(void) + setDefaultShouldFlipHorizontallyOnLoad:
 
(void) + setDefaultShouldFlipVerticallyOnLoad:
 
(void) + setDefaultTextureParameters:
 
(void) + setIsPreloading:
 
(void) + setShouldCacheAssociatedCCTextures:
 
(void) + setShouldGenerateMipmaps:
 
(BOOL) + shouldCacheAssociatedCCTextures
 
(BOOL) + shouldGenerateMipmaps
 
(id) + textureCubeColoredForAxes
 
(id) + textureCubeFromFilePattern:
 
(id) + textureCubeFromFilesPosX:negX:posY:negY:posZ:negZ:
 
(id) + textureCubeWithPixelFormat:andPixelType:
 
(id) + textureCubeWithPixelFormat:withPixelType:
 
(id) + textureCubeWithSideLength:withPixelFormat:withPixelType:
 
(id) + textureCubeWithSize:andPixelFormat:andPixelType:
 
(id) + textureFromFile:
 
(NSString *) + textureNameFromFilePath:
 
(id) + textureWithCCTexture:
 
(id) + textureWithCGImage:
 
(id) + textureWithPixelFormat:andPixelType:
 
(id) + textureWithPixelFormat:withPixelType:
 
(id) + textureWithSize:andPixelFormat:andPixelType:
 
(id) + textureWithSize:withColor:
 
(id) + textureWithSize:withPixelFormat:withPixelType:
 
- Class Methods inherited from CC3Identifiable
(GLint) + instanceCount
 
(void) + resetTagAllocation
 

Properties

CCTexture *ccTexture2D __deprecated
 
CCTexture * ccTexture
 
CGSize coverage
 
BOOL hasAlpha
 
BOOL hasMipmap
 
BOOL hasPremultipliedAlpha
 
GLenum horizontalWrappingFunction
 
GLenum initialAttachmentFace
 
BOOL isBumpMap
 
BOOL isPOT
 
BOOL isPOTHeight
 
BOOL isPOTWidth
 
BOOL isTexture2D
 
BOOL isTextureCube
 
BOOL isUpsideDown
 
CC3Vector lightDirection
 
GLenum magnifyingFunction
 
GLenum minifyingFunction
 
GLenum pixelFormat
 
GLenum pixelType
 
GLenum samplerSemantic
 
BOOL shouldFlipHorizontallyOnLoad
 
BOOL shouldFlipVerticallyOnLoad
 
CC3IntSize size
 
CC3Texturetexture
 
GLuint textureID
 
ccTexParams textureParameters
 
GLenum textureTarget
 
CC3TextureUnittextureUnit
 
GLenum verticalWrappingFunction
 
- Properties inherited from CC3Identifiable
NSObject *sharedUserData __deprecated
 
NSString * name
 
NSString * nameSuffix
 
GLint podIndex
 
BOOL shouldIncludeInDeepCopy
 
GLuint tag
 
NSObject * userData
 
- Properties inherited from <CC3Cacheable>
NSString * name
 

Detailed Description

The root class of a class cluster representing textures.

Since a single texture can be used by many nodes and materials, textures can be cached. The application can use the class-side getTextureNamed: method to retrieve a loaded texture from the cache, and the class-side addTexture: method to add a new texture to the cache. See the notes of those two methods for more details.

When creating an instance, several of the class-side texture... family of methods (particularly those loading from files) automatically check the cache for an existing instance, based on the filename, and will use that cached instance instead of loading the file again. If the texture is not in the cache, these methods will load it and place it in the cache automatically. These methods can therefore be invoked repeatedly without having to be concerned whether multiple copies of the same texture content will be loaded. Check the notes for the creation methods to verify which methods make use of the cache.

CC3Texture is the root of a class cluster organized for loading different texture types, for both 2D and cube textures. Use the creation and initialization methods from this root CC3Texture class. The initializer will ensure that the correct subclass for the texture type, and in some cases, the texture file type, is created and returned. Because of this class-cluster structure, be aware that the class of the instance returned by an instance creation or initialization method may be different than the receiver of that method.

There is one exception to this paradigm. Under fixed-pipeline rendering, such as in OpenGL ES 1.1 under iOS, or OpenGL without shaders under OSX, multi-texturing is handled using configurable texture units. In order to assign a texture unit to a CC3Texture, you must directly instatiate an instance of CC3TextureUnitTexture, and then assign a texture unit to it, instead of letting the CC3Texture creation and initialization methods handle it.

To improve both performance and texture quality, by default, instances whose width and height are a power-of-two (see the isPOT property) automatically generate a mipmap when a texture is loaded. If you do not want mipmaps to be generated automatically, set the class-side shouldGenerateMipmaps property to NO. With automatic mipmap generation turned off, you can selectively generate a mipmap on any single CC3Texture instance by using the generateMipmap method. In addition, textures that contain mipmaps within the file content (PVR files may contain mipmaps) will retain and use this mipmap. See the shouldGenerateMipmaps and hasMipmap properties, and the generateMipmap method for more information.

Under iOS and OSX, most texture formats are loaded updside-down. This is because the vertical axis of the coordinate system of OpenGL is inverted relative to the iOS or OSX view coordinate system. Subclasses that may loaded upside-down can be configured to automatically flip the texture right-way up during loading. In addition, the isFlippedVerically property indicates whether the texture is upside down. This can be used to ensure that textures are displayed with the correct orientation. When a CC3Texture is applied to a mesh, the mesh will be adjusted automatically if the texture is upside down.

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. If you want to avoid this pre-processing for PNG or TGA files, for textures such as normal maps or lighting maps, that you don't want to be modified, you can prepend a 'p' to the file extension ("ppng" or "ptga") to cause Xcode to skip this pre-processing and to use a loader that does not pre-multiply the alpha. You can also use this for other file types as well. See the notes for the CC3STBImage useForFileExtensions class-side property for more info.

Method Documentation

- (CCTexture*) __deprecated
Deprecated:
Use the ccTexture property instead.

Implements CC3Identifiable.

+ (void) addTexture: (CC3Texture *)  texture

Adds the specified texture to the collection of loaded textures.

Textures are accessible via their names through the getTextureNamed: method, and each texture name should be unique. If a texture with the same name as the specified texture already exists in this cache, an assertion error is raised.

This cache is a weak cache, meaning that it does not hold strong references to the textures that are added to it. As a result, the specified texture will automatically be deallocated and removed from this cache once all external strong references to it have been released.

+ (NSString*) cachedTexturesDescription

Returns a description of the contents of this cache, with each entry formatted as a source-code line for loading the texture from a file.

During development time, you can log this string, then copy and paste it into a pre-loading function within your app code.

- (NSString*) constructorDescription

Returns a description formatted as a source-code line for loading this texture from a file.

During development time, you can log this string, then copy and paste it into a pre-loading function within your app code.

+ (BOOL) defaultShouldFlipHorizontallyOnLoad

This class-side property determines the initial value of the shouldFlipHorizontallyOnLoad for instances of this class.

Each subclass can have a different value for this class-side property. See the notes for this property on each subclass to understand the initial value.

Implemented in CC3Texture2D, and CC3TextureCube.

+ (BOOL) defaultShouldFlipVerticallyOnLoad

This class-side property determines the initial value of the shouldFlipVerticallyOnLoad for instances of this class.

Each subclass can have a different value for this class-side property. See the notes for this property on each subclass to understand the initial value.

Implemented in CC3Texture2D, and CC3TextureCube.

+ (ccTexParams) defaultTextureParameters

The default values for the textureParameters property (with the initial values of this class-side property):

  • minifyingFunction (GL_LINEAR_MIPMAP_NEAREST)
  • magnifyingFunction (GL_LINEAR)
  • horizontalWrappingFunction (GL_REPEAT)
  • verticalWrappingFunction (GL_REPEAT)
- (void) drawWithVisitor: (CC3NodeDrawingVisitor *)  visitor

Binds this texture to the GL engine.

If any of the texture parameter properties have been changed since the last time this texture was bound, they are updated in the GL engine at this time.

- (void) generateMipmap

Generates a mipmap for this texture, if needed.

It is safe to invoke this method more than once, because it will only generate a mipmap if it does not yet exist.

Mipmaps can only be generated for textures whose width and height are are a power-of-two (see the isPOT property).

+ (CC3Texture*) getTextureNamed: (NSString *)  name

Returns the texture with the specified name, or nil if a texture with that name has not been added.

- (id) initCubeColoredForAxes

Initializes this instance to have a unique solid color for each side of the cube.

The sides of the cube are colored using an easy (RGB <=> XYZ) mnemonic as follows:

  • +X-axis: Red
  • -X-axis: Cyan (inverse of Red)
  • +Y-axis: Green
  • -Y-axis: Magenta (inverse of Green)
  • +Z-axis: Blue
  • -Z-axis: Yellow (inverse of Blue)

Once initialized, the texture will be bound to the GL engine.

The name property of this instance will be nil.

Since the texture is just a solid color, a mipmap is not created.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initCubeFromFilePattern: (NSString *)  aFilePathPattern

Initializes this instance by loading the six cube face textures using the specified pattern string as a string format template to derive the names of the six textures, and returns whether all six files were successfully loaded.

This method expects the six required files to have identical paths and names, except that each should contain one of the following character substrings in the same place in each file path: "PosX", "NegX", "PosY", "NegY", "PosZ", "NegZ".

The specified file path pattern should include one standard NSString format marker %@ at the point where one of the substrings in the list above should be substituted.

As an example, the file path pattern MyCubeTex%png would be expanded by this method to load the following six textures:

  • MyCubeTexPosX.png
  • MyCubeTexNegX.png
  • MyCubeTexPosY.png
  • MyCubeTexNegY.png
  • MyCubeTexPosZ.png
  • MyCubeTexNegZ.png

The format marker can occur anywhere in the file name. It does not need to occur at the end as in this example.

The specified file path pattern may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path pattern can simply be the file name pattern.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

The name of this instance is set to the unqualified file name derived from substituting an empty string into the format marker in the specified file path pattern string.

Returns nil if any of the six files could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initCubeFromFilesPosX: (NSString *)  posXFilePath
negX: (NSString *)  negXFilePath
posY: (NSString *)  posYFilePath
negY: (NSString *)  negYFilePath
posZ: (NSString *)  posZFilePath
negZ: (NSString *)  negZFilePath 

Initializes this instance by loading the six cube face textures at the specified file paths, and returns whether all six files were successfully loaded.

Each of the specified file paths may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the corresponding file path can simply be the name of the file.

The name of this instance is set to the unqualified file name of the specified posXFilePath file path.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

Returns nil if any of the six files could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initCubeWithPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use initCubeWithPixelFormat:withPixelType:
- (id) initCubeWithPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Initializes this instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine when the resizeTo: method is invoked, providing the texture with a size.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initCubeWithSideLength: (GLuint)  sideLength
withPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Initializes this instance from the specified texture properties, without providing content.

The sideLength argument indicates the length, in pixels, of each side of the texture.

Once initialized, the texture will be bound to the GL engine, with space allocated for six texture faces of the specified size and pixel content. Content can be added later by using this texture as a rendering surface.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initCubeWithSize: (CC3IntSize size
andPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use initCubeWithSize:withPixelFormat:withPixelType:
- (id) initFromFile: (NSString *)  filePath

Returns an instance initialized by loading the single texture file at the specified file path.

The specified file path may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path can simply be the name of the file.

The name of this instance is set to the unqualified file name from the specified file path and the tag is set to an automatically generated unique tag value.

This method can be used to load a single standard 2D texture. It can also be used to load cube-map textures contained within a single PVR texture file.

This method cannot be used to load cube-maps that require more than one file to be loaded.

CC3Texture is the root of a class cluster for loading different file types. Depending on the file type of the specified file, this method may return an instance of a class that is different than the class of the receiver. You can use the textureClassForFile: method to determine the cluster subclass whose instance will be returned by this method for the specified file.

Normally, you should use the textureFromFile: method to reuse any cached instance instead of creating and loading a new instance. The textureFromFile: method automatically invokes this method if an instance does not exist in the texture cache, in order to create and load the texture from the file, and after doing so, places the newly loaded instance into the cache.

However, by invoking the alloc method and then invoking this method directly, the application can load the texture without first checking the texture cache. The texture can then be placed in the cache using the addTexture: method. If you load two separate textures from the same file, be sure to set a distinct name for each before adding each to the cache.

If the class-side shouldGenerateMipmaps property is set to YES, and the texture file does not already contain a mipmap, a mipmap will be generated for the texture automatically.

Returns nil if the file could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initWithCCTexture: (CCTexture *)  ccTexture

Initializes this instance from the specified Cocos2D CCTexture.

This instance will use the same GL texture object as the specified CCTexture. The specified CCTexture can be retrieved from this instance using the ccTexture property.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initWithCGImage: (CGImageRef)  cgImg

Initializes this instance from the content in the specified CGImage.

The name property of this instance will be nil.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initWithPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use initWithPixelFormat:withPixelType:
- (id) initWithPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Initializes this instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine when the resizeTo: method is invoked, providing the texture with a size.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initWithSize: (CC3IntSize size
andPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use initWithSize:withPixelFormat:withPixelType:
- (id) initWithSize: (CC3IntSize size
withColor: (ccColor4B)  color 

Initializes this instance containing pixel content of the specified size and solid, uniform color.

This method can be useful for creating a test texture.

Since the texture is just a solid color, a mipmap is not created.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

- (id) initWithSize: (CC3IntSize size
withPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Initializes this instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine, with space allocated for a texture of the specified size and pixel content. Content can be added later by using this texture as a rendering surface.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

+ (BOOL) isPreloading

Returns whether textures are being pre-loaded.

See the setIsPreloading setter method for a description of how and when to use this property.

- (void) remove

Removes this texture instance from the cache.

+ (void) removeAllTextures

Removes from the cache all textures that are instances of any subclass of the receiver.

You can use this method to selectively remove specific types of texturs, based on the texture class, by invoking this method on that class. If you invoke this method on the CC3Texture class, this cache will be compltely cleared. However, if you invoke this method on one of its subclasses, only those textures that are instances of that subclass (or one of its subclasses in turn) will be removed, leaving the remaining textures in the cache.

+ (void) removeTexture: (CC3Texture *)  texture

Removes the specified texture from the texture cache.

+ (void) removeTextureNamed: (NSString *)  name

Removes the texture with the specified name from the texture cache.

- (void) replacePixels: (CC3Viewport rect
inTarget: (GLenum)  target
withContent: (ccColor4B *)  colorArray 

Replaces a portion of the content of this texture by writing the specified array of pixels into the specified rectangular area within the specified target for this texture, The specified content replaces the texture data within the specified rectangle.

The specified content array must be large enough to contain content for the number of pixels in the specified rectangle.

If this is a standard 2D texture, the target must be GL_TEXTURE_2D. If this is a cube-map texture, the specified target can be one of the following:

  • GL_TEXTURE_CUBE_MAP_POSITIVE_X
  • GL_TEXTURE_CUBE_MAP_NEGATIVE_X
  • GL_TEXTURE_CUBE_MAP_POSITIVE_Y
  • GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
  • GL_TEXTURE_CUBE_MAP_POSITIVE_Z
  • GL_TEXTURE_CUBE_MAP_NEGATIVE_Z

Content is read from the specified array left to right across each row of pixels within the specified image rectangle, starting at the row at the bottom of the rectangle, and ending at the row at the top of the rectangle.

Within the specified array, the pixel content should be packed tightly, with no gaps left at the end of each row. The last pixel of one row should immediately be followed by the first pixel of the next row.

The pixels in the specified array are in standard 32-bit RGBA. If the pixelFormat and pixelType properties of this texture are not GL_RGBA and GL_UNSIGNED_BYTE, respectively, the pixels in the specified array will be converted to the format and type of this texture before being inserted into the texture. Be aware that this conversion will reduce the performance of this method. For maximum performance, match the format and type of this texture to the 32-bit RGBA format of the specified array, by setting the pixelFormat property to GL_RGBA and the pixelType property to GL_UNSIGNED_BYTE. However, keep in mind that the 32-bit RGBA format consumes more memory than most other formats, so if performance is of lesser concern, you may choose to minimize the memory requirements of this texture by setting the pixelFormat and pixelType properties to values that consume less memory.

If this texture has mipmaps, they are not automatically updated. Once all desired content has been replaced, invoke the generateMipmap method to regenerate the mipmaps.

- (void) resizeTo: (CC3IntSize size

Resizes this texture to the specified dimensions and clears all texture content.

+ (void) setDefaultShouldFlipHorizontallyOnLoad: (BOOL)  shouldFlip

This class-side property determines the initial value of the shouldFlipVerticallyOnLoad for instances of this class.

Each subclass can have a different value for this class-side property. See the notes for this property on each subclass to understand the initial value.

Implemented in CC3Texture2D, and CC3TextureCube.

+ (void) setDefaultShouldFlipVerticallyOnLoad: (BOOL)  shouldFlip

This class-side property determines the initial value of the shouldFlipVerticallyOnLoad for instances of this class.

Each subclass can have a different value for this class-side property. See the notes for this property on each subclass to understand the initial value.

Implemented in CC3Texture2D, and CC3TextureCube.

+ (void) setDefaultTextureParameters: (ccTexParams)  texParams

The default values for the textureParameters property (with the initial values of this class-side property):

  • minifyingFunction (GL_LINEAR_MIPMAP_NEAREST)
  • magnifyingFunction (GL_LINEAR)
  • horizontalWrappingFunction (GL_REPEAT)
  • verticalWrappingFunction (GL_REPEAT)

You can change the value of this class-side property to affect any textures subsequently created or loaded from a file.

+ (void) setIsPreloading: (BOOL)  isPreloading

Sets whether textures are being pre-loaded.

Textures that are added to this cache while the value of this property is YES will be strongly cached and cannot be deallocated until specifically removed from this cache. You must manually remove any textures added to this cache while the value of this property is YES.

Textures that are added to this cache while the value of this property is NO will be weakly cached, and will automatically be deallocated and removed from this cache once all references to the resource outside this cache are released.

You can set the value of this property at any time, and can vary it between YES and NO to accomodate your specific loading patterns.

The initial value of this property is NO, meaning that textures will be weakly cached in this cache, and will automatically be removed if not used in the scene. You can set this property to YES in order to pre-load textures that will not be immediately used in the scene, but which you wish to keep in the cache for later use.

+ (void) setShouldCacheAssociatedCCTextures: (BOOL)  shouldCache

Indicates whether the associated Cocos2D CCTexture, available through the ccTexture property, should be automatically added to the Cocos2D CCTextureCache.

The initial value of this property is NO. If you intend to share many of the same textures between Cocos3D and Cocos2D objects, you may want to set this property to YES.

With this property set to NO, you can still add any CCTexture retrieved from the ccTexture property to the CCTextureCache using the CCTexture addToCacheWithName: method.

+ (void) setShouldGenerateMipmaps: (BOOL)  shouldMipmap

Sets whether a mipmap should be generated automatically for each instance when the texture is loaded.

If this property is set to YES, mipmap will only be generated if the texture file does not already contain a mipmap.

The value of this property affects all textures loaded while that value is in effect. You can set this property to the desired value prior to loading one or more textures.

The default value of this class-side property is YES, indicating that mipmaps will be generated for any texture loaded whose dimensions are a power-of-two.

+ (BOOL) shouldCacheAssociatedCCTextures

Indicates whether the associated Cocos2D CCTexture, available through the ccTexture property, should be automatically added to the Cocos2D CCTextureCache.

The initial value of this property is NO. If you intend to share many of the same textures between Cocos3D and Cocos2D objects, you may want to set this property to YES.

With this property set to NO, you can still add any CCTexture retrieved from the ccTexture property to the CCTextureCache using the CCTexture addToCacheWithName: method.

+ (BOOL) shouldGenerateMipmaps

Returns whether a mipmap should be generated automatically for each instance when the texture is loaded.

If this property is set to YES, mipmap will only be generated if the texture file does not already contain a mipmap.

The value of this property affects all textures loaded while that value is in effect. You can set this property to the desired value prior to loading one or more textures.

The default value of this class-side property is YES, indicating that mipmaps will be generated for any texture loaded whose dimensions are a power-of-two.

+ (id) textureCubeColoredForAxes

Returns an instance initialized to have a unique solid color for each side of the cube.

The sides of the cube are colored using an easy (RGB <=> XYZ) mnemonic as follows:

  • +X-axis: Red
  • -X-axis: Cyan (inverse of Red)
  • +Y-axis: Green
  • -Y-axis: Magenta (inverse of Green)
  • +Z-axis: Blue
  • -Z-axis: Yellow (inverse of Blue)

Once initialized, the texture will be bound to the GL engine.

Since the texture is just a solid color, a mipmap is not created.

The name of the instance is set to "Axes-Colored-Cube".

Textures loaded through this method are cached. If the texture was already loaded and is in the cache, it is retrieved and returned. If the texture has not in the cache, it is loaded, placed into the cache, indexed by its name, and returned. It is therefore safe to invoke this method any time the texture is needed, without having to worry that the texture will be repeatedly loaded from file.

To clear a texture instance from the cache, use the removeTexture: method.

To create a texture directly, bypassing the cache, use the alloc and initCubeColoredForAxes methods. This technique can be used to create the same texture twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately. However, when choosing to do so, be aware that textures often consume significant memory.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureCubeFromFilePattern: (NSString *)  aFilePathPattern

Returns an instance initialized by loading the six cube face textures using the specified pattern string as a string format template to derive the names of the six textures, and returns whether all six files were successfully loaded.

This method expects the six required files to have identical paths and names, except that each should contain one of the following character substrings in the same place in each file path: "PosX", "NegX", "PosY", "NegY", "PosZ", "NegZ".

The specified file path pattern should include one standard NSString format marker %@ at the point where one of the substrings in the list above should be substituted.

As an example, the file path pattern MyCubeTex%png would be expanded by this method to load the following six textures:

  • MyCubeTexPosX.png
  • MyCubeTexNegX.png
  • MyCubeTexPosY.png
  • MyCubeTexNegY.png
  • MyCubeTexPosZ.png
  • MyCubeTexNegZ.png

The format marker can occur anywhere in the file name. It does not need to occur at the end as in this example.

The specified file path pattern may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path pattern can simply be the file name pattern.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

The name of this instance is set to the unqualified file name derived from substituting an empty string into the format marker in the specified file path pattern string.

Textures loaded through this method are cached. If the texture was already loaded and is in the cache, it is retrieved and returned. If the texture has not in the cache, it is loaded, placed into the cache, indexed by its name, and returned. It is therefore safe to invoke this method any time the texture is needed, without having to worry that the texture will be repeatedly loaded from file.

To clear a texture instance from the cache, use the removeTexture: method.

To load the file directly, bypassing the cache, use the alloc and initFromFilePattern: methods. This technique can be used to load the same texture twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately. However, when choosing to do so, be aware that textures often consume significant memory.

Returns nil if the texture is not in the cache and any of the six files could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureCubeFromFilesPosX: (NSString *)  posXFilePath
negX: (NSString *)  negXFilePath
posY: (NSString *)  posYFilePath
negY: (NSString *)  negYFilePath
posZ: (NSString *)  posZFilePath
negZ: (NSString *)  negZFilePath 

Returns an instance initialized by loading the six cube face textures at the specified file paths, and returns whether all six files were successfully loaded.

Each of the specified file paths may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the corresponding file path can simply be the name of the file.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

The name of this instance is set to the unqualified file name of the specified posXFilePath file path.

Textures loaded through this method are cached. If the texture was already loaded and is in the cache, it is retrieved and returned. If the texture has not in the cache, it is loaded, placed into the cache, indexed by its name, and returned. It is therefore safe to invoke this method any time the texture is needed, without having to worry that the texture will be repeatedly loaded from file.

To clear a texture instance from the cache, use the removeTexture: method.

To load the file directly, bypassing the cache, use the alloc and initFromFilesPosX:negX:posY:negY:posZ:negZ: methods. This technique can be used to load the same texture twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately. However, when choosing to do so, be aware that textures often consume significant memory.

Returns nil if the texture is not in the cache and any of the six files could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureCubeWithPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use textureCubeWithPixelFormat:withPixelType:
+ (id) textureCubeWithPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Allocates and initializes an autoreleased instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine when the resizeTo: method is invoked, providing the texture with a size.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureCubeWithSideLength: (GLuint)  sideLength
withPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Allocates and initializes an autoreleased instance from the specified texture properties, without providing content.

The sideLength argument indicates the length, in pixels, of each side of the texture.

Once initialized, the texture will be bound to the GL engine, with space allocated for a texture of the specified size and pixel content. Content can be added later by using this texture as a rendering surface.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureCubeWithSize: (CC3IntSize size
andPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use textureCubeWithSize:withPixelFormat:withPixelType:
+ (id) textureFromFile: (NSString *)  filePath

Returns an instance initialized by loading the single texture file at the specified file path.

The specified file path may be either an absolute path, or a path relative to the application resource directory. If the file is located directly in the application resources directory, the specified file path can simply be the name of the file.

The name of this instance is set to the unqualified file name from the specified file path and the tag is set to an automatically generated unique tag value.

This method can be used to load a single standard 2D texture. It can also be used to load cube-map textures contained within a single PVR texture file.

This method cannot be used to load cube-maps that require more than one file to be loaded.

CC3Texture is the root of a class cluster for loading different file types. Depending on the file type of the specified file, this method may return an instance of a class that is different than the receiver. You can use the textureClassForFile: method to determine the cluster subclass whose instance will be returned by this method for the specified file.

Textures loaded through this method are cached. If the texture was already loaded and is in the cache, it is retrieved and returned. If the texture has not in the cache, it is loaded from the specified file, placed into the cache, and returned. It is therefore safe to invoke this method any time the texture is needed, without having to worry that the texture will be repeatedly loaded from file.

To clear a texture instance from the cache, use the removeTexture: method.

To load the file directly, bypassing the cache, use the alloc and initFromFile: methods. This technique can be used to load the same texture twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately. However, when choosing to do so, be aware that textures often consume significant memory.

If the class-side shouldGenerateMipmaps property is set to YES, and the texture file does not already contain a mipmap, a mipmap will be generated for the texture automatically.

Returns nil if the texture is not in the cache and could not be loaded.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (NSString*) textureNameFromFilePath: (NSString *)  filePath

Returns a texture name derived from the specified file path.

This method is used to standardize the naming of textures, to ease in adding and retrieving textures to and from the cache, and is used to create the name for each texture that is loaded from a file.

This implementation returns the lastComponent of the specified file path.

+ (id) textureWithCCTexture: (CCTexture *)  ccTexture

Allocates and initializes an instance from the specified Cocos2D CCTexture.

The instance will use the same GL texture object as the specified CCTexture. The specified CCTexture can be retrieved from this instance using the ccTexture property.

The name property of the instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureWithCGImage: (CGImageRef)  cgImg

Allocates and initializes an autoreleased instance from the content in the specified CGImage.

The name property of this instance will be nil.

If the class-side shouldGenerateMipmaps property is set to YES, a mipmap will be generated for the texture automatically.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureWithPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use textureWithPixelFormat:withPixelType:
+ (id) textureWithPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Allocates and initializes an autoreleased instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine when the resizeTo: method is invoked, providing the texture with a size.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of the instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

+ (id) textureWithSize: (CC3IntSize size
andPixelFormat: (GLenum)  format
andPixelType: (GLenum)  __deprecated 
Deprecated:
Use textureWithSize:withPixelFormat:withPixelType:
+ (id) textureWithSize: (CC3IntSize size
withColor: (ccColor4B)  color 

Allocates and initializes an autoreleased instance containing pixel content of the specified size and solid, uniform color.

This method can be useful for creating a test texture.

Since the texture is just a solid color, a mipmap is not created.

The name property of this instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be a different instance of a different class than the receiver.

+ (id) textureWithSize: (CC3IntSize size
withPixelFormat: (GLenum)  format
withPixelType: (GLenum)  type 

Allocates and initializes an autoreleased instance from the specified texture properties, without providing content.

Once initialized, the texture will be bound to the GL engine, with space allocated for a texture of the specified size and pixel content. Content can be added later by using this texture as a rendering surface.

See the notes for the pixelFormat and pixelType properties for the range of values permitted for the corresponding format and type parameters here.

The name property of the instance will be nil.

Since textures can consume significant resources, you should assign this instance a name and add it to the texture cache by using the class-side addTexture: method. You can then retrieve the texture from the cache via the getTextureNamed: method to apply this texture to multple meshes.

CC3Texture is the root of a class-cluster. The object returned may be an instance of a different class than the receiver.

Property Documentation

- (CCTexture* ccTexture2D) __deprecated
readnonatomicretain
Deprecated:
Renamed to ccTexture.
- (CCTexture*) ccTexture
readnonatomicretain

Returns a Cocos2D-compatible 2D texture, that references the same GL texture.

The value of the class-side shouldCacheAssociatedCCTextures property determines whether the CCTexture returned by this method will automatically be added to the CCTextureCache.

With the class-side shouldCacheAssociatedCCTextures property set to NO, you can still add any CCTexture retrieved from this property to the CCTextureCache using the CCTextureCache addTexture:named: method.

Although a CCTexture can be retrieved for any type of CC3Texture, including cube-maps, using a cube-mapped texture as a Cocos2D texture may lead to unexpected behavour.

- (CGSize) coverage
readnonatomicassign

Returns the proportional size of the usable image in the texture, relative to its physical size.

Depending on the environment, the physical size of textures may be some power-of-two (POT), even when the texture dimensions are not. In this case, the usable image size is the actual portion of it that contains the image. This property contains two fractional floats (width & height), each between zero and one, representing the proportional size of the usable image

As an example, an image whose dimensions are actually 320 x 480 pixels may be loaded into a texture that is 512 x 512 pixels. In that case, the value returned by this property will be {0.625, 0.9375}, as calculated from {320/512, 480/512}.

- (BOOL) hasAlpha
readwritenonatomicassign

Indicates whether this texture has an alpha channel, representing opacity.

The value of this property is determined from the contents of the texture file, but you can set this property directly to override the value determined from the file.

- (BOOL) hasMipmap
readnonatomicassign

Returns whether a mipmap has been generated for this texture.

If the class-side shouldGenerateMipmaps property is YES, mipmaps are generated automatically after the texture data has been loaded.

Mipmaps can also be generated manually by invoking the generateMipmap method.

- (BOOL) hasPremultipliedAlpha
readwritenonatomicassign

Indicates whether the alpha channel of this texture has already been multiplied into each of the RGB color channels.

The value of this property is determined from the contents of the texture file, but you can set this property directly to override the value determined from the file.

- (GLenum) horizontalWrappingFunction
readwritenonatomicassign

The method used to detemine the texel to use when a texture coordinate has a value less than zero or greater than one in the horizontal (S) direction.

This property must be one of the following values:

  • GL_CLAMP_TO_EDGE: Uses the nearest texel from the nearest edge, effectively extending this texel across the mesh.
  • GL_REPEAT: Repeats the texture across the mesh.
  • GL_MIRRORED_REPEAT: Repeats the texture across the mesh, altering between the texture and a mirror-image of the texture.

The values GL_REPEAT and GL_MIRRORED_REPEAT can only be set if the isPOT property returns YES, indicating that both width and height dimensions of this texture are a power-of-two. Otherwise, this property will always return GL_CLAMP_TO_EDGE.

This property must be set to GL_CLAMP_TO_EDGE when using this texture as a rendering target as an attachment to a rendering surface such as a framebuffer ("render-to-texture").

The initial value of this property is set by the defaultTextureParameters class-side property, and will be GL_REPEAT if the dimensions of this texture are a power-of-two, or GL_CLAMP_TO_EDGE if not.

- (GLenum) initialAttachmentFace
readnonatomicassign

Returns the GL face to use when initially attaching this texture to a framebuffer.

Returns GL_TEXTURE_2D if this is a 2D texture, or GL_TEXTURE_CUBE_MAP_POSITIVE_X if this is a cube map texture.

- (BOOL) isBumpMap
readnonatomicassign

Returns whether this texture is configured as an object-space bump-map.

Returns NO. Subclasses, such as CC3TextureUnitTexture may override.

- (BOOL) isPOT
readnonatomicassign

Returns whether both the width and the height of this texture is a power-of-two.

- (BOOL) isPOTHeight
readnonatomicassign

Returns whether the height of this texture is a power-of-two.

- (BOOL) isPOTWidth
readnonatomicassign

Returns whether the width of this texture is a power-of-two.

- (BOOL) isTexture2D
readnonatomicassign

Returns whether this texture is a standard two-dimentional texture.

- (BOOL) isTextureCube
readnonatomicassign

Returns whether this texture is a six-sided cube-map texture.

- (BOOL) isUpsideDown
readwritenonatomicassign

Indicates whether this texture is flipped upside-down.

The vertical axis of the coordinate system of OpenGL is inverted relative to the CoreGraphics view coordinate system. As a result, some texture file formats may be loaded upside down. Most common file formats, including JPG, PNG & PVR are loaded right-way up, but using proprietary texture formats developed for other platforms may result in textures being loaded upside-down.

The value of this property is determined from the contents of the texture file, but you can set this property directly to override the value determined from the file.

- (CC3Vector) lightDirection
readwritenonatomicassign

The direction, in local node coordinates, of the light source that is to interact with this texture if the texture has been configured as an object-space bump-map.

Object-space bump-maps are textures that store a normal vector (XYZ coordinates), in object-space coordinates, in the RGB components of each texture pixel, instead of color information. These per-pixel normals interact with the value of this lightDirection property (through a dot-product), to determine the luminance of the pixel.

Object-space bump-maps are used primarily with multi-texturing in a fixed-pipeline rendering environment such as OpenGL ES 1.1. Bump-maps in a programmable-pipeline, such as OpenGL ES 2.0, more commonly use tangent-space normal mapping, which does not make use of this property.

Most textures ignore this property. In this implementation, setting this property has no effect, and reading this property always returns kCC3VectorZero.

Subclasses, such as CC3TextureUnitTexture may override to make use of this property.

- (GLenum) magnifyingFunction
readwritenonatomicassign

The magnifying function to be used whenever a pixel being textured maps to an area less than or equal to one texel.

This property must be one of the following values:

  • GL_NEAREST: Uses the texel nearest to the center of the pixel.
  • GL_LINEAR: Uses a weighted average of the four closest texels.

The initial value of this property is set by the defaultTextureParameters class-side property, and defaults to GL_LINEAR.

- (GLenum) minifyingFunction
readwritenonatomicassign

The minifying function to be used whenever a pixel being textured maps to an area greater than one texel.

This property must be one of the following values:

  • GL_NEAREST: Uses the texel nearest to the center of the pixel.
  • GL_LINEAR: Uses a weighted average of the four closest texels.
  • GL_NEAREST_MIPMAP_NEAREST: Uses GL_NEAREST on the mipmap that is closest in size.
  • GL_LINEAR_MIPMAP_NEAREST: Uses GL_LINEAR on the mipmap that is closest in size.
  • GL_NEAREST_MIPMAP_LINEAR: Uses GL_NEAREST on the two mipmaps that are closest in size, then uses the weighted average of the two results.
  • GL_LINEAR_MIPMAP_LINEAR: Uses GL_LINEAR on the two mipmaps that are closest in size, then uses the weighted average of the two results.

The last four values above require that a mipmap be available, as indicated by the hasMipmap property. If one of those values is set in this property, this property will only return either GL_NEAREST (for all GL_NEAREST... values) or GL_LINEAR (for all GL_LINEAR... values) until a mipmap has been created. See the hasMipmap property for more information about mipmaps.

The initial value of this property is set by the defaultTextureParameters class-side property, and defaults to GL_LINEAR_MIPMAP_NEAREST, or GL_LINEAR if the texture does not have a mipmap.

- (GLenum) pixelFormat
readnonatomicassign

Returns the pixel format of the texture.

The returned value may be one of the following:

  • GL_RGBA
  • GL_RGB
  • GL_ALPHA
  • GL_LUMINANCE
  • GL_LUMINANCE_ALPHA
  • GL_DEPTH_COMPONENT
  • GL_DEPTH_STENCIL
- (GLenum) pixelType
readnonatomicassign

Returns the pixel data type.

Possible values depend on the value of the pixelFormat property as follows:

pixelFormat pixelType


GL_RGBA GL_UNSIGNED_BYTE GL_UNSIGNED_SHORT_4_4_4_4 GL_UNSIGNED_SHORT_5_5_5_1 GL_RGB GL_UNSIGNED_BYTE GL_UNSIGNED_SHORT_5_6_5 GL_ALPHA GL_UNSIGNED_BYTE GL_LUMINANCE GL_UNSIGNED_BYTE GL_LUMINANCE_ALPHA GL_UNSIGNED_BYTE GL_DEPTH_COMPONENT GL_UNSIGNED_SHORT GL_UNSIGNED_INT GL_DEPTH_STENCIL GL_UNSIGNED_INT_24_8

- (GLenum) samplerSemantic
readnonatomicassign

Returns the GLSL uniform texture sampler semantic for this type of texture.

- (BOOL) shouldFlipHorizontallyOnLoad
readwritenonatomicassign

Indicates whether this instance will flip the texture horizontally during loading.

Some types of textures (notably cube-map textures) are stored in GL memory horizontally flipped.

If this property is set to YES during loading, the texture will be flipped horizontally in memory.

The initial value of this property is set to the value of the class-side defaultShouldFlipHorizontallyOnLoad property.

- (BOOL) shouldFlipVerticallyOnLoad
readwritenonatomicassign

Indicates whether this instance will flip the texture vertically during loading, in order to ensure that the texture is oriented upside up.

Under iOS and OSX, most textures are loaded into memory upside-down because of the difference in vertical orientation between the OpenGL and CoreGraphics coordinate systems.

If this property is set to YES during loading, and the texture has been loaded upside down, the texture will be flipped in memory so that it is oriented the right way up.

If this property is set to NO during loading, and the texture has been loaded upside up, the texture will be flipped in memory so that it is oriented upside down.

It is possible to compensate for an upside-down using texture coordinates. You can set this property to NO prior to loading in order to leave the texture upside-down and use texture coordinates to compensate.

The initial value of this property is set to the value of the class-side defaultShouldFlipVerticallyOnLoad property.

- (CC3IntSize) size
readnonatomicassign

The size of this texture in pixels.

- (CC3Texture*) texture
readnonatomicretain

Some texture types wrap a base internal texture.

This property returns that wrapped texture, or, if this instance does not wrap another texture, this property returns this instance.

This property provides polymorphic compatibility with CC3Texture subclasses, notably CC3TextureUnitTexture, that contain another, underlying texture.

- (GLuint) textureID
readnonatomicassign

The texture ID used to identify this texture to the GL engine.

- (ccTexParams) textureParameters
readwritenonatomicassign

A convenience method to accessing the following four texture parameter properties using a Cocos2D ccTexParams structure:

  • minifyingFunction
  • magnifyingFunction
  • horizontalWrappingFunction
  • verticalWrappingFunction

The value of each component of this structure will be the same as the corresponding property on this instance. See the notes for each of those properties for an indication of the initial values for each of those properties.

- (GLenum) textureTarget
readnonatomicassign

Returns the GL target of this texture.

Returns GL_TEXTURE_2D if this is a 2D texture, or GL_TEXTURE_CUBE_MAP if this is a cube map texture.

- (CC3TextureUnit*) textureUnit
readwritenonatomicretain

When using multiple textures with fixed-pipeline rendering, as in OpenGL ES 1.1, textures are combined using environmental settings applied via a texture unit.

When using OpenGL ES 2.0, or OpenGL on OSX, texture units are not typically used, but in some circumstances can be used to carry certain additional configuration information for the texture.

In this implementation, setting this property has no effect, and reading this property will always return nil. Subclasses, such as CC3TextureUnitTexture, will override to make use of this property. When making use of texture units, be sure to instantiate an instance of a subclass that supports texture units, such as CC3TextureUnitTexture.

- (GLenum) verticalWrappingFunction
readwritenonatomicassign

The method used to detemine the texel to use when a texture coordinate has a value less than zero or greater than one in the vertical (T) direction.

This property must be one of the following values:

  • GL_CLAMP_TO_EDGE: Uses the nearest texel from the nearest edge, effectively extending this texel across the mesh.
  • GL_REPEAT: Repeats the texture across the mesh.
  • GL_MIRRORED_REPEAT: Repeats the texture across the mesh, altering between the texture and a mirror-image of the texture.

The values GL_REPEAT and GL_MIRRORED_REPEAT can only be set if the isPOT property returns YES, indicating that both width and height dimensions of this texture are a power-of-two. Otherwise, this property will always return GL_CLAMP_TO_EDGE.

This property must be set to GL_CLAMP_TO_EDGE when using this texture as a rendering target as an attachment to a rendering surface such as a framebuffer ("render-to-texture").

The initial value of this property is set by the defaultTextureParameters class-side property, and will be GL_REPEAT if the dimensions of this texture are a power-of-two, or GL_CLAMP_TO_EDGE if not.


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