Discussion

Normally this property is set during initialization. If you set this property directly, you must invoke the link method, and optionally, the prewarm method, once both shaders have been set via this property and the vertexShader property.

Discussion

This property must be set prior to the program being compiled.

Discussion

If the value of this property is YES, and the value of a uniform has not been set via either a semantic mapping, or a uniform override in the shader context in a mesh node, a default value will be used for the variable. The default value depends on the variable type. It will be zero for scalars, (0,0,0,1) for vectors, or an identity matrix for matrices.

If the value of this property is NO, and the value of a uniform has not been set via either a semantic mapping, or a uniform override in the shader context in a mesh node, an assertion error will be raised. This ensures that unexpected missing uniform variables are detected directly and early in the development cycle.

The initial value of this property is determined by the value of the class-side defaultShouldAllowDefaultVariableValues property. By default, this will be NO, indicating that an assertion error will be raised if the value of a uniform cannot be determined.

Discussion

The 2D textures are allocated consecutive texture units beginning at the returned texture unit.

Discussion

The cube textures are allocated consecutive texture units beginning at the returned texture unit.

Discussion

The light probe textures are allocated consecutive texture units beginning at the returned texture unit.

Discussion

Normally this property is set during initialization. If you set this property directly, you must invoke the link method, and optionally, the prewarm method, once both shaders have been set via this property and the fragmentShader property.

Discussion

Returns YES if both the vertex and fragment shaders were loaded from files, otherwise returns NO.

Discussion

The specified program should be compiled and linked prior to being added here.

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

Depending on the value of the isPreloading property, the shader program may be held within this cache as a weak reference. As a result, the specified shader program may automatically be deallocated and removed from this cache once all external strong references to it have been released.

If the value of both the shouldAutomaticallyPreloadMatchingPureColorPrograms and isPreloading properties are set to YES, this method will ensure that a matching pure-color program is added to the cache for each regular program that is added. The pureColorProgramMatching: method, of the program matcher found in the class-side shaderMatcher property, is used to create the matching pure-color program.

Discussion

See the notes for the shouldAllowDefaultVariableValues property for a full discussion.

The initial value of this property is NO.

Discussion

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

Discussion

During development time, you can log this string, then copy and paste it into a pre-loading function within your app code to pre-load the shader programs for later use.

Discussion

If either shader has already been loaded, compiled, and cached, the cached shader will be reused, and will not be reloaded and recompiled from the file.

The specified file paths may be either absolute paths, or relative to the application resource directory. If the files are located directly in the application resources directory, the specified file paths can simply be the names of the files.

The semanticDelegate property is set to the default semantic delegate returned from the semanticDelegate property of the program matcher in the class-side shaderMatcher property.

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

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of the instance from the names of the vertex and fragment shaders, and to attempt to retrieve the program from the cache, prior to creating a new program.

To clear a program instance from the cache, use the removeProgram: method.

To create the program directly, bypassing the cache, use the alloc and initWithSemanticDelegate:fromVertexShaderFile:andFragmentShaderFile: methods. This technique can be used to create the same program twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately.

Discussion

This method is used to standardize the naming of programs, to ease in adding and retrieving programs to and from the cache.

Discussion

If either shader has already been loaded, compiled, and cached, the cached shader will be reused, and will not be reloaded and recompiled from the file.

The specified file paths may be either absolute paths, or relative to the application resource directory. If the files are located directly in the application resources directory, the specified file paths can simply be the names of the files.

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

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of the instance from the names of the vertex and fragment shaders, and to attempt to retrieve the program from the cache, prior to creating a new program.

To clear a program instance from the cache, use the removeProgram: method.

To create the program directly, bypassing the cache, use the alloc and initWithSemanticDelegate:fromVertexShaderFile:andFragmentShaderFile: methods. This technique can be used to create the same program twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately.

Discussion

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

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of the instance from the names of the vertex and fragment shaders, and to attempt to retrieve the program from the cache, prior to creating a new program.

To clear a program instance from the cache, use the removeProgram: method.

