A config defines all the color spaces to be available at runtime. More...

#include <OpenColorIO.h>

Public Member Functions
ConfigRcPtr	createEditableCopy () const

unsigned int	getMajorVersion () const
	Get the configuration major version. More...

void	setMajorVersion (unsigned int major)

unsigned int	getMinorVersion () const
	Get the configuration minor version. More...

void	setMinorVersion (unsigned int minor)
	Set the configuration minor version. Throws if it is not supported for the current major. More...

void	setVersion (unsigned int major, unsigned int minor)
	Set the configuration major and minor versions. Throws if version is not supported. More...

void	upgradeToLatestVersion () noexcept
	Allows an older config to be serialized as the current version. More...

void	validate () const
	Performs a thorough validation for the most common user errors. More...

const char *	getName () const noexcept
	Get/set a name string for the config. More...

void	setName (const char *name) noexcept

char	getFamilySeparator () const
	Get the family separator. More...

void	setFamilySeparator (char separator)
	Set the family separator. More...

const char *	getDescription () const

void	setDescription (const char *description)

void	serialize (std::ostream &os) const
	Returns the string representation of the Config in YAML text form. More...

const char *	getCacheID () const

const char *	getCacheID (const ConstContextRcPtr &context) const

ConstContextRcPtr	getCurrentContext () const

void	addEnvironmentVar (const char name, const char defaultValue)

int	getNumEnvironmentVars () const

const char *	getEnvironmentVarNameByIndex (int index) const

const char *	getEnvironmentVarDefault (const char *name) const

void	clearEnvironmentVars ()

void	setEnvironmentMode (EnvironmentMode mode) noexcept
	The EnvironmentMode controls the behavior of loadEnvironment. More...

EnvironmentMode	getEnvironmentMode () const noexcept

void	loadEnvironment () noexcept
	Initialize the environment/context variables in the Config's Context. More...

const char *	getSearchPath () const

void	setSearchPath (const char *path)
	Set all search paths as a concatenated string, use ':' to separate the paths. More...

int	getNumSearchPaths () const

const char *	getSearchPath (int index) const

void	clearSearchPaths ()

void	addSearchPath (const char *path)
	Add a single search path to the end of the list. More...

const char *	getWorkingDir () const

void	setWorkingDir (const char *dirname)
	The working directory defaults to the location of the config file. It is used to convert any relative paths to absolute. If no search paths have been set, the working directory will be used as the fallback search path. No environment (context) variables may be used in the working directory. More...

ColorSpaceSetRcPtr	getColorSpaces (const char *category) const
	Get all active color spaces having a specific category in the order they appear in the config file. More...

int	getNumColorSpaces (SearchReferenceSpaceType searchReferenceType, ColorSpaceVisibility visibility) const
	Work on the color spaces selected by the reference color space type and visibility. More...

const char *	getColorSpaceNameByIndex (SearchReferenceSpaceType searchReferenceType, ColorSpaceVisibility visibility, int index) const
	Work on the color spaces selected by the reference color space type and visibility (active or inactive). More...

int	getNumColorSpaces () const
	Work on the active color spaces only. More...

const char *	getColorSpaceNameByIndex (int index) const

int	getIndexForColorSpace (const char *name) const
	Get an index from the active color spaces only and return -1 if the name is not found. More...

ConstColorSpaceRcPtr	getColorSpace (const char *name) const
	Get the color space from all the color spaces (i.e. active and inactive) and return null if the name is not found. More...

const char *	getCanonicalName (const char *name) const

void	addColorSpace (const ConstColorSpaceRcPtr &cs)
	Add a color space to the configuration. More...

void	removeColorSpace (const char *name)
	Remove a color space from the configuration. More...

bool	isColorSpaceUsed (const char *name) const noexcept

void	clearColorSpaces ()
	Remove all the color spaces from the configuration. More...

void	setInactiveColorSpaces (const char *inactiveColorSpaces)
	Set/get a list of inactive color space or named transform names. More...

const char *	getInactiveColorSpaces () const

bool	isColorSpaceLinear (const char *colorSpace, ReferenceSpaceType referenceSpaceType) const
	Return true if the specified color space is linear. More...

void	setRole (const char role, const char colorSpaceName)

int	getNumRoles () const

bool	hasRole (const char *role) const
	Return true if the role has been defined. More...

const char *	getRoleName (int index) const
	Get the role name at index, this will return values like 'scene_linear', 'compositing_log'. More...

const char *	getRoleColorSpace (int index) const
	Get the role color space at index. More...

void	addSharedView (const char view, const char viewTransformName, const char colorSpaceName, const char looks, const char ruleName, const char description)
	Will throw if view or colorSpaceName are null or empty. More...

void	removeSharedView (const char *view)
	Remove a shared view. Will throw if the view does not exist. More...

const char *	getDefaultDisplay () const

int	getNumDisplays () const

const char *	getDisplay (int index) const
	Will return "" if the index is invalid. More...

const char *	getDefaultView (const char *display) const

const char *	getDefaultView (const char display, const char colorspaceName) const

int	getNumViews (const char *display) const

const char *	getView (const char *display, int index) const

int	getNumViews (const char display, const char colorspaceName) const

const char *	getView (const char display, const char colorspaceName, int index) const

const char *	getDisplayViewTransformName (const char display, const char view) const

const char *	getDisplayViewColorSpaceName (const char display, const char view) const

const char *	getDisplayViewLooks (const char display, const char view) const
	Returns the looks attribute of a (display, view) pair. More...

const char *	getDisplayViewRule (const char display, const char view) const noexcept
	Returns the rule attribute of a (display, view) pair. More...

const char *	getDisplayViewDescription (const char display, const char view) const noexcept
	Returns the description attribute of a (display, view) pair. More...

