|
Synergy Color Management Component - SDK -
2018.0.80
|
Public Types | |
| enum | ShaderLanguage { LANGUAGE_GLSL = 0, LANGUAGE_CG, LANGUAGE_HLSL, LANGUAGE_GLSL_CORE } |
| enum | PipelineType { PIPELINE_RGBA_FLOAT = 0 } |
| enum | UniformType { UNIFORM_DOUBLE = 0, UNIFORM_BOOL } |
Public Member Functions | |
| GPUAdaptor (ShaderLanguage lang, PipelineType pipeline) | |
| Constructor. More... | |
| virtual | ~GPUAdaptor () |
| Destructor. More... | |
| virtual const char * | getUniqueId () const =0 |
| Adaptor unique ID. More... | |
| virtual GPUAdaptorPtr | clone () const =0 |
| Clone the GPU Adaptor. More... | |
| virtual SynStatus | begin (const char *uid) |
| Perform any GPU toolkit specific set-up for creating shader programs. More... | |
| virtual SynStatus | end () |
| Perform any GPU toolkit specific cleanup following shader program creation. More... | |
| virtual const char * | getResourcesNamesPrefix () const =0 |
| Prefix for uniquely identifying resources names. More... | |
| virtual SynStatus | acquireProgram ()=0 |
| Create and store a GPU program handle. More... | |
| virtual SynStatus | releaseProgram ()=0 |
| Clear any GPU resources held by the adaptor. More... | |
| virtual SynStatus | buildProgram (const char *shaderDeclarations, const char *shaderHelperMethods, const char *shaderMainHeader, const char *shaderMainBody, const char *shaderMainFooter)=0 |
| Build a shader program and finalize its associated resources. More... | |
| virtual SynStatus | acquireUniform (DynamicProperty::Ids id, const char *name, UniformType type, const void *value)=0 |
| Create a uniform variable of the specified type. More... | |
| virtual SynStatus | getTextureDimensions (unsigned numValues, unsigned &width, unsigned &height)=0 |
| Calculate the width and height of a texture to hold the given texture size. More... | |
| virtual SynStatus | acquire1DTexture (const char *name, const void *values, unsigned size)=0 |
| Create and store a linear texture. More... | |
| virtual SynStatus | acquire2DTexture (const char *name, unsigned width, unsigned height, const void *values)=0 |
| Create and store a planar texture. More... | |
| virtual SynStatus | acquire3DTexture (const char *name, unsigned dim, bool linearInterpolation, const void *values, unsigned size)=0 |
| Create and store a volumetric texture. More... | |
| virtual SynStatus | acquireInputTexture ()=0 |
| Obtain any input texture related resources. More... | |
| virtual const char * | getInputTextureName () const =0 |
| Obtain the input texture name. More... | |
| virtual SynStatus | drawQuad (unsigned inTexHandle, const SYNCOLOR::Vertices &texCoords, const SYNCOLOR::Vertices &screenCoords) const =0 |
| Render into the currently active destination render buffer. More... | |
| ShaderLanguage | getShaderLanguage () const |
| Shader language configured. More... | |
Protected Member Functions | |
| PipelineType | _getPipelineType () const |
| GPU pipeline type configured. More... | |
Private Attributes | |
| ShaderLanguage | _lang |
| Shader language for constructing the color transform shader. More... | |
| PipelineType | _pipelineType |
| GPU pipeline type for which the color transform shader is built. More... | |
When finalizing a color transform for rendering, SynColor can create a GPU renderer for the the transform. When this is requested, a GPU shader program that implements the color transform rendering is built. The shader can be applied to the active graphics frame buffer via the SYNCOLOR::Transform::applyGPU call.
To achieve this SynColor requires a GPU adaptor at transform finalization. GPU adaptors for OpenGL using the GLSL or the Cg shader languages are available and a GPU adaptor for DirectX 11 using HLSL is in the works. If it is necessary to use a different graphics toolkit or if the adaptor behavior is not adequate for the intended application then a custom GPU adaptor needs to be written. The following information explains the calling sequence of adaptor methods. See each method description for details about their intent.
GPU adaptor method call sequence:
Setup phase methods:
begin() // Perform any required set-up.
releaseProgram() // Clear any GPU resources held by the adaptor.
acquireInputTexture() // Obtain any input texture related resources.
getInputTextureName() // Obtain the string corresponding to the input texture resource name.
For each color operator in the transform any of these methods could be called:
getResourceNamePrefix() // Obtain a prefix to use for all GPU resources.
getTextureDimensions() // Calculate the width and height of a texture to hold the given texture size.
acquireUniform() // Create and store a uniform variable of the specified type. See UniformType.
acquire1DTexture() // Create and store a linear texture.
acquire2DTexture() // Create and store a planar texture.
acquire3DTexture() // Create and store a volumetric texture.
GPU shader program finalization methods:
acquireProgram() // Create and store a GPU program handle.
buildProgram() // Compile and link the shader program.
end() // Perform any specific clean up.
Method used when calling SYNCOLOR::Transform::applyGPU():
drawQuad() // Render into the currently active destination render buffer.
All GPU adaptor methods are required to return a SYNCOLOR::SynStatus. An error code other that SYNCOLOR::ERROR_NONE will cause the SYNCOLOR::finalize or SYNCOLOR::Transform::applyGPU calls to abort and return the error as well. A special error code is reserved for GPU adaptor errors. If the GPU adaptor method encounters an error, the SYNCOLOR::SynStatus usage pattern should be as follows:
SYNCOLOR::SynStatus status; // Initialized to SYNCOLOR::ERROR_NONE.
...
if(<error condition>) {
status.setErrorCode(SYNCOLOR::ERROR_RENDERER_GPU_ADAPTOR_ERROR);
status.setErrorMessage(<error message string>);
}
return status;
On the application side, the error message can be retrieved by calling SYNCOLOR::SynStatus::getErrorMessage().
List of supported shader languages.
| Enumerator | |
|---|---|
| LANGUAGE_GLSL |
GLSL. |
| LANGUAGE_CG |
Cg. |
| LANGUAGE_HLSL |
HLSL. |
| LANGUAGE_GLSL_CORE |
GLSL Core profile. |
List of supported GPU pipelines.
| Enumerator | |
|---|---|
| PIPELINE_RGBA_FLOAT |
Only floating point RGBA GPU pipelines are supported. |
List of supported uniform types.
| Enumerator | |
|---|---|
| UNIFORM_DOUBLE |
Double. |
| UNIFORM_BOOL |
Boolean. |
| SYNCOLOR::GPUAdaptor::GPUAdaptor | ( | ShaderLanguage | lang, |
| PipelineType | pipeline | ||
| ) |
Constructor.
| lang | Adaptor shader language. |
| pipeline | Adaptor GPU pipeline type. |
|
virtual |
Destructor.
|
pure virtual |
Adaptor unique ID.
This function is used as a key in the SynColor caching system. Each GPU adaptor instance should return a different ID.
|
pure virtual |
Clone the GPU Adaptor.
This method needs to return a copy of 'this' GPUAdaptor.
|
virtual |
Perform any GPU toolkit specific set-up for creating shader programs.
This method is always called before any other adaptor method when finalizing a color transform. The default implementation simply returns without error.
| uid | Transform unique id. See Transfor::getUniqueId(). |
|
virtual |
Perform any GPU toolkit specific cleanup following shader program creation.
This method is the last one called when finalizing a transform. It is always called when an adaptor method returns an error. The default implementation simply returns without error.
|
pure virtual |
Prefix for uniquely identifying resources names.
Some applications may require that textures, uniforms, and helper methods be uniquely named. If this is the case the implementation of this method needs to return a prefix unique to the GPUAdaptor instance.
A unique prefix would be necessary for example if the shader code from multiple color transform need to be integrated into a larger shader program. In this case the resources need to be uniquely identified.
|
pure virtual |
Create and store a GPU program handle.
In the OpenGL model, this method corresponds to a call to glCreateProgram().
|
pure virtual |
Clear any GPU resources held by the adaptor.
The intent of this method is to release any textures and uniforms created by the adaptor instance. It also needs to delete the shader program.
|
pure virtual |
Build a shader program and finalize its associated resources.
This method receives the shader program text pieces for compilation or integration into another shader program. The pieces provided are the variable and resource declarations, the helper methods, and the color transform shader program header, body, and footer.
An OpenGL implementation of this methods that produces a single shader program to render the color transform would for example concatenate the shader text pieces and build the shader program via glCompileShader() and glLinkProgram().
| shaderDeclarations | Variable and resource declaration text. |
| shaderHelperMethods | Helper function definitions text. |
| shaderMainHeader | Color transform shader header text. |
| shaderMainBody | Color transform shader body text. |
| shaderMainFooter | Color transform shader text footer. |
|
pure virtual |
Create a uniform variable of the specified type.
Uniforms in color transforms correspond to dynamic properties of the transforms such as exposure or contrast. Changes to the values of these properties need to be updated prior to rendering the transform. The GPU adaptor needs to retain the memory location of the uniform value and apply its content to the uniform in the drawQuad() method. Dynamic property values are updated via the SYNCOLOR::Transform::setDynamicProperty call.
| id | Dynamic property id for this uniform. See DynamicProperty::Ids. |
| name | Uniform name. |
| type | Uniform type |
| value | Memory location of the uniform value. Corresponds to a pointer of the uniform type. |
|
pure virtual |
Calculate the width and height of a texture to hold the given texture size.
When deciding whether to use a 1-d or 2-d texture to hold a look-up table, SynColor needs a hint. The implementation of this method needs to provide, based on the GPU toolkit or GPU device constraints, the width and height of a texture that will hold the specified number of values.
If the height returned is 1, SynColor will request a 1-d texture via the acquire1DTexture() adaptor method. Otherwise, acquire2DTexture() will be called to create a 2-d texture.
| numValues | Number of values that the texture needs to hold. |
| width | Texture width return value. |
| height | Texture height return value. |
|
pure virtual |
Create and store a linear texture.
The GPU adaptor needs to retain the handle to the texture and release it in the releaseProgram() call.
| name | Texture name. |
| values | Values to copied into the texture. |
| size | Number of texture values. |
|
pure virtual |
Create and store a planar texture.
The GPU adaptor needs to retain the handle to the texture and release it in the releaseProgram() call.
| name | Texture name. |
| width | Texture width. |
| height | Texture height. |
| values | Values to be copied into the texture. |
|
pure virtual |
Create and store a volumetric texture.
The GPU adaptor needs to retain the handle to the texture and release it in the releaseProgram() call.
| name | Texture name. |
| dim | Texture dimension. The texture will be of size dim x dim x dim. |
| linearInterpolation | Whether linear interpolation of texel values is needed. |
| values | Values to be copied into the texture. |
| size | Values buffer size. |
|
pure virtual |
Obtain any input texture related resources.
This method needs to create the input texture name to be used in the shader program.
|
pure virtual |
Obtain the input texture name.
The input texture name is needed for inclusion in the shader declaration text.
|
pure virtual |
Render into the currently active destination render buffer.
This method is for applying the color transform shader on the input texture. The input texture provided is mapped to the input texture name supplied by getInputTextureName().
| inTexHandle | Input texture handle. |
| texCoords | Input texture coordinates. |
| screenCoords | Destination screen coordinates. |
| ShaderLanguage SYNCOLOR::GPUAdaptor::getShaderLanguage | ( | ) | const |
Shader language configured.
The shader language is specified at the constructor.
|
protected |
GPU pipeline type configured.
The pipeline type is specified at the constructor.
|
private |
Shader language for constructing the color transform shader.
|
private |
GPU pipeline type for which the color transform shader is built.