OCIO_NAMESPACE::Context Class Reference

#include <OpenColorIO.h>

Public Member Functions
ContextRcPtr	createEditableCopy () const
const char *	getCacheID () const
void	setSearchPath (const char *path)
const char *	getSearchPath () const
int	getNumSearchPaths () const
const char *	getSearchPath (int index) const
void	clearSearchPaths ()
void	addSearchPath (const char *path)
void	setWorkingDir (const char *dirname)
const char *	getWorkingDir () const
void	setStringVar (const char *name, const char *value) noexcept
const char *	getStringVar (const char *name) const noexcept
int	getNumStringVars () const
const char *	getStringVarNameByIndex (int index) const
const char *	getStringVarByIndex (int index) const
void	clearStringVars ()
void	addStringVars (const ConstContextRcPtr &ctx) noexcept
	Add to the instance all the context variables from ctx. More...
void	setEnvironmentMode (EnvironmentMode mode) noexcept
	See Config::setEnvironmentMode. More...
EnvironmentMode	getEnvironmentMode () const noexcept
void	loadEnvironment () noexcept
	Seed string vars with the current environment, based on the EnvironmentMode setting. More...
const char *	resolveStringVar (const char *string) const noexcept
const char *	resolveStringVar (const char *string, ContextRcPtr &usedContextVars) const noexcept
const char *	resolveFileLocation (const char *filename) const
const char *	resolveFileLocation (const char *filename, ContextRcPtr &usedContextVars) const
void	setConfigIOProxy (ConfigIOProxyRcPtr ciop)
ConfigIOProxyRcPtr	getConfigIOProxy () const
	Context (const Context &)=delete
Context &	operator= (const Context &)=delete
	~Context ()
	Do not use (needed only for pybind11). More...

Static Public Member Functions
static ContextRcPtr	Create ()

Detailed Description

Context

A context defines some overrides to a Config. For example, it can override the search path or change the value of a context variable.

Note

Only some Config::getProcessor methods accept a custom context; otherwise, the default context instance is used (see Config::getCurrentContext).

Context Variables

The context variables allow changes at runtime using environment variables. For example, a color space name (such as src & dst for the ColorSpaceTransform) or a file name (such as LUT file name for the FileTransform) could be defined by context variables. The color transformation is then customized based on some environment variables.

In a config the context variables support three syntaxes (i.e. ${VAR}, $VAR and VAR%) and the parsing starts from longest to shortest. So, the resolve works like '$TEST_$TESTING_$TE' expands in this order '2 1 3'.

Config authors are recommended to include the "environment" section in their configs. This improves performance as well as making the config more readable. When present, this section must declare all context variables used in the config. It may also provide a default value, in case the variable is not present in the user's environment.

A context variable may only be used in the following places:

• the ColorSpaceTransform to define the source and the destination color space names,
• the FileTransform to define the source file name (e.g. a LUT file name),
• the search_path,
• the cccid of the FileTransform to only extract one specific transform from the CDL & CCC files.

Some specific restrictions are worth calling out:

• they cannot be used as either the name or value of a role,
• the context variable characters $ and % are prohibited in a color space name.

Definition at line 3437 of file OpenColorIO.h.

Constructor & Destructor Documentation

OCIO_NAMESPACE::Context::Context ( const Context &  )

delete

OCIO_NAMESPACE::Context::~Context

(

)

Do not use (needed only for pybind11).

Member Function Documentation

void OCIO_NAMESPACE::Context::addSearchPath

(

const char *

path

)

void OCIO_NAMESPACE::Context::addStringVars ( const ConstContextRcPtr &  ctx )

noexcept

Add to the instance all the context variables from ctx.

void OCIO_NAMESPACE::Context::clearSearchPaths

(

)

void OCIO_NAMESPACE::Context::clearStringVars

(

)

static ContextRcPtr OCIO_NAMESPACE::Context::Create ( )

static

ContextRcPtr OCIO_NAMESPACE::Context::createEditableCopy

(

)

const

const char* OCIO_NAMESPACE::Context::getCacheID

(

)

const

ConfigIOProxyRcPtr OCIO_NAMESPACE::Context::getConfigIOProxy

(

)

const

EnvironmentMode OCIO_NAMESPACE::Context::getEnvironmentMode ( ) const

noexcept

int OCIO_NAMESPACE::Context::getNumSearchPaths

(

)

const

int OCIO_NAMESPACE::Context::getNumStringVars

(

)

const

const char* OCIO_NAMESPACE::Context::getSearchPath

(

)

const

const char* OCIO_NAMESPACE::Context::getSearchPath

(

int

index

)

const

const char* OCIO_NAMESPACE::Context::getStringVar ( const char *  name ) const

noexcept

Get the context variable value. It returns an empty string if the context variable is null or does not exist.

const char* OCIO_NAMESPACE::Context::getStringVarByIndex

(

int

index

)

const

const char* OCIO_NAMESPACE::Context::getStringVarNameByIndex

(

int

index

)

const

const char* OCIO_NAMESPACE::Context::getWorkingDir

(

)

const

void OCIO_NAMESPACE::Context::loadEnvironment ( )

noexcept

Seed string vars with the current environment, based on the EnvironmentMode setting.

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

delete

const char* OCIO_NAMESPACE::Context::resolveFileLocation

(

const char *

filename

)

const

Build the resolved and expanded filepath using the search_path when needed, and check if the filepath exists. If it cannot be resolved or found, an exception will be thrown. The method argument is directly from the config file so it can be an absolute or relative file path or a file name.

Note

The filepath existence check could add a performance hit.

The context variable resolution is performed using :cpp:func:resolveStringVar.

const char* OCIO_NAMESPACE::Context::resolveFileLocation	(	const char *	filename,
		ContextRcPtr &	usedContextVars
	)		const

Build the resolved and expanded filepath and return all the context variables used to resolve the filename (empty if no context variables were used).

const char* OCIO_NAMESPACE::Context::resolveStringVar ( const char *  string ) const

noexcept

Resolve all the context variables from the string. It could be color space names or file names. Note that it recursively applies the context variable resolution. Returns the string unchanged if it does not contain any context variable.

const char* OCIO_NAMESPACE::Context::resolveStringVar ( const char *  string, ContextRcPtr &  usedContextVars  ) const

noexcept

Resolve all the context variables from the string and return all the context variables used to resolve the string (empty if no context variables were used).

void OCIO_NAMESPACE::Context::setConfigIOProxy

(

ConfigIOProxyRcPtr

ciop

)

Set the ConfigIOProxy object used to provision the config and LUTs from somewhere other than the file system.

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

noexcept

See Config::setEnvironmentMode.

void OCIO_NAMESPACE::Context::setSearchPath

(

const char *

path

)

void OCIO_NAMESPACE::Context::setStringVar ( const char *  name, const char *  value  )

noexcept

Add (or update) a context variable. But it removes it if the value argument is null. Note that a Context StringVar is the same thing as a Config EnvironmentVar and these are both often referred to as a "context var".

void OCIO_NAMESPACE::Context::setWorkingDir

(

const char *

dirname

)

---

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

• OpenColorIO/OpenColorIO.h