v2.0.2
|
|
v2.0.2
|
#import <CC3Shaders.h>
Instance Methods | |
| (void) | - accumulateSourceCompilationStringCountWithVisitor: |
| (void) | - accumulateSourceCompilationStringsWithVisitor: |
| (void) | - appendSourceCodeString: |
| (NSString *) | - constructorDescription |
| (BOOL) | - localizeLineNumberWithVisitor: |
| (void) | - remove |
 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) | + addShaderSourceCode: |
| (CC3ShaderSourceCode *) | + getShaderSourceCodeNamed: |
| (BOOL) | + isPreloading |
| (NSString *) | + loadedShaderSourceCodeDescription |
| (void) | + removeAllShaderSourceCode |
| (void) | + removeShaderSourceCode: |
| (void) | + removeShaderSourceCodeNamed: |
| (void) | + setIsPreloading: |
| (void) | + setSourceCodeSubsectionClass: |
| (id) | + shaderSourceCodeFromFile: |
| (NSString *) | + shaderSourceCodeNameFromFilePath: |
| (id) | + shaderSourceCodeWithName:fromSourceCodeString: |
| (Class) | + sourceCodeSubsectionClass |
| Class Methods inherited from CC3Identifiable | |
| (GLint) | + instanceCount |
| (void) | + resetTagAllocation |
Properties | |
| NSString * | importableSourceCodeString |
| GLuint | lineCount |
| NSString * | sourceCodeString |
| GLuint | sourceStringCount |
| NSArray * | subsections |
| 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 |
A CC3ShaderSourceCode instance contains shader source code.
CC3ShaderSourceCode is the visible class of a class-cluster. The actual class created and returned during instantitation from source code will depend on the structure of the source code.
Modular shader code is supported through the use of #import and #include statements. Shader source code loaded using this class cluster may contain #import and #include statements to load additional code in-place from other source code files. Importing may be nested to any level. The loading mechanism ensures that each source code file is only imported once, so the same source code library file may be imported into several files within the same load.
Since a single source code file can be imported by multiple other source code files, shader source code instances are cached, and are retrieved automatically from the cache when another instance imports it. In this way, source code text does not need to be duplicated in order to be imported into multiple, nested source code trees.
| - (void) accumulateSourceCompilationStringCountWithVisitor: | (CC3ShaderSourceCodeCompilationStringCountVisitor *) | visitor |
Uses the specified visitor to accumulate the total number of source code strings that will be submitted to the shader compiler.
Invokes the addSourceCompilationStringCount: method on the visitor to provide the number of source code strings that are being managed by this instance.
The mechanism for managing the source code sections depends on the subclass.
| - (void) accumulateSourceCompilationStringsWithVisitor: | (CC3ShaderSourceCodeCompilationStringVisitor *) | visitor |
Uses the specified visitor to accumulate the collection of source code strings that will be submitted to the shader compiler.
Invokes the addSourceCompilationString: method on the visitor for each source code string managed by this instance.
The mechanism for managing the source code sections depends on the subclass.
| + (void) addShaderSourceCode: | (CC3ShaderSourceCode *) | shader |
Adds the specified shader source to the collection of loaded shader sources.
Shader sources are accessible via their names through the getShaderSourceNamed: method, and each shader source name should be unique. If a shader source 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 source may be held within this cache as a weak reference. As a result, the specified shader source may automatically be deallocated and removed from this cache once all external strong references to it have been released.
| - (void) appendSourceCodeString: | (NSString *) | srcCode |
Appends the specified source code section to the source code managed by this instance.
Depending on how the source code is being parsed, the specfied string may contain any amount of source code, but will typically contain a single line of code.
The mechansim for organizing the various source code sections submitted through this method is defined by each subclass.
| - (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 shader sources individually. However, normally, your shader sources will be loaded, compiled, and cached as a result of creating a shader program.
| + (CC3ShaderSourceCode*) getShaderSourceCodeNamed: | (NSString *) | name |
Returns the shader source with the specified name, or nil if a shader source with that name has not been added.
| + (BOOL) isPreloading |
Returns whether shader sources are being pre-loaded.
See the setIsPreloading setter method for a description of how and when to use this property.
| + (NSString*) loadedShaderSourceCodeDescription |
Returns a description of the source code in this cache that was loaded from files, with each entry formatted as a source-code line for loading the 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 shader source code individually. However, normally, your source code will be loaded and cached as a result of creating a shader program.
| - (BOOL) localizeLineNumberWithVisitor: | (CC3ShaderSourceCodeLineNumberLocalizingVisitor *) | visitor |
This callback method is invoked during error handling, to determine the file and location within that file at which the error occurred.
If this instance contains the source of the error, the lineNumber and localizedSourceCode properties of the visitor are set, and this method returns YES. Otherwise, this method adjusts other properties within the visitor, to manage the traversal of the sourcde code, and returns NO.
| - (void) remove |
Removes this shader source instance from the cache.
| + (void) removeAllShaderSourceCode |
Removes from the cache all shader sources that are instances of any subclass of the receiver.
Removing cached shader sources does not affect the operation of shaders that have been compiled into a CC3Shader. It is common to invoke this method after you have compiled all of your CC3Shaders that use the currently loaded shader sources.
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 CC3ShaderSourceCode 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) removeShaderSourceCode: | (CC3ShaderSourceCode *) | shader |
Removes the specified shader source from the shader cache.
If the shader source 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) removeShaderSourceCodeNamed: | (NSString *) | name |
Removes the shader source with the specified name from the shader source 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 shader sources are being pre-loaded.
Shader sources 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 sources added to this cache while the value of this property is YES.
Shader sources 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 shader sources will be weakly cached in this cache, and will automatically be removed if not compiled into a shader. You can set this property to YES in order to pre-load shader sources that will not be immediately used in the scene, but which you wish to keep in the cache for later use.
| + (void) setSourceCodeSubsectionClass: | (Class) | sourceCodeSubsectionClass |
As shader source code is parsed and assembled using #import and #include directives, sections of code that do not require importing other code, are wrapped in an instance of a CC3ShaderSourceCode subclass.
This class-side property indicates the class to instantiate for each section of GLSL code.
This propery must be set to a CC3ShaderSourceCode subclass.
The initial value of this property is the CC3ShaderSourceCodeString class.
| + (id) shaderSourceCodeFromFile: | (NSString *) | filePath |
Returns an instance containing 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.
Source code loaded through this method is cached. If the source code was already loaded and is in the cache, it is retrieved and returned. If the source code is 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 source code is needed, without having to worry that it will be repeatedly loaded from file.
To clear a source code instance from the cache, use the removeShaderSourceCode: method.
CC3ShaderSourceCode is the abstract head of a class cluster. The class of the object returned will be a subclass of CC3ShaderSourceCode, depending on the structure of the source code.
| + (NSString*) shaderSourceCodeNameFromFilePath: | (NSString *) | filePath |
Returns a shader source code name derived from the specified file path.
This method is used to standardize the naming of shader source code instances, to ease in adding and retrieving shader source code to and from the cache, and is used to create the name for each shader source code instance that is loaded from a file.
This implementation returns the lastComponent of the specified file path.
| + (id) shaderSourceCodeWithName: | (NSString *) | name | |
| fromSourceCodeString: | (NSString *) | srcCodeString | |
Returns an instance with the specified name and containing the 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.
Source code instances created through this method are cached. If source code with the specified name is already in the cache, it is retrieved and returned. If the source code is not in the cache, it is created from the specified source code, placed into the cache, and returned. It is therefore safe to invoke this method any time the source code is needed, without having to worry that the shader will be repeatedly loaded.
To clear a source code instance from the cache, use the removeShaderSourceCode: method.
CC3ShaderSourceCode is the abstract head of a class cluster. The class of the object returned will be a subclass of CC3ShaderSourceCode, depending on the structure of the source code.
| + (Class) sourceCodeSubsectionClass |
As shader source code is parsed and assembled using #import and #include directives, sections of code that do not require importing other code, are wrapped in an instance of a CC3ShaderSourceCode subclass.
This class-side property indicates the class to instantiate for each section of GLSL code.
This propery must be set to a CC3ShaderSourceCode subclass.
The initial value of this property is the CC3ShaderSourceCodeString class.
|
readnonatomicassign |
If the value of the wasLoadedFromFile property is NO, returns the value of the sourceCodeString property.
If the value of the wasLoadedFromFile property is YES, returns an equivalent #import "filename" directive.
|
readnonatomicassign |
Returns the number of lines in this source code.
|
readnonatomicassign |
Returns the source code as a string.
|
readnonatomicassign |
Returns the number of source code strings that will be submitted to the shader compiler.
|
readnonatomicassign |
Returns the collection of source code subsections.
Each member of the returned collection is an instance of CC3ShaderSourceCode.
This property will return nil if the source code contains no subsections.
|
readwritenonatomicassign |
Indicates whether this source code was loaded from a file.
The value of this property is automatically set by the allocation and instantiation methods that load this source code from a file.