void	addDisplayView (const char display, const char view, const char colorSpaceName, const char looks)

void	addDisplayView (const char display, const char view, const char viewTransformName, const char colorSpaceName, const char looks, const char ruleName, const char *description)
	For the (display, view) pair, specify the color space or alternatively specify the view transform and display color space. The looks, viewing rule, and description are optional. Pass a null or empty string for any optional arguments. If the view already exists, it is replaced. More...

void	addDisplaySharedView (const char display, const char sharedView)
	Add a (reference to a) shared view to a display. More...

void	removeDisplayView (const char display, const char view)
	Remove the view and the display if no more views. More...

void	clearDisplays ()
	Clear all the displays. More...

void	addVirtualDisplayView (const char view, const char viewTransformName, const char colorSpaceName, const char looks, const char ruleName, const char description)

void	addVirtualDisplaySharedView (const char *sharedView)

int	getVirtualDisplayNumViews (ViewType type) const noexcept
	Get the number of views associated to the virtual display. More...

const char *	getVirtualDisplayView (ViewType type, int index) const noexcept
	Get the view name at a specific index. More...

const char *	getVirtualDisplayViewTransformName (const char *view) const noexcept

const char *	getVirtualDisplayViewColorSpaceName (const char *view) const noexcept

const char *	getVirtualDisplayViewLooks (const char *view) const noexcept

const char *	getVirtualDisplayViewRule (const char *view) const noexcept

const char *	getVirtualDisplayViewDescription (const char *view) const noexcept

void	removeVirtualDisplayView (const char *view) noexcept
	Remove the view from the virtual display. More...

void	clearVirtualDisplay () noexcept
	Clear the virtual display. More...

int	instantiateDisplayFromMonitorName (const char *monitorName)
	Instantiate a new display from a virtual display, using the monitor name. More...

int	instantiateDisplayFromICCProfile (const char *ICCProfileFilepath)
	Instantiate a new display from a virtual display, using an ICC profile. More...

void	setActiveDisplays (const char *displays)
	$OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the allowed displays. It is a comma or colon delimited list. Active displays that are not in the specified profile will be ignored, and the left-most defined display will be the default. More...

const char *	getActiveDisplays () const

void	setActiveViews (const char *views)
	$OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views. It is a comma or colon delimited list. Active views that are not in the specified profile will be ignored, and the left-most defined view will be the default. More...

const char *	getActiveViews () const

int	getNumDisplaysAll () const noexcept
	Get all displays in the config, ignoring the active_displays list. More...

const char *	getDisplayAll (int index) const noexcept

int	getDisplayAllByName (const char *) const noexcept

bool	isDisplayTemporary (int index) const noexcept

int	getNumViews (ViewType type, const char *display) const

const char *	getView (ViewType type, const char *display, int index) const

ConstViewingRulesRcPtr	getViewingRules () const noexcept
	Get read-only version of the viewing rules. More...

void	setViewingRules (ConstViewingRulesRcPtr viewingRules)
	Set viewing rules. More...

void	getDefaultLumaCoefs (double *rgb) const
	Get the default coefficients for computing luma. More...

void	setDefaultLumaCoefs (const double *rgb)
	These should be normalized (sum to 1.0 exactly). More...

ConstLookRcPtr	getLook (const char *name) const

int	getNumLooks () const

const char *	getLookNameByIndex (int index) const

void	addLook (const ConstLookRcPtr &look)

void	clearLooks ()

int	getNumViewTransforms () const noexcept

ConstViewTransformRcPtr	getViewTransform (const char *name) const noexcept

const char *	getViewTransformNameByIndex (int i) const noexcept

void	addViewTransform (const ConstViewTransformRcPtr &viewTransform)

ConstViewTransformRcPtr	getDefaultSceneToDisplayViewTransform () const
	This view transform is the one that will be used by default if a ColorSpaceTransform is needed between a scene-referred and display-referred color space. The config author may specify a transform to use via the default_view_transform entry in the config. If that is not present, or does not return a valid view transform from the scene-referred connection space, the fall-back is to use the first valid view transform in the config. Returns a null ConstTransformRcPtr if there isn't one. More...

const char *	getDefaultViewTransformName () const noexcept

void	setDefaultViewTransformName (const char *defaultName) noexcept

void	clearViewTransforms ()

int	getNumNamedTransforms (NamedTransformVisibility visibility) const noexcept
	Work on the named transforms selected by visibility. More...

const char *	getNamedTransformNameByIndex (NamedTransformVisibility visibility, int index) const noexcept
	Work on the named transforms selected by visibility (active or inactive). More...

int	getNumNamedTransforms () const noexcept
	Work on the active named transforms only. More...

const char *	getNamedTransformNameByIndex (int index) const noexcept
	Work on the active named transforms only and return an empty string for invalid index. More...

int	getIndexForNamedTransform (const char *name) const noexcept
	Get an index from the active named transforms only and return -1 if the name is not found. More...

ConstNamedTransformRcPtr	getNamedTransform (const char *name) const noexcept
	Get the named transform from all the named transforms (i.e. active and inactive) and return null if the name is not found. More...

void	addNamedTransform (const ConstNamedTransformRcPtr &namedTransform)
	Add or replace named transform. More...

void	clearNamedTransforms ()
	Clear all named transforms. More...

ConstFileRulesRcPtr	getFileRules () const noexcept
	Get read-only version of the file rules. More...

void	setFileRules (ConstFileRulesRcPtr fileRules)
	Set file rules. More...

const char *	getColorSpaceFromFilepath (const char *filePath) const

const char *	getColorSpaceFromFilepath (const char *filePath, size_t &ruleIndex) const