To create the program directly, bypassing the cache, use the alloc and initWithSemanticDelegate:withVertexShader:withFragmentShader: methods. This technique can be used to create the same program twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately.

Discussion

The semanticDelegate property is set to the default semantic delegate returned from the semanticDelegate property of the program matcher in the class-side shaderMatcher property.

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

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of the instance from the names of the vertex and fragment shaders, and to attempt to retrieve the program from the cache, prior to creating a new program.

To clear a program instance from the cache, use the removeProgram: method.

To create the program directly, bypassing the cache, use the alloc and initWithSemanticDelegate:withVertexShader:withFragmentShader: methods. This technique can be used to create the same program twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately.

Discussion

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

Discussion

See the notes for the shouldAllowDefaultVariableValues property for a full discussion.

The initial value of this property is NO.

Discussion

Shader programs 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 shader programs added to this cache while the value of this property is YES.

Shader programs 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 shader program outside this cache are released.

If you will be loading resources such as models and textures on a background thread while the scene is running, you will find that any shader programs that are loaded while the scene is running will often create a brief, but noticable, pause in the scene while the final stages of the shader program are conmpiled and configured.

You can avoid this pause by pre-loading all of the shader programs that your scene will need during scene initialization. They will then automatically be recalled from this cache when needed by the models that you load mid-scene. In order for them to be available in this cache at that time, the value of this property must be set to YES for the duration of the pre-loading stage during scene initialization.

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 shader programs will be weakly cached in this cache, and will automatically be removed if not used by a model. You can set this property to YES in order to pre-load shader programs that will not be immediately used in the scene, but which you wish to keep in the cache for later use.

Discussion

Rendering a mesh node requires a shader program. Typically, the shader program is assigned to the mesh node when the node is created or loaded from a model resource. This is either done by the resource loader, based on configuration information, or by the application directly, via the shaderProgram or shaderContext properties on the mesh node.

As a convenience, once a mesh node has been constructed and configured, the application can use the shader matcher in this property to retrieve a shader program suitable for rendering that node.

If the application does not assign a specific shader program to a mesh node, the shader matcher in this property will be accessed automatically to assign a shader program when the node is first rendered.

If desired, the application can set a custom shader matcher into this property. If the value of this property is not explicitly set by the application, it is lazily initialized to an instance of CC3ShaderMatcherBase, the first time it is accessed.

Discussion

If both this property and the isPreloading property are set to YES, the addProgram method will ensure that a matching pure-color shader program is added for each normal shader program that is added using that method.

If pre-loading is not active, each shader program is loaded dynamically the first time it is needed, and is added to the cache at that time. For such dynamically-loaded shader programs, the corresponding pure-color shader program will be dynamically loaded when it is needed, in turn. Typically this will be the first time node is involved in node picking as a result of a touch event.

The initial value of this property is YES, ensuring that a matching pure-color program will be added for each normal shader program that is added during pre-loading. Pure-color shader programs are used when rendering a node for picking from a touch-event. You should therefore leave the value of this property at its default value, unless your app does not use touch events to pick nodes.

Discussion

Rendering a mesh node requires a shader program. Typically, the shader program is assigned to the mesh node when the node is created or loaded from a model resource. This is either done by the resource loader, based on configuration information, or by the application directly, via the shaderProgram or shaderContext properties on the mesh node.

As a convenience, once a mesh node has been constructed and configured, the application can use the shader matcher in this property to retrieve a shader program suitable for rendering that node.

If the application does not assign a specific shader program to a mesh node, the shader matcher in this property will be accessed automatically to assign a shader program when the node is first rendered.

If desired, the application can set a custom shader matcher into this property. If the value of this property is not explicitly set by the application, it is lazily initialized to an instance of CC3ShaderMatcherBase, the first time it is accessed.

Discussion

If both this property and the isPreloading property are set to YES, the addProgram method will ensure that a matching pure-color shader program is added for each normal shader program that is added using that method.

If pre-loading is not active, each shader program is loaded dynamically the first time it is needed, and is added to the cache at that time. For such dynamically-loaded shader programs, the corresponding pure-color shader program will be dynamically loaded when it is needed, in turn. Typically this will be the first time node is involved in node picking as a result of a touch event.

