v2.0.2
|
|
v2.0.2
|
#import <CC3Texture.h>
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 |
| CC3Texture * | texture |
| GLuint | textureID |
| ccTexParams | textureParameters |
| GLenum | textureTarget |
| CC3TextureUnit * | textureUnit |
| 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 |
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.
| - (CCTexture*) __deprecated |
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):
| - (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:
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:
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 | |
| - (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 | |
| - (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 | |
| - (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 | |
| - (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:
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):
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:
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:
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 | |
| + (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 | |
| + (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 | |
| + (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 | |
| + (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.
|
readnonatomicretain |
|
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.
|
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}.
|
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.
|
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.
|
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.
|
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:
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.
|
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.
|
readnonatomicassign |
Returns whether this texture is configured as an object-space bump-map.
Returns NO. Subclasses, such as CC3TextureUnitTexture may override.
|
readnonatomicassign |
Returns whether both the width and the height of this texture is a power-of-two.
|
readnonatomicassign |
Returns whether the height of this texture is a power-of-two.
|
readnonatomicassign |
Returns whether the width of this texture is a power-of-two.
|
readnonatomicassign |
Returns whether this texture is a standard two-dimentional texture.
|
readnonatomicassign |
Returns whether this texture is a six-sided cube-map texture.
|
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.
|
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.
|
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:
The initial value of this property is set by the defaultTextureParameters class-side property, and defaults to GL_LINEAR.
|
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:
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.
|
readnonatomicassign |
Returns the pixel format of the texture.
The returned value may be one of the following:
|
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
|
readnonatomicassign |
Returns the GLSL uniform texture sampler semantic for this type of texture.
|
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.
|
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.
|
readnonatomicassign |
The size of this texture in pixels.
|
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.
|
readnonatomicassign |
The texture ID used to identify this texture to the GL engine.
|
readwritenonatomicassign |
A convenience method to accessing the following four texture parameter properties using a Cocos2D ccTexParams structure:
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.
|
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.
|
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.
|
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:
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.