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

#import <CC3TextureUnit.h>

Inheritance diagram for CC3TextureUnit:
Inheritance graph

Instance Methods

(void) - bindWithVisitor:

Class Methods

(void) + bindDefaultWithVisitor:
(id) + textureUnit


CCColorRef color
ccColor4F constantColor
BOOL isBumpMap
CC3Vector lightDirection
CCOpacity opacity
CC3DOT3RGB rgbNormalMap
GLenum textureEnvironmentMode

Detailed Description

In fixed rendering pipeline (without shaders), CC3TextureUnit is used by certain classes in the CC3Texture class-cluster to configure the GL texture environment to which the texture is being applied.

Notably, the texture unit defines how the texture is to be combined with textures from other texture units in a multi-texture layout.

CC3TextureUnit is not typically used in a programmable rendering pipeline containing GLSL shaders. However, for certain techniques, such as object-space bump-mapping, a CC3TextureUnit can be used to carry additional environmental parameters for the shaders.

With fixed-pipeline multi-texturing, several textures can be overlaid and combined in interesting ways onto a single material. Each texture is processed by a GL texture unit, and is combined with the textures already processed by other texture units. The source and type of combining operation can be individually configured by subclasses of this class. Support for bump-mapping as one of these combining configurations is explicitly provided by the CC3BumpMapTextureUnit subclass.

This base CC3TextureUnit class permits setting a variety of texture environment modes via the textureEnvironmentMode property. For the full range of configuration flexibility, the CC3ConfigurableTextureUnit subclass contains the full range of configuration properties associated with the GL_COMBINE texture environment mode.

Method Documentation

+ (void) bindDefaultWithVisitor: (CC3NodeDrawingVisitor *)  visitor

Automatically invoked from CC3Texture when no texture unit configuration is provided in that texture.

In the GL engine, sets the combining function to the default value of GL_MODULATE, and the texture constant color to the default value of kCCC4FBlackTransparent.

- (void) bindWithVisitor: (CC3NodeDrawingVisitor *)  visitor

Template method that binds the configuration of this texture unit to the GL engine.

The visitor provides additional configuration information that can be used by subclass overrides of this method.

+ (id) textureUnit

Allocates and initializes an autoreleased instance.

Property Documentation

- (CCColorRef) color

The constant color of this texture unit, returned as a CCColorRef.

Querying this property returns the RGB components of the constantColor property.

When setting this property, the RGB values are each converted to a floating point number between 0 and 1, and are set into the constantColor property. The alpha component of constantColor remains unchanged.

- (ccColor4F) constantColor

The constant color of the texture unit.

This will be used by the combiner when the value of one of the source properties of a subclass is set to GL_CONSTANT. This is often the case for bump-mapping configurations.

Although this property can be set directly, it is rare to do so. Usually, this property is set indirectly via the lightDirection property, which converts the XYZ coordinates of a lighting direction vector into the RGB components of this property.

This property is not used by this parent class implementation, but is provided for common access by subclasses.

The initial value of this property is kCCC4FBlackTransparent.

- (BOOL) isBumpMap

Returns whether this texture unit is configured as a bump-map.

This implementation always returns NO. Subclasses that support bump-mapping will override this default implementation.

- (CC3Vector) lightDirection

The direction, in local tangent coordinates, of the light source that is to interact with subclasses that are configured as bump-maps (aka normal maps).

Bump-maps are textures that store a normal vector (XYZ 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.

Setting this property changes the value of the constantColor property. The lightDirection vector is normalized and shifted from the range of +/- 1.0 to the range 0.0-1.0. Then each XYZ component in the vector is mapped to the RGB components of the constantColor using the rgbNormalMap property.

Reading this value reads the value from the constantColor property. The RGB components of the color are mapped to the XYZ components of the direction vector using the rgbNormalMap property, and then shifted from the color component range 0.0-1.0 to the directional vector range +/- 1.0.

The value of this property must be in the tangent-space coordinates associated with the texture UV space, in practice, this property is typically not set directly. Instead, you can use the globalLightPosition property of the mesh node that is making use of this texture and texture unit.

- (CCOpacity) opacity

The opacity of this texture unit.

Querying this property returns the alpha component of the constantColor property.

When setting this property, the value is converted to a floating point number between 0 and 1, and is set into the constantColor property. The RGB components of constantColor remain unchanged.

- (CC3DOT3RGB) rgbNormalMap

When a subclass is configured as a bump-map, this property indicates how the XYZ coordinates of each per-pixel normal are stored in the RGB values of each pixel.

The texture has three slots (R, G & B) in which to store three normal coordinate components (X, Y & Z). This can be done in any of six ways, as indicated by the values of the CC3DOT3RGB enumeration.

The initial value of this property is kCC3DOT3RGB_XYZ, indicating that the X, Y & Z components of the bump-map normals will be stored in the R, G & B coordinates of the texture pixels, respectively.

- (GLenum) textureEnvironmentMode

Defines the texture function to be used when combining this texture unit with the output of the previous texture unit.

This can be set to one of several fixed texture functions (GL_ADD, GL_MODULATE, GL_DECAL, GL_BLEND, GL_REPLACE), in which case the remaining configuration properties of this class are ignored. Setting this property to GL_MODULATE replicates the default behaviour of the CC3Texture class.

If you want to set this property to GL_COMBINE, to open up significant additional configuration flexibility, use the CC3ConfigurableTextureUnit subclass, which contains the full range of configuration properties associated with the GL_COMBINE functionality.

The initial value of this property is GL_MODULATE.

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