The initial value of this property is YES, ensuring that a matching pure-color program will be added for each normal shader program that is added during pre-loading. Pure-color shader programs are used when rendering a node for picking from a touch-event. You should therefore leave the value of this property at its default value, unless your app does not use touch events to pick nodes.

Discussion

This method invokes the same method on each instance in the cache.

Discussion

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

Discussion

• If you do use this method directly, before invoking this method, you can invoke the class-side
• getProgramNamed: method to detemine whether a shader program with with a name derived from the
• programNameFromVertexShaderName:andFragmentShaderName: method already exists, and after invoking
• this method, you should use the class-side addProgram: method to add the new shader program
• instance to the program cache.

Discussion

• If you do use this method directly, before invoking this method, you can invoke the class-side
• getProgramNamed: method to detemine whether a shader program with with a name derived from the
• programNameFromVertexShaderName:andFragmentShaderName: method already exists, and after invoking
• this method, you should use the class-side addProgram: method to add the new shader program
• instance to the program cache.

Discussion

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of this instance from the names of the vertex and fragment shaders.

Since a single shader program can be used by many nodes and materials, shader programs are cached. Typically, this method is not invoked directly, and the programWithVertexShader:andFragmentShader: method is used instead.

If you do use this method directly, before invoking this method, you can invoke the class-side getProgramNamed: method, to detemine whether a shader program with a name derived from the programNameFromVertexShaderName:andFragmentShaderName: method already exists, and after invoking this method, you should use the class-side addProgram: method to add the new shader program instance to the program cache.

Discussion

The semanticDelegate property is set to the default semantic delegate returned from the semanticDelegate property of the program matcher in the class-side shaderMatcher property.

This method uses the programNameFromVertexShaderName:andFragmentShaderName: method to set the name of this instance from the names of the vertex and fragment shaders.

Since a single shader program can be used by many nodes and materials, shader programs are cached. Typically, this method is not invoked directly, and the programWithVertexShader:andFragmentShader: method is used instead.

If you do use this method directly, before invoking this method, you can invoke the class-side getProgramNamed: method, to detemine whether a shader program with a name derived from the programNameFromVertexShaderName:andFragmentShaderName: method already exists, and after invoking this method, you should use the class-side addProgram: method to add the new shader program instance to the program cache.

Discussion

The vertexShader, fragmentShader, and semanticDelegate properties must be set prior to invoking this method.

This method is automatically invoked during instance initialization if the vertex and fragment shaders are provided. If you create this instance without shaders and add them later, you can invoke this method once the vertexShader and fragmentShader properties have been set.

Discussion

Invoked automatically at the beginning of scene rendering.

Discussion

This method is lazily invoked by the populateNodeScopeUniformsWithVisitor method. Therefore, scene scope will be populated on each render pass when the first node that uses this program is rendered. Under normal operations, this method need never be explicitly invoked.

Discussion

The GL engine may choose to defer some final shader program compilation steps until the first time the shader program is used to render a mesh. This can cause the first frame of the first mesh drawn with the shader program to take significantly longer than subsequent renderings with that shader program, which can often result in a transient, but noticable, “freezing” of the scene. This is particularly apparent for new meshes that are added to the scene at any point other than during scene initialization.

To avoid this, this method can be invoked to cause this shader program to render a small mesh to an off-screen rendering surface, in order to force this shader program to perform its final compilation and linking steps at a controlled, and predicatble, time.

This method is automatically invoked during instance initialization if the vertex and fragment shaders are provided. If you create this instance without shaders and add them later, you can invoke this method once the vertexShader and fragmentShader properties have been set, and the link method has been invoked.

Prewarming is always performed on shader programs loaded on the background thread, but is only performed on shader programs loaded on the foreground thread during the preloading phase. This is to avoid prewarming activity during lazy loading of shader programs during rendering.

Discussion

Invokes the markSceneScopeDirty method to mark the scene scope variables as dirty and in need of re-populating.