Synergy Color Management Component - SDK -  2018.0.80
SYNCOLOR::GPUAdaptor Class Referenceabstract

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...
 

Detailed Description

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().

Member Enumeration Documentation

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.

Constructor & Destructor Documentation

SYNCOLOR::GPUAdaptor::GPUAdaptor ( ShaderLanguage  lang,
PipelineType  pipeline 
)

Constructor.

Parameters
langAdaptor shader language.
pipelineAdaptor GPU pipeline type.
virtual SYNCOLOR::GPUAdaptor::~GPUAdaptor ( )
virtual

Destructor.

Member Function Documentation

virtual const char* SYNCOLOR::GPUAdaptor::getUniqueId ( ) const
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.

Returns
virtual GPUAdaptorPtr SYNCOLOR::GPUAdaptor::clone ( ) const
pure virtual

Clone the GPU Adaptor.

This method needs to return a copy of 'this' GPUAdaptor.

Returns
Cloned instance.
virtual SynStatus SYNCOLOR::GPUAdaptor::begin ( const char *  uid)
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.

Parameters
uidTransform unique id. See Transfor::getUniqueId().
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::end ( )
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.

Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual const char* SYNCOLOR::GPUAdaptor::getResourcesNamesPrefix ( ) const
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.

Returns
Resource name prefix unique to the GPUAdaptor instance.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquireProgram ( )
pure virtual

Create and store a GPU program handle.

In the OpenGL model, this method corresponds to a call to glCreateProgram().

Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::releaseProgram ( )
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.

Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::buildProgram ( const char *  shaderDeclarations,
const char *  shaderHelperMethods,
const char *  shaderMainHeader,
const char *  shaderMainBody,
const char *  shaderMainFooter 
)
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().

Parameters
shaderDeclarationsVariable and resource declaration text.
shaderHelperMethodsHelper function definitions text.
shaderMainHeaderColor transform shader header text.
shaderMainBodyColor transform shader body text.
shaderMainFooterColor transform shader text footer.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquireUniform ( DynamicProperty::Ids  id,
const char *  name,
UniformType  type,
const void *  value 
)
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.

Parameters
idDynamic property id for this uniform. See DynamicProperty::Ids.
nameUniform name.
typeUniform type
valueMemory location of the uniform value. Corresponds to a pointer of the uniform type.
See also
UniformType, drawQuad().
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::getTextureDimensions ( unsigned  numValues,
unsigned &  width,
unsigned &  height 
)
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.

Parameters
numValuesNumber of values that the texture needs to hold.
widthTexture width return value.
heightTexture height return value.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquire1DTexture ( const char *  name,
const void *  values,
unsigned  size 
)
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.

Parameters
nameTexture name.
valuesValues to copied into the texture.
sizeNumber of texture values.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquire2DTexture ( const char *  name,
unsigned  width,
unsigned  height,
const void *  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.

Parameters
nameTexture name.
widthTexture width.
heightTexture height.
valuesValues to be copied into the texture.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquire3DTexture ( const char *  name,
unsigned  dim,
bool  linearInterpolation,
const void *  values,
unsigned  size 
)
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.

Parameters
nameTexture name.
dimTexture dimension. The texture will be of size dim x dim x dim.
linearInterpolationWhether linear interpolation of texel values is needed.
valuesValues to be copied into the texture.
sizeValues buffer size.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual SynStatus SYNCOLOR::GPUAdaptor::acquireInputTexture ( )
pure virtual

Obtain any input texture related resources.

This method needs to create the input texture name to be used in the shader program.

See also
GPUAdaptor::getInputTextureName().
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
virtual const char* SYNCOLOR::GPUAdaptor::getInputTextureName ( ) const
pure virtual

Obtain the input texture name.

The input texture name is needed for inclusion in the shader declaration text.

Returns
Texture identification.
virtual SynStatus SYNCOLOR::GPUAdaptor::drawQuad ( unsigned  inTexHandle,
const SYNCOLOR::Vertices texCoords,
const SYNCOLOR::Vertices screenCoords 
) const
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().

Parameters
inTexHandleInput texture handle.
texCoordsInput texture coordinates.
screenCoordsDestination screen coordinates.
Returns
Must return a SYNCOLOR::SynStatus. See the GPUAdaptor class description for details.
ShaderLanguage SYNCOLOR::GPUAdaptor::getShaderLanguage ( ) const

Shader language configured.

The shader language is specified at the constructor.

Returns
Adaptor shader language.
PipelineType SYNCOLOR::GPUAdaptor::_getPipelineType ( ) const
protected

GPU pipeline type configured.

The pipeline type is specified at the constructor.

Returns
Adaptor expected pipelined type.

Member Data Documentation

ShaderLanguage SYNCOLOR::GPUAdaptor::_lang
private

Shader language for constructing the color transform shader.

PipelineType SYNCOLOR::GPUAdaptor::_pipelineType
private

GPU pipeline type for which the color transform shader is built.