bool	filepathOnlyMatchesDefaultRule (const char *filePath) const
	Returns true if the only rule matched by filePath is the default rule. This is a convenience method for applications that want to require the user to manually choose a color space when strictParsing is true and no other rules match. More...

const char *	parseColorSpaceFromString (const char *str) const

bool	isStrictParsingEnabled () const

void	setStrictParsingEnabled (bool enabled)

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const ConstColorSpaceRcPtr &srcColorSpace, const ConstColorSpaceRcPtr &dstColorSpace) const

ConstProcessorRcPtr	getProcessor (const ConstColorSpaceRcPtr &srcColorSpace, const ConstColorSpaceRcPtr &dstColorSpace) const

ConstProcessorRcPtr	getProcessor (const char srcColorSpaceName, const char dstColorSpaceName) const

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const char srcColorSpaceName, const char dstColorSpaceName) const

ConstProcessorRcPtr	getProcessor (const char srcColorSpaceName, const char display, const char *view, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const char srcColorSpaceName, const char display, const char *view, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const ConstNamedTransformRcPtr &namedTransform, TransformDirection direction) const
	Get the processor to apply a NamedTransform in the specified direction. More...

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const ConstNamedTransformRcPtr &namedTransform, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const char *namedTransformName, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const char *namedTransformName, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const ConstTransformRcPtr &transform) const
	Get the processor for the specified transform. More...

ConstProcessorRcPtr	getProcessor (const ConstTransformRcPtr &transform, TransformDirection direction) const

ConstProcessorRcPtr	getProcessor (const ConstContextRcPtr &context, const ConstTransformRcPtr &transform, TransformDirection direction) const

void	setConfigIOProxy (ConfigIOProxyRcPtr ciop)

ConfigIOProxyRcPtr	getConfigIOProxy () const

bool	isArchivable () const
	Verify if the config is archivable. More...

void	archive (std::ostream &ostream) const
	Archive the config and its LUTs into the specified output stream. More...

	Config (const Config &)=delete

Config &	operator= (const Config &)=delete

	~Config ()
	Do not use (needed only for pybind11). More...

void	setProcessorCacheFlags (ProcessorCacheFlags flags) noexcept

Static Public Member Functions
static ConfigRcPtr	Create ()
	Create an empty config of the current version. More...

static ConstConfigRcPtr	CreateRaw ()
	Create a fall-back config. More...

static ConstConfigRcPtr	CreateFromEnv ()
	Create a configuration using the OCIO environment variable. More...

static ConstConfigRcPtr	CreateFromFile (const char *filename)
	Create a configuration using a specific config file. More...

static ConstConfigRcPtr	CreateFromStream (std::istream &istream)
	Create a configuration using a stream. More...

static ConstConfigRcPtr	CreateFromConfigIOProxy (ConfigIOProxyRcPtr ciop)
	Create a config from the supplied ConfigIOProxy object. This allows the calling program to directly provide the config and associated LUTs rather than reading them from the standard file system. More...

static ConstConfigRcPtr	CreateFromBuiltinConfig (const char *configName)
	Create a configuration using an OCIO built-in config. More...

static char	GetDefaultFamilySeparator () noexcept
	Get the default family separator i.e. '/' . More...

static ConstProcessorRcPtr	GetProcessorToBuiltinColorSpace (ConstConfigRcPtr srcConfig, const char srcColorSpaceName, const char builtinColorSpaceName)
	Get a Processor to or from a known external color space. More...

static ConstProcessorRcPtr	GetProcessorFromBuiltinColorSpace (const char builtinColorSpaceName, ConstConfigRcPtr srcConfig, const char srcColorSpaceName)
	See description of GetProcessorToBuiltinColorSpace. More...

static ConstProcessorRcPtr	GetProcessorFromConfigs (const ConstConfigRcPtr &srcConfig, const char srcColorSpaceName, const ConstConfigRcPtr &dstConfig, const char dstColorSpaceName)
	Get a processor to convert between color spaces in two separate configs. More...

static ConstProcessorRcPtr	GetProcessorFromConfigs (const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char srcColorSpaceName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char dstColorSpaceName)

static ConstProcessorRcPtr	GetProcessorFromConfigs (const ConstConfigRcPtr &srcConfig, const char srcColorSpaceName, const char srcInterchangeName, const ConstConfigRcPtr &dstConfig, const char dstColorSpaceName, const char dstInterchangeName)

static ConstProcessorRcPtr	GetProcessorFromConfigs (const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char srcColorSpaceName, const char srcInterchangeName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char dstColorSpaceName, const char dstInterchangeName)

Detailed Description

A config defines all the color spaces to be available at runtime.

The color configuration (Config) is the main object for interacting with this library. It encapsulates all of the information necessary to use customized ColorSpaceTransform and DisplayViewTransform operations.

See the user-guide for more information on selecting, creating, and working with custom color configurations.

For applications interested in using only one color config at a time (this is the vast majority of apps), their API would traditionally get the global configuration and use that, as opposed to creating a new one. This simplifies the use case for plugins and bindings, as it alleviates the need to pass around configuration handles.

An example of an application where this would not be sufficient would be a multi-threaded image proxy server (daemon), which wished to handle multiple show configurations in a single process concurrently. This app would need to keep multiple configurations alive, and to manage them appropriately.

Roughly speaking, a novice user should select a default configuration that most closely approximates the use case (animation, visual effects, etc.), and set the :envvar:OCIO environment variable to point at the root of that configuration.

Note: Initialization using environment variables is typically preferable in a multi-app ecosystem, as it allows all applications to be consistently configured.

See developers-usageexamples

Definition at line 259 of file OpenColorIO.h.

Constructor & Destructor Documentation

OCIO_NAMESPACE::Config::Config ( const Config & )

delete

OCIO_NAMESPACE::Config::~Config ( )

Do not use (needed only for pybind11).

Member Function Documentation

void OCIO_NAMESPACE::Config::addColorSpace ( const ConstColorSpaceRcPtr & cs )

Add a color space to the configuration.

Note: If another color space is already present with the same name, this will overwrite it. This stores a copy of the specified color space.; Adding a color space to a Config does not affect any ColorSpaceSet sets that have already been created.

void OCIO_NAMESPACE::Config::addEnvironmentVar	(	const char *	name,
		const char *	defaultValue
	)

Add (or update) an environment variable with a default value. But it removes it if the default value is null.

void OCIO_NAMESPACE::Config::addLook ( const ConstLookRcPtr & look )

void OCIO_NAMESPACE::Config::addSearchPath ( const char * path )

Add a single search path to the end of the list.

Paths may be either absolute or relative. Relative paths are relative to the working directory. Forward slashes will be normalized to reverse for Windows. Environment (context) variables may be used in paths.

void OCIO_NAMESPACE::Config::addViewTransform ( const ConstViewTransformRcPtr & viewTransform )

void OCIO_NAMESPACE::Config::archive ( std::ostream & ostream ) const

Archive the config and its LUTs into the specified output stream.

The config is archived by serializing the Config object into a file named "config.ocio" and then walking through the current working directory and any sub-directories. Any files that have an extension matching a supported LUT file format are added to the archive. Any files that do not have an extension (or have some unsupported LUT extension, including .ocio), will not be added to the archive. To reiterate, it is the in-memory Config object that is archived, and not any .ocio file in the current working directory. The directory structure relative to the working directory is preserved. No files outside the working directory are archived so that if it is later expanded, no files will be created outside the working dir.

The reason the archive is created using all supported LUT file extensions rather than by trying to resolve all the FileTransforms in the Config to specific files is because of the goal to allow context variables to continue to work.

If a Config is created with CreateFromStream, CreateFromFile with an OCIOZ archive, or CreateFromConfigIOProxy, it cannot be archived unless the working directory is manually set to a directory that contains any necessary LUT files.

The provided output stream must be closed by the caller, if necessary (e.g., an ofstream).

Parameters

ostream The output stream to write to.

void OCIO_NAMESPACE::Config::clearColorSpaces ( )

Remove all the color spaces from the configuration.

Note: Removing color spaces from a Config does not affect any ColorSpaceSet sets that have already been created.

void OCIO_NAMESPACE::Config::clearEnvironmentVars ( )

void OCIO_NAMESPACE::Config::clearLooks ( )

void OCIO_NAMESPACE::Config::clearSearchPaths ( )

void OCIO_NAMESPACE::Config::clearViewTransforms ( )

static ConfigRcPtr OCIO_NAMESPACE::Config::Create ( )

static

Create an empty config of the current version.

Note that an empty config will not pass validation since required elements will be missing.

Returns: The Config object.

ConfigRcPtr OCIO_NAMESPACE::Config::createEditableCopy ( ) const

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateFromBuiltinConfig ( const char * configName )

static

Create a configuration using an OCIO built-in config.

Parameters

configName Built-in config name.

The available configNames are:

ACES Studio config, contains a more complete collection of color spaces and displays: "studio-config-v1.0.0_aces-v1.3_ocio-v2.1"

ACES CG config, basic color spaces for computer graphics apps: "cg-config-v1.0.0_aces-v1.3_ocio-v2.1"

More information is available at: https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES

Information about the available configs is available from the BuiltinConfigRegistry.

Exceptions

Exception If the configName is not recognized.

Returns: One of the configs built into the OCIO library.

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateFromConfigIOProxy ( ConfigIOProxyRcPtr ciop )

static

Create a config from the supplied ConfigIOProxy object. This allows the calling program to directly provide the config and associated LUTs rather than reading them from the standard file system.

See the ConfigIOProxy class documentation for more info.

Parameters

ciop	ConfigIOProxy object providing access to the config's files.

Exceptions

Exception If the config may not be read from the proxy, or does not parse.

Returns: The Config object.

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateFromEnv ( )

static

Create a configuration using the OCIO environment variable.

Also supports the OCIO URI format for Built-in configs and supports archived configs. See Config::CreateFromFile.

If the variable is missing or empty, returns the same result as Config::CreateRaw.

Returns: The Config object.

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateFromFile ( const char * filename )

static

Create a configuration using a specific config file.

Also supports the following OCIO URI format for Built-in configs: "ocio://default" - Default Built-in config. "ocio://<CONFIG NAME>" - A specific Built-in config. For the list of available <CONFIG name>=""> strings, see Config::CreateFromBuiltinConfig.

Also supports archived configs (.ocioz files).

Exceptions

Exception If the file may not be read or does not parse.

Returns: The Config object.

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateFromStream ( std::istream & istream )

static

Create a configuration using a stream.

Note that CreateFromStream does not set the working directory so the caller would need to set that separately in order to resolve FileTransforms. This function is typically only used for self-contained configs (no LUTs).

Configs created from CreateFromStream can not be archived unless the working directory is set and contains any necessary LUT files.

Parameters

istream Stream to the config.

Exceptions

Exception If the stream does not parse.

Returns: The Config object.

static ConstConfigRcPtr OCIO_NAMESPACE::Config::CreateRaw ( )

static

Create a fall-back config.

This may be useful to allow client apps to launch in cases when the supplied config path is not loadable.

Returns: The Config object.

bool OCIO_NAMESPACE::Config::filepathOnlyMatchesDefaultRule ( const char * filePath ) const

Returns true if the only rule matched by filePath is the default rule. This is a convenience method for applications that want to require the user to manually choose a color space when strictParsing is true and no other rules match.

const char* OCIO_NAMESPACE::Config::getActiveDisplays ( ) const

const char* OCIO_NAMESPACE::Config::getActiveViews ( ) const

const char* OCIO_NAMESPACE::Config::getCacheID ( ) const

This will produce a hash of the all colorspace definitions, etc. All external references, such as files used in FileTransforms, etc., will be incorporated into the cacheID. While the contents of the files are not read, the file system is queried for relevant information (mtime, inode) so that the config's cacheID will change when the underlying luts are updated.

If a context is not provided, the current Context will be used.

If a null context is provided, file references will not be taken into account (this is essentially a hash of Config::serialize).

const char* OCIO_NAMESPACE::Config::getCacheID ( const ConstContextRcPtr & context ) const

const char* OCIO_NAMESPACE::Config::getCanonicalName ( const char * name ) const

Accepts an alias, role name, named transform name, or color space name and returns the color space name or the named transform name.

ConstColorSpaceRcPtr OCIO_NAMESPACE::Config::getColorSpace ( const char * name ) const

Get the color space from all the color spaces (i.e. active and inactive) and return null if the name is not found.

Note: The fcn accepts either a color space name, role name, or alias. (Color space names take precedence over roles.)

const char* OCIO_NAMESPACE::Config::getColorSpaceFromFilepath ( const char * filePath ) const

Get the color space of the first rule that matched filePath. (For v1 configs, this is equivalent to calling parseColorSpaceFromString with strictparsing set to false.)

const char* OCIO_NAMESPACE::Config::getColorSpaceFromFilepath	(	const char *	filePath,
		size_t &	ruleIndex
	)		const

Most applications will use the preceding method, but this method may be used for applications that want to know which was the highest priority rule to match filePath. FileRules::getNumCustomKeys and custom keys methods may then be used to get additional information about the matching rule.

const char* OCIO_NAMESPACE::Config::getColorSpaceNameByIndex	(	SearchReferenceSpaceType	searchReferenceType,
		ColorSpaceVisibility	visibility,
		int	index
	)		const

Work on the color spaces selected by the reference color space type and visibility (active or inactive).

Return empty for invalid index.

const char* OCIO_NAMESPACE::Config::getColorSpaceNameByIndex ( int index ) const

Work on the active color spaces only and return null for invalid index.

Note: Only works from the list of active color spaces.

ColorSpaceSetRcPtr OCIO_NAMESPACE::Config::getColorSpaces ( const char * category ) const

Get all active color spaces having a specific category in the order they appear in the config file.

Note: If the category is null or empty, the method returns all the active color spaces like Config::getNumColorSpaces and Config::getColorSpaceNameByIndex do.; It's worth noticing that the method returns a copy of the selected color spaces decoupling the result from the config. Hence, any changes on the config do not affect the existing color space sets, and vice-versa.

ConfigIOProxyRcPtr OCIO_NAMESPACE::Config::getConfigIOProxy ( ) const

ConstContextRcPtr OCIO_NAMESPACE::Config::getCurrentContext ( ) const

static char OCIO_NAMESPACE::Config::GetDefaultFamilySeparator ( )

staticnoexcept

Get the default family separator i.e. '/' .

void OCIO_NAMESPACE::Config::getDefaultLumaCoefs ( double * rgb ) const

Get the default coefficients for computing luma.

Note: There is no "1 size fits all" set of luma coefficients. (The values are typically different for each colorspace, and the application of them may be nonsensical depending on the intensity coding anyways). Thus, the 'right' answer is to make these functions on the ColorSpace class. However, it's often useful to have a config-wide default so here it is. We will add the colorspace specific luma call if/when another client is interesting in using it.

ConstViewTransformRcPtr OCIO_NAMESPACE::Config::getDefaultSceneToDisplayViewTransform ( ) const

This view transform is the one that will be used by default if a ColorSpaceTransform is needed between a scene-referred and display-referred color space. The config author may specify a transform to use via the default_view_transform entry in the config. If that is not present, or does not return a valid view transform from the scene-referred connection space, the fall-back is to use the first valid view transform in the config. Returns a null ConstTransformRcPtr if there isn't one.

const char* OCIO_NAMESPACE::Config::getDefaultViewTransformName ( ) const

noexcept

Get or set the default_view_transform string from the config.

Note that if this is not the name of a valid view transform from the scene-referred connection space, it will be ignored.

const char* OCIO_NAMESPACE::Config::getDescription ( ) const

const char* OCIO_NAMESPACE::Config::getDisplayAll ( int index ) const

noexcept

int OCIO_NAMESPACE::Config::getDisplayAllByName ( const char * ) const

noexcept

EnvironmentMode OCIO_NAMESPACE::Config::getEnvironmentMode ( ) const

noexcept

const char* OCIO_NAMESPACE::Config::getEnvironmentVarDefault ( const char * name ) const

const char* OCIO_NAMESPACE::Config::getEnvironmentVarNameByIndex ( int index ) const

char OCIO_NAMESPACE::Config::getFamilySeparator ( ) const

Get the family separator.

A single character used to separate the family string into tokens for use in hierarchical menus. Defaults to '/'.

ConstFileRulesRcPtr OCIO_NAMESPACE::Config::getFileRules ( ) const

noexcept

Get read-only version of the file rules.

const char* OCIO_NAMESPACE::Config::getInactiveColorSpaces ( ) const

int OCIO_NAMESPACE::Config::getIndexForColorSpace ( const char * name ) const

Get an index from the active color spaces only and return -1 if the name is not found.

Note: The fcn accepts either a color space name, role name, or alias. (Color space names take precedence over roles.)

ConstLookRcPtr OCIO_NAMESPACE::Config::getLook ( const char * name ) const

const char* OCIO_NAMESPACE::Config::getLookNameByIndex ( int index ) const

