v2.0.2
|
|
v2.0.2
|
#import <CC3Shaders.h>
Instance Methods | |
| (void) | - compileFromSourceCode: |
| (void) | - compileFromSourceCodeString: |
| (NSString *) | - constructorDescription |
| (id) | - initFromSourceCode: |
| (id) | - initFromSourceCodeFile: |
| (id) | - initWithName:fromSourceCode: |
| (void) | - remove |
| (GLenum) | - shaderType |
 Instance Methods inherited from CC3Identifiable | |
| (void) | - __deprecated |
| (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) | + addShader: |
| (CC3Shader *) | + getShaderNamed: |
| (BOOL) | + isPreloading |
| (NSString *) | + loadedShadersDescription |
| (void) | + removeAllShaders |
| (void) | + removeShader: |
| (void) | + removeShaderNamed: |
| (void) | + setIsPreloading: |
| (id) | + shaderFromPFXShader:inPFXResource: |
| (id) | + shaderFromSourceCodeFile: |
| (NSString *) | + shaderNameFromFilePath: |
| (id) | + shaderWithName:fromSourceCode: |
| Class Methods inherited from CC3Identifiable | |
| (GLint) | + instanceCount |
| (void) | + resetTagAllocation |
Properties | |
| CC3ShaderSourceCode * | defaultShaderPreamble |
| NSString * | defaultShaderPreambleString |
| GLuint | shaderID |
| CC3ShaderSourceCode * | shaderPreamble |
| NSString * | shaderPreambleString |
| BOOL | wasLoadedFromFile |
| 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 |
CC3Shader represents an OpenGL shader, compiled from GLSL source code.
CC3Shader is an abstract class, and has two concrete classes: CC3VertexShader and CC3FragmentShader.
Since a single shader can be used by more than one shader program, shaders are cached, and are retrieved automatically when a CC3ShaderProgram that requires the shaders is created. Typically, the application does not create instances of CC3Shader directly.
| + (void) addShader: | (CC3Shader *) | shader |
Adds the specified shader to the collection of loaded shaders.
The specified shader should be compiled prior to being added here.
Shaders are accessible via their names through the getShaderNamed: method, and each shader name should be unique. If a shader with the same name as the specified shader already exists in this cache, an assertion error is raised.
Depending on the value of the isPreloading property, the shader may be held within this cache as a weak reference. As a result, the specified shader may automatically be deallocated and removed from this cache once all external strong references to it have been released.
| - (void) compileFromSourceCode: | (CC3ShaderSourceCode *) | shSrcCode |
Compiles this shader from the specified shader source code, and returns whether compilation was successful.
The value of the shaderPreamble property is prepended to the specified source code prior to compiling.
| - (void) compileFromSourceCodeString: | (NSString *) | srcCodeString |
Compiles this shader from the specified GLSL source code, and returns whether compilation was successful.
The value of the shaderPreamble property is prepended to the specified source code prior to compiling.
The implementation of this method creates a CC3ShaderSourceCode instance from the specified source code string and then invokes the compileFromSourceCode: method.
| - (NSString*) constructorDescription |
Returns a description formatted as a source-code line for loading this shader from a source code file.
During development time, you can log this string, then copy and paste it into a pre-loading function within your app code, if you want to load shaders individually. However, normally, your shaders will be loaded, compiled, and cached as a result of creating a shader program.
| + (CC3Shader*) getShaderNamed: | (NSString *) | name |
Returns the shader with the specified name, or nil if a shader with that name has not been added.
| - (id) initFromSourceCode: | (CC3ShaderSourceCode *) | shSrcCode |
Initializes this instance compiled from GLSL source code in the specified shader source code,.
Prior to compiling, the value of the shaderPreamble property is prepended to the the specified shader source code.
The name of this instance is set to the name of the specified shader source code, and the tag is set to an automatically generated unique tag value.
The specified shader source code may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
Since a single shader can be used by many shader programs, shaders are cached. Typically, this method is not invoked directly, and the shaderFromSourceCodeFile: method is used instead.
If you do use this method directly, before invoking this method, you can invoke the class-side getShaderNamed: method to detemine whether a shader with the name of the specified shader source already exists, and after invoking this method, you should use the class-side addShader: method to add the new shader instance to the shader cache.
If you want to set properties prior to compiling the source code, you can create an instance without compiling code by using one of the initialization methods defined by the superclass (eg- initWithName:), set properties such as the shaderPreamble, and then invoke the compileFromSource: method to compile this shader from GLSL source code.
| - (id) initFromSourceCodeFile: | (NSString *) | filePath |
Initializes this instance compiled from GLSL source code loaded from 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.
The specified shader source code may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
Since a single shader can be used by many shader programs, shaders are cached. Typically, this method is not invoked directly, and the shaderFromSourceCodeFile: method is used instead.
If you do use this method directly, before invoking this method, you can invoke the class-side getShaderNamed: method to detemine whether a shader with the specified filename already exists, and after invoking this method, you should use the class-side addShader: method to add the new shader instance to the shader cache.
If you want to set properties prior to compiling the source code, you can create an instance without compiling code by using one of the initialization methods defined by the superclass (eg- initWithName:), set properties such as the shaderPreamble, and then invoke the compileFromSource: method to compile this shader from GLSL source code.
| - (id) initWithName: | (NSString *) | name | |
| fromSourceCode: | (NSString *) | srcCodeString | |
Initializes this instance with the specified name and compiles this instance from the specified GLSL source code.
The value of the shaderPreambleString property is prepended to the specified source code prior to compiling.
The specified shader source code may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
Since a single shader can be used by many shader programs, shaders are cached. Before invoking this method, you should invoke the class-side getShaderNamed: method to detemine whether a shader with the specified name exists already, and after invoking this method, you should use the class-side addShader: method to add the new GL program instance to the shader cache.
If you want to set properties prior to compiling the source code, you can create an instance without compiling code by using one of the initialization methods defined by the superclass (eg- initWithName:), set properties such as the shaderPreamble, and then invoke the compileFromSource: to compile this shader from GLSL source code.
| + (BOOL) isPreloading |
Returns whether shaders are being pre-loaded.
See the setIsPreloading setter method for a description of how and when to use this property.
| + (NSString*) loadedShadersDescription |
Returns a description of the shaders in this cache that were loaded from files, with each entry formatted as a source-code line for loading the shader 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, if you want to load shaders individually. However, normally, your shaders will be loaded, compiled, and cached as a result of creating a shader program.
| - (void) remove |
Removes this shader instance from the cache.
| + (void) removeAllShaders |
Removes from the cache all shaders that are instances of any subclass of the receiver.
Removing cached shaders does not affect the operation of shaders that have been linked into a CC3ShaderProgram. It is common to invoke this method after you have created all of your CC3ShaderPrograms from the loaded shaders.
You can use this method to selectively remove specific types of shaders, based on the shader class, by invoking this method on that class. If you invoke this method on the CC3Shader class, this cache will be compltely cleared. However, if you invoke this method on one of its subclasses, only those shaders that are instances of that subclass (or one of its subclasses in turn) will be removed, leaving the remaining shaders in the cache.
| + (void) removeShader: | (CC3Shader *) | shader |
Removes the specified shader from the shader cache.
If the shader is not strongly referenced elsewhere, it will be deallocated, and will be removed from the GL engine.
Removing a shader from the GL engine does not affect the operation of shaders that have been linked into a CC3ShaderProgram. It is common to remove shaders after you have created all of the CC3ShaderPrograms that will use that shader.
| + (void) removeShaderNamed: | (NSString *) | name |
Removes the shader with the specified name from the shader cache.
If the shader is not strongly referenced elsewhere, it will be deallocated, and will be removed from the GL engine.
Removing a shader from the GL engine does not affect the operation of that shader if it has been linked into a CC3ShaderProgram. It is common to remove shaders after you have created all of the CC3ShaderPrograms that will use that shader.
| + (void) setIsPreloading: | (BOOL) | isPreloading |
Sets whether shaders are being pre-loaded.
Shaders 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 shaders added to this cache while the value of this property is YES.
Shaders 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.
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 shaders will be weakly cached in this cache, and will automatically be removed if not used by a shader program. You can set this property to YES in order to pre-load shaders that will not be immediately used in the scene, but which you wish to keep in the cache for later use.
| + (id) shaderFromPFXShader: | (PFXClassPtr) | pSPVRTPFXParserShader | |
| inPFXResource: | (CC3PFXResource *) | pfxRez | |
Returns an instance compiled from GLSL source code identified by the specified PFX shader specification in the specified PFX resource loader.
Shaders loaded through this method are cached. If the shader was already loaded and is in the cache, it is retrieved and returned. If the shader has not in the cache, it is created compiled from GLSL code identified by the specified PFX shader specification, and added to the shader cache. It is safe to invoke this method any time the shader is needed, without having to worry that the shader will be repeatedly loaded and compiled.
If the shader is created and compiled, the GLSL code may be embedded in the PFX file, or may be contained in a separate GLSL source code file, as defined by the PFX shader spec.
To clear a shader instance from the cache, use the removeShader: method.
Provided by category CC3Shader(PFXEffects).
| + (id) shaderFromSourceCodeFile: | (NSString *) | filePath |
Returns an instance compiled from GLSL source code loaded from the 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.
The specified shader source code may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
Shaders loaded through this method are cached. If the shader was already loaded and is in the cache, it is retrieved and returned. If the shader 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 shader is needed, without having to worry that the shader will be repeatedly loaded from file.
To clear a shader instance from the cache, use the removeShader: method.
To load the file directly, bypassing the cache, use the alloc and initFromSourceCodeFile: methods. This technique can be used to load the same shader twice, if needed for some reason. Each distinct instance can then be given its own name, and added to the cache separately.
If you want to set properties prior to compiling the source code, you can create an instance without compiling code by using one of the initialization methods defined by the superclass (eg- initWithName:), set properties such as the shaderPreamble, and then invoke the compileFromSource: method to compile this shader from GLSL source code. Once compiled, you can add the shader to the cache using the addShader: method.
| + (NSString*) shaderNameFromFilePath: | (NSString *) | __deprecated |
| - (GLenum) shaderType |
Returns the type of shader, either GL_VERTEX_SHADER or GL_FRAGMENT_SHADER.
| + (id) shaderWithName: | (NSString *) | name | |
| fromSourceCode: | (NSString *) | srcCodeString | |
Returns an instance with the specified name and compiled from specified GLSL source code.
The specified shader source code may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
Shaders loaded through this method are cached. If a shader with the specified name is already in the cache, it is retrieved and returned. If the shader has not in the cache, it is compiled from the specified source code, placed into the cache, and returned. It is therefore safe to invoke this method any time the shader is needed, without having to worry that the shader will be repeatedly compiled.
To clear a shader instance from the cache, use the removeShader: method.
To instantiate and compile a new shader directly, bypassing the cache, use the alloc and initWithName:fromSourceCode: methods.
If you want to set properties prior to compiling the source code, you can create an instance without compiling code by using one of the initialization methods defined by the superclass (eg- initWithName:), set properties such as the shaderPreamble, and then invoke the compileFromSource: method to compile this shader from GLSL source code. Once compiled, you can add the shader to the cache using the addShader: method.
|
readnonatomicretain |
Returns the shader source object containing GLSL source code to be used as a default preamble for the source code of the shader.
The value of this property defines the initial value of the shaderPreamble property.
To allow platform-specific requirements, the value of this property is retrieved from CC3OpenGL.sharedGL.defaultShaderPreamble, and contains platform-specific defines.
In addition, for OpenGL on the OSX platform, this property contains define statements to remove any precision qualifiers of all variables in the GLSL source code and to set the GLSL #version declaration.
Subclasses may override this property to return additional shader preamble content, such as standard define statements, etc. Subclasses may find it easier to override the defaultShaderPreambleString property instead.
This preamble may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
|
readnonatomicretain |
Returns a string containing GLSL source code to be used as a default preamble for the source code of the shader.
The value of this property defines the initial value of the shaderPreambleString property.
To allow platform-specific requirements, the value of this property is retrieved from CC3OpenGL.sharedGL.defaultShaderPreamble, and contains platform-specific defines.
In addition, for OpenGL on the OSX platform, this property contains define statements to remove any precision qualifiers of all variables in the GLSL source code and to set the GLSL #version declaration.
Subclasses may override this property to return additional shader preamble content, such as standard define statements, etc.
This preamble may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
|
readnonatomicassign |
Returns the GL shader ID.
|
readwritenonatomicretain |
The shader source code object associated with the shaderPreambleString property.
You can set the shader preamble source code by either setting this property or setting the shaderPreambleString property.
This preamble may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
|
readwritenonatomicretain |
A string containing GLSL source code to be used as a preamble for the source code of this shader.
The value of this property can be set prior to invoking the compileFromSourceCode: or compileFromSourceCodeString: method. The content of this propery will be prepended to the shader source code. You can use this property to include compiler builds settings, and other delarations.
This preamble may contain #import or #include directives to load additional source code from other files. The #import and #include directives perform identically. Regardless of which you choose to use, if the same file is imported or included more than once (perhaps through nesting), the loader will ensure that only one copy of each source file is loaded.
This is a convenience property that uses the shaderPreamble property to actually hold the preamble source code. Setting this property also changes the contents of theshaderPreamble property. Reading this property retrieves a string representation of the preamble source code held in the shaderPreamble property.
The initial value of this property is set to the value of the defaultShaderPreambleString property. If you change this property, you should usually concatenate the value of the defaultShaderPreambleString property to the additional preamble content that you require.
|
readnonatomicassign |
Indicates whether this shader was loaded from a file.
The value of this property is automatically set by the allocation and instantiation methods that load this shader from a file.