Inherits from CC3ShaderSemanticsBase : NSObject
Declared in CC3ShaderSemantics.h

Overview

CC3ShaderSemanticsByVarName extends CC3ShaderSemanticsBase to add the assignment of semantics to uniform and attribute variables based on matching specific variable names within the GLSL source code.

Since the semantics are determined by GLSL variable name, it is critical that the GLSL shader code use very specific attribute and uniform variable names.

This extension to CC3ShaderSemanticsByVarName establishes a Cocos3D default mappings between variable names and semantics.

An application can use the mappings defined in this extension as the basis for its own mappings and add or change a few of its own additional mappings, or an application may ignore this extension and may instead provide its own extensions to populate completely different mappings.

Tasks

Other Methods

DefaultMappings Methods

Instance Methods

addVariableConfiguration:

Adds the specified variable configuration to the configuration lookup.

- (void)addVariableConfiguration:(CC3GLSLVariableConfiguration *)varConfig

Discussion

Configurations added via this method are used to configure the variables submitted to the configureVariable: method.

Configurations are added to the lookup by name. If a configuration with the same name already exists in the lookup, it is replaced with the specified configuration.

Declared In

CC3ShaderSemantics.h

configureVariable:

This implementation uses the name property of the specified variable to look up a configuration, and sets the semantic property of the specified variable to that of the retrieved configuration.

- (BOOL)configureVariable:(CC3GLSLVariable *)variable

Discussion

Returns YES if a configuration was found and the semantic was assigned, or NO if a configuration could not be found for the variable.

Declared In

CC3ShaderSemantics.h

mapVarName:toSemantic:

Adds a variable configruation that maps the specified variable name to the specified semantic at semantic index zero.

- (void)mapVarName:(NSString *)name toSemantic:(GLenum)semantic

Discussion

This is a convenience method that invokes the mapVarName:toSemantic:at: method, passing a value of zero for the semanticIndex argument. See the description of that method for more info.

Declared In

CC3ShaderSemantics.h

mapVarName:toSemantic:at:

Adds a variable configruation that maps the specified variable name to the specified semantic and semantic index.

- (void)mapVarName:(NSString *)name toSemantic:(GLenum)semantic at:(GLuint)semanticIndex

Discussion

This implementation creates an instance of CC3GLSLVariableConfiguration configured with the specified name, semantic and semantic index, and invokes the addVariableConfiguration: method.

The value of the semantic parameter is typically one of values in the CC3Semantic enumeration, but an application can define and use additional semantics beyond the values defined by CC3Semantic. Additional semantics defined by the application should fall with the range defined by the kCC3SemanticAppBase and kCC3SemanticMax constants, inclusively.

Declared In

CC3ShaderSemantics.h

populateWithDefaultVariableNameMappings

Populates this instance with the default Cocos3D mappings between variable names and semantics.

- (void)populateWithDefaultVariableNameMappings

Discussion

An application wishing to add additional semantic mappings, or override any of the default mappings can invoke this method, and then invoke the mapVarName:toSemantic: or addVariableConfiguration: methods to add or change any of the mappings.

An application wishing to define a completely different semantic mapping may instantiate an instance of this class, will avoid invoking this method, and will typically add its own population methods in a class extension category.

Declared In

CC3ShaderSemantics.h

populateWithLegacyVariableNameMappings

@deprecated Populates this instance with the default Cocos3D mappings initially included with early versions of Cocos3D 2.0.

- (void)populateWithLegacyVariableNameMappings

Discussion

These legacy mappings use less efficient uniform mappings, including use of the array-of-structures paradigm. For GLSL under OpenGL ES, each element of each structure in an array of structures is assigned to its own uniform variable for the purpose of managing and populating the uniforms. This can significantly increase the number of actual uniforms, and results in a corresponding increase in the overhead of managing and populating the larger number of uniforms.

It recommended that the array-of-structure approach offered by this method be avoided. It is provided here to provide backwards compatibility for shaders already developed using these legacy mappings.

Declared In

CC3ShaderSemantics.h

populateWithStructuredVariableNameMappings

@deprecated Populates this instance with the default Cocos3D mappings between variable names and semantics that are based on uniforms collected together into structures.

- (void)populateWithStructuredVariableNameMappings

Discussion

Structure-based mapping provides an organized approach to managing uniform names, but are not compatible with current OSX implementations of GLSL. Current OSX drivers do not handle structure-based uniforms correctly.

If you have developed GLSL shaders under iOS, that use this structure-based approach to uniform naming, you can use this method to populate a semantic mapping that supports this approach. For new iOS applications, and for all OSX applications, you should use the semantic uniform name mappings defined by the populateWithDefaultVariableNameMappings method.

Declared In

CC3ShaderSemantics.h