unsigned int OCIO_NAMESPACE::Config::getMajorVersion ( ) const

Get the configuration major version.

unsigned int OCIO_NAMESPACE::Config::getMinorVersion ( ) const

Get the configuration minor version.

const char* OCIO_NAMESPACE::Config::getName ( ) const

noexcept

Get/set a name string for the config.

The name string may be used to communicate config update details or similar information to workflows external to OCIO in cases where the config path/filename itself does not provide adequate information.

int OCIO_NAMESPACE::Config::getNumColorSpaces	(	SearchReferenceSpaceType	searchReferenceType,
		ColorSpaceVisibility	visibility
	)		const

Work on the color spaces selected by the reference color space type and visibility.

int OCIO_NAMESPACE::Config::getNumColorSpaces ( ) const

Work on the active color spaces only.

Note: Only works from the list of active color spaces.

int OCIO_NAMESPACE::Config::getNumDisplaysAll ( ) const

noexcept

Get all displays in the config, ignoring the active_displays list.

int OCIO_NAMESPACE::Config::getNumEnvironmentVars ( ) const

int OCIO_NAMESPACE::Config::getNumLooks ( ) const

int OCIO_NAMESPACE::Config::getNumRoles ( ) const

int OCIO_NAMESPACE::Config::getNumSearchPaths ( ) const

int OCIO_NAMESPACE::Config::getNumViews	(	ViewType	type,
		const char *	display
	)		const

Get either the shared or display-defined views for a display. The active_views list is ignored. Passing a null or empty display (with type=VIEW_SHARED) returns the contents of the shared_views section of the config. Return 0 if display does not exist.

int OCIO_NAMESPACE::Config::getNumViewTransforms ( ) const

noexcept

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const ConstColorSpaceRcPtr &	srcColorSpace,
		const ConstColorSpaceRcPtr &	dstColorSpace
	)		const

Get the processor to apply a ColorSpaceTransform from a source to a destination color space.

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstColorSpaceRcPtr &	srcColorSpace,
		const ConstColorSpaceRcPtr &	dstColorSpace
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const char *	srcColorSpaceName,
		const char *	dstColorSpaceName
	)		const

Note: Names can be colorspace name, role name, or a combination of both.

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const char *	srcColorSpaceName,
		const char *	dstColorSpaceName
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const char *	srcColorSpaceName,
		const char *	display,
		const char *	view,
		TransformDirection	direction
	)		const

Get the processor to apply a DisplayViewTransform for a display and view. Refer to the Display/View Registration section above for more info on the display and view arguments.

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const char *	srcColorSpaceName,
		const char *	display,
		const char *	view,
		TransformDirection	direction
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstNamedTransformRcPtr &	namedTransform,
		TransformDirection	direction
	)		const

Get the processor to apply a NamedTransform in the specified direction.

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const ConstNamedTransformRcPtr &	namedTransform,
		TransformDirection	direction
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const char *	namedTransformName,
		TransformDirection	direction
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const char *	namedTransformName,
		TransformDirection	direction
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor ( const ConstTransformRcPtr & transform ) const

Get the processor for the specified transform.

Not often needed, but will allow for the re-use of atomic OCIO functionality (such as to apply an individual LUT file).

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstTransformRcPtr &	transform,
		TransformDirection	direction
	)		const

ConstProcessorRcPtr OCIO_NAMESPACE::Config::getProcessor	(	const ConstContextRcPtr &	context,
		const ConstTransformRcPtr &	transform,
		TransformDirection	direction
	)		const

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorFromBuiltinColorSpace	(	const char *	builtinColorSpaceName,
		ConstConfigRcPtr	srcConfig,
		const char *	srcColorSpaceName
	)

static

See description of GetProcessorToBuiltinColorSpace.

Parameters

builtinColorSpaceName	The name of the color space in the current default Built-in config.
srcConfig	The user's source config.
srcColorSpaceName	The name of the color space in the source config.

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorFromConfigs	(	const ConstConfigRcPtr &	srcConfig,
		const char *	srcColorSpaceName,
		const ConstConfigRcPtr &	dstConfig,
		const char *	dstColorSpaceName
	)

static

Get a processor to convert between color spaces in two separate configs.

This relies on both configs having the aces_interchange role (when srcName is scene-referred) or the role cie_xyz_d65_interchange (when srcName is display-referred) defined. An exception is thrown if that is not the case.

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorFromConfigs	(	const ConstContextRcPtr &	srcContext,
		const ConstConfigRcPtr &	srcConfig,
		const char *	srcColorSpaceName,
		const ConstContextRcPtr &	dstContext,
		const ConstConfigRcPtr &	dstConfig,
		const char *	dstColorSpaceName
	)

static

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorFromConfigs	(	const ConstConfigRcPtr &	srcConfig,
		const char *	srcColorSpaceName,
		const char *	srcInterchangeName,
		const ConstConfigRcPtr &	dstConfig,
		const char *	dstColorSpaceName,
		const char *	dstInterchangeName
	)

static

The srcInterchangeName and dstInterchangeName must refer to a pair of color spaces in the two configs that are the same. A role name may also be used.

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorFromConfigs	(	const ConstContextRcPtr &	srcContext,
		const ConstConfigRcPtr &	srcConfig,
		const char *	srcColorSpaceName,
		const char *	srcInterchangeName,
		const ConstContextRcPtr &	dstContext,
		const ConstConfigRcPtr &	dstConfig,
		const char *	dstColorSpaceName,
		const char *	dstInterchangeName
	)

static

static ConstProcessorRcPtr OCIO_NAMESPACE::Config::GetProcessorToBuiltinColorSpace	(	ConstConfigRcPtr	srcConfig,
		const char *	srcColorSpaceName,
		const char *	builtinColorSpaceName
	)

static

Get a Processor to or from a known external color space.

These methods provide a way to interface color spaces in a config with known standard external color spaces. The set of external color space are those contained in the current default Built-in config. This includes common spaces such as "Linear Rec.709 (sRGB)", "sRGB - Texture", "ACEScg", and "ACES2065-1".

If the source config defines the necessary Interchange Role (typically "aces_interchange"), then the conversion will be well-defined and equivalent to calling GetProcessorFromConfigs with the source config and the Built-in config

However, if the Interchange Roles are not present, heuristics will be used to try and identify a common color space in the source config that may be used to allow the conversion to proceed. If the heuristics fail to find a suitable space, an exception is thrown. The heuristics may evolve, so the results returned by this function for a given source config and color space may change in future releases of the library. However, the Interchange Roles are required in config versions 2.2 and higher, so it is hoped that the need for the heuristics will decrease over time.

Parameters

srcConfig	The user's source config.
srcColorSpaceName	The name of the color space in the source config.
builtinColorSpaceName	The name of the color space in the current default Built-in config.

const char* OCIO_NAMESPACE::Config::getRoleColorSpace ( int index ) const

Get the role color space at index.

Return empty string if index is out of range.

const char* OCIO_NAMESPACE::Config::getRoleName ( int index ) const

Get the role name at index, this will return values like 'scene_linear', 'compositing_log'.

Return empty string if index is out of range.

const char* OCIO_NAMESPACE::Config::getSearchPath ( ) const

const char* OCIO_NAMESPACE::Config::getSearchPath ( int index ) const

Get a search path from the list.

The paths are in the order they will be searched (that is, highest to lowest priority).

const char* OCIO_NAMESPACE::Config::getView	(	ViewType	type,
		const char *	display,
		int	index
	)		const

ConstViewingRulesRcPtr OCIO_NAMESPACE::Config::getViewingRules ( ) const

noexcept

Get read-only version of the viewing rules.

ConstViewTransformRcPtr OCIO_NAMESPACE::Config::getViewTransform ( const char * name ) const

noexcept

const char* OCIO_NAMESPACE::Config::getViewTransformNameByIndex ( int i ) const

noexcept

const char* OCIO_NAMESPACE::Config::getWorkingDir ( ) const

bool OCIO_NAMESPACE::Config::hasRole ( const char * role ) const

Return true if the role has been defined.

bool OCIO_NAMESPACE::Config::isArchivable ( ) const

Verify if the config is archivable.

A config is not archivable if any of the following are true: – The working directory is not set – It contains FileTransforms with a src outside the working directory – The search path contains paths outside the working directory – The search path contains paths that start with a context variable

Context variables are allowed but the intent is that they may only resolve to paths that are within or below the working directory. This is because the archiving function will only archive files that are within the working directory in order to ensure that if it is later expanded, that it will not create any files outside this directory.

For example, a context variable on the search path intended to contain the name of a sub-directory under the working directory must have the form "./$DIR_NAME" rather than just "$DIR_NAME" to be considered archivable. This is imperfect since there is no way to prevent the context variable from creating a path outside the working dir, but it should at least draw attention to the fact that the archive would fail if used with context vars that try to abuse the intended functionality.

Returns: bool Archivable if true.

bool OCIO_NAMESPACE::Config::isColorSpaceLinear	(	const char *	colorSpace,
		ReferenceSpaceType	referenceSpaceType
	)		const

Return true if the specified color space is linear.

The determination of linearity is made with respect to one of the two reference spaces (i.e., either the scene-referred one or the display-referred one). If the reference space type of the color space is the opposite of the requested reference space type, false is returned immediately rather than trying to invoke the default view transform to convert between the reference spaces.

Note: This function relies on heuristics that may sometimes give an incorrect result. For example, if the encoding attribute is not set appropriately or the sampled values fail to detect non-linearity.

The algorithm proceeds as follows: – If the color space isdata attribute is true, return false. – If the reference space type of the color space differs from the requested reference space type, return false. – If the color space's encoding attribute is present, return true if it matches the expected reference space type (i.e., "scene-linear" for REFERENCE_SPACE_SCENE or "display-linear" for REFERENCE_SPACE_DISPLAY) and false otherwise. – If the color space has no to_reference or from_reference transform, return true. – Evaluate several points through the color space's transform and check if the output only differs by a scale factor (which may be different per channel, e.g. allowing an arbitrary matrix transform, with no offset).

Note that the encoding test happens before the sampled value test to give config authors ultimate control over the linearity determination. For example, they could set the encoding attribute to indicate linearity if they want to ignore some areas of non-linearity (e.g., at extreme values). Or they could set it to indicate that a color space should not be considered linear, even if it is, in a mathematical sense.

Parameters

colorSpace	Color space to evaluate.
referenceSpaceType	Evaluate linearity with respect to the specified reference space (either scene-referred or display-referred).

bool OCIO_NAMESPACE::Config::isColorSpaceUsed ( const char * name ) const

noexcept

Return true if the color space is used by a transform, a role, or a look.

Note: Name must be the canonical name.

bool OCIO_NAMESPACE::Config::isDisplayTemporary ( int index ) const

noexcept

Will be true for a display that was instantiated from a virtual display. These displays are intended to be temporary (i.e. for the current session) and are not saved to a config file.

bool OCIO_NAMESPACE::Config::isStrictParsingEnabled ( ) const

void OCIO_NAMESPACE::Config::loadEnvironment ( )

noexcept

Initialize the environment/context variables in the Config's Context.

Config& OCIO_NAMESPACE::Config::operator= ( const Config & )

delete

const char* OCIO_NAMESPACE::Config::parseColorSpaceFromString ( const char * str ) const

Given the specified string, get the longest, right-most, colorspace substring that appears.

If strict parsing is enabled, and no color space is found, return an empty string.
If strict parsing is disabled, return ROLE_DEFAULT (if defined).
If the default role is not defined, return an empty string.

void OCIO_NAMESPACE::Config::removeColorSpace ( const char * name )

Remove a color space from the configuration.

Note: It does not throw an exception. Name must be the canonical name. If a role name or alias is provided or if the name is not in the config, nothing is done.; Removing a color space from a Config does not affect any ColorSpaceSet sets that have already been created.

void OCIO_NAMESPACE::Config::serialize ( std::ostream & os ) const

Returns the string representation of the Config in YAML text form.

This is typically stored on disk in a file with the extension .ocio. NB: This does not validate the config. Applications should validate before serializing.

void OCIO_NAMESPACE::Config::setActiveDisplays ( const char * displays )

$OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the allowed displays. It is a comma or colon delimited list. Active displays that are not in the specified profile will be ignored, and the left-most defined display will be the default.

Comma-delimited list of names to filter and order the active displays.

Note: The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

void OCIO_NAMESPACE::Config::setActiveViews ( const char * views )

$OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views. It is a comma or colon delimited list. Active views that are not in the specified profile will be ignored, and the left-most defined view will be the default.

Comma-delimited list of names to filter and order the active views.

Note: The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

void OCIO_NAMESPACE::Config::setConfigIOProxy ( ConfigIOProxyRcPtr ciop )

Set the ConfigIOProxy object used to provision the config and LUTs from somewhere other than the file system. (This is set on the config's embedded Context object.)

void OCIO_NAMESPACE::Config::setDefaultLumaCoefs ( const double * rgb )

These should be normalized (sum to 1.0 exactly).

void OCIO_NAMESPACE::Config::setDefaultViewTransformName ( const char * defaultName )

noexcept

void OCIO_NAMESPACE::Config::setDescription ( const char * description )

void OCIO_NAMESPACE::Config::setEnvironmentMode ( EnvironmentMode mode )

noexcept

The EnvironmentMode controls the behavior of loadEnvironment.

ENV_ENVIRONMENT_LOAD_PREDEFINED - Only update vars already added to the Context.
ENV_ENVIRONMENT_LOAD_ALL - Load all env. vars into the Context.

Note: Loading ALL the env. vars may reduce performance and reduce cache efficiency.

Client programs generally will not use these methods because the EnvironmentMode is set automatically when a Config is loaded. If the Config has an "environment" section, the mode is set to LOAD_PREDEFINED, and otherwise set to LOAD_ALL.

void OCIO_NAMESPACE::Config::setFamilySeparator ( char separator )

Set the family separator.

Succeeds if the characters is null or a valid character from the ASCII table i.e. from value 32 (i.e. space) to 126 (i.e. '~'); otherwise, it throws an exception.

void OCIO_NAMESPACE::Config::setFileRules ( ConstFileRulesRcPtr fileRules )

Set file rules.

Note: The argument is cloned.

void OCIO_NAMESPACE::Config::setInactiveColorSpaces ( const char * inactiveColorSpaces )

Set/get a list of inactive color space or named transform names.

Notes:

List can contain color space and/or named transform names.
The inactive spaces are color spaces that should not appear in application menus.
These color spaces will still work in Config::getProcessor calls.
The argument is a comma-delimited string. A null or empty string empties the list.
The environment variable OCIO_INACTIVE_COLORSPACES may also be used to set the inactive color space list.
The env. var. takes precedence over the inactive_colorspaces list in the config file.
Setting the list via the API takes precedence over either the env. var. or the config file list.

void OCIO_NAMESPACE::Config::setMajorVersion ( unsigned int major )

Set the configuration major version.

Throws if it is not supported. Resets minor to the most recent minor for the given major.

void OCIO_NAMESPACE::Config::setMinorVersion ( unsigned int minor )

Set the configuration minor version. Throws if it is not supported for the current major.

void OCIO_NAMESPACE::Config::setName ( const char * name )

noexcept

void OCIO_NAMESPACE::Config::setProcessorCacheFlags ( ProcessorCacheFlags flags )

noexcept

Control the caching of processors in the config instance. By default, caching is on. The flags allow turning caching off entirely or only turning it off if dynamic properties are being used by the processor.

void OCIO_NAMESPACE::Config::setRole	(	const char *	role,
		const char *	colorSpaceName
	)

Note: Setting the colorSpaceName name to a null string unsets it.

void OCIO_NAMESPACE::Config::setSearchPath ( const char * path )

Set all search paths as a concatenated string, use ':' to separate the paths.

See addSearchPath for a more robust and platform-agnostic method of setting the search paths.

void OCIO_NAMESPACE::Config::setStrictParsingEnabled ( bool enabled )

void OCIO_NAMESPACE::Config::setVersion	(	unsigned int	major,
		unsigned int	minor
	)

Set the configuration major and minor versions. Throws if version is not supported.

void OCIO_NAMESPACE::Config::setViewingRules ( ConstViewingRulesRcPtr viewingRules )

Set viewing rules.

Note: The argument is cloned.

void OCIO_NAMESPACE::Config::setWorkingDir ( const char * dirname )

The working directory defaults to the location of the config file. It is used to convert any relative paths to absolute. If no search paths have been set, the working directory will be used as the fallback search path. No environment (context) variables may be used in the working directory.

void OCIO_NAMESPACE::Config::upgradeToLatestVersion ( )

noexcept

Allows an older config to be serialized as the current version.

void OCIO_NAMESPACE::Config::validate ( ) const

Performs a thorough validation for the most common user errors.

This will throw an exception if the config is malformed. The most common error occurs when references are made to colorspaces that do not exist.

The documentation for this class was generated from the following file:

OpenColorIO/OpenColorIO.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation