Exceptions¶

class Exception¶

An exception class to throw for errors detected at runtime.

Warning

All functions in the Config class can potentially throw this exception.

Exception::Exception(const char*)¶

Constructor that takes a string as the exception message.

Exception::Exception(const Exception&)

Constructor that takes an exception pointer.

Exception& Exception::operator=(const Exception&)¶

Constructor that takes an exception pointer and returns an exception pointer (???).

Exception::~Exception()¶

const char* Exception::what() const¶

class ExceptionMissingFile¶

An exception class for errors detected at runtime, thrown when OCIO cannot find a file that is expected to exist. This is provided as a custom type to distinguish cases where one wants to continue looking for missing files, but wants to properly fail for other error conditions.

ExceptionMissingFile::ExceptionMissingFile(const char*)¶

Constructor that takes a string as the exception message.

ExceptionMissingFile::ExceptionMissingFile(const ExceptionMissingFile&)

Constructor that takes an existing exception.

Global¶

void ClearAllCaches()¶

OpenColorIO, during normal usage, tends to cache certain information (such as the contents of LUTs on disk, intermediate results, etc.). Calling this function will flush all such information. Under normal usage, this is not necessary, but it can be helpful in particular instances, such as designing OCIO profiles, and wanting to re-read luts without restarting.

const char* GetVersion()¶

Get the version number for the library, as a dot-delimited string (e.g., “1.0.0”). This is also available at compile time as OCIO_VERSION.

int GetVersionHex()¶

Get the version number for the library, as a single 4-byte hex number (e.g., 0x01050200 for “1.5.2”), to be used for numeric comparisons. This is also available at compile time as OCIO_VERSION_HEX.

LoggingLevel GetLoggingLevel()¶

Get the global logging level. You can override this at runtime using the OCIO_LOGGING_LEVEL environment variable. The client application that sets this should use SetLoggingLevel(), and not the environment variable. The default value is INFO.

void SetLoggingLevel(LoggingLevel level)¶

Set the global logging level.

Config¶

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 DisplayTransform 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 OCIO environment variable to point at the root of that configuration.

See Usage Examples

ConstConfigRcPtr GetCurrentConfig()¶

Get the current configuration.

void SetCurrentConfig(const ConstConfigRcPtr& config)¶

Set the current configuration. This will then store a copy of the specified config.

class Config¶

ColorSpace¶

The ColorSpace is the state of an image with respect to colorimetry and color encoding. Transforming images between different ColorSpaces is the primary motivation for this library.

While a complete discussion of color spaces is beyond the scope of header documentation, traditional uses would be to have ColorSpaces corresponding to: physical capture devices (known cameras, scanners), and internal ‘convenience’ spaces (such as scene linear, logarithmic).

ColorSpaces are specific to a particular image precision (float32, uint8, etc.), and the set of ColorSpaces that provide equivalent mappings (at different precisions) are referred to as a ‘family’.

class ColorSpace¶

static ColorSpaceRcPtr ColorSpace::Create()¶

ColorSpaceRcPtr ColorSpace::createEditableCopy() const¶

const char* ColorSpace::getName() const¶

void ColorSpace::setName(const char* name)¶

const char* ColorSpace::getFamily() const¶

Get the family, for use in user interfaces (optional)

void ColorSpace::setFamily(const char* family)¶

Set the family, for use in user interfaces (optional)

const char* ColorSpace::getEqualityGroup() const¶

Get the ColorSpace group name (used for equality comparisons) This allows no-op transforms between different colorspaces. If an equalityGroup is not defined (an empty string), it will be considered unique (i.e., it will not compare as equal to other ColorSpaces with an empty equality group). This is often, though not always, set to the same value as ‘family’.

void ColorSpace::setEqualityGroup(const char* equalityGroup)¶

const char* ColorSpace::getDescription() const¶

void ColorSpace::setDescription(const char* description)¶

BitDepth ColorSpace::getBitDepth() const¶

void ColorSpace::setBitDepth(BitDepth bitDepth)¶

2 vars: [min, max]

2 vars: [lg2min, lg2max]
3 vars: [lg2min, lg2max, linear_offset]

Look¶

The Look is an ‘artistic’ image modification, in a specified image state. The processSpace defines the ColorSpace the image is required to be in, for the math to apply correctly.

class Look¶

static LookRcPtr Look::Create()¶

LookRcPtr Look::createEditableCopy() const¶

const char* Look::getName() const¶

void Look::setName(const char* name)¶

const char* Look::getProcessSpace() const¶

void Look::setProcessSpace(const char* processSpace)¶

ConstTransformRcPtr Look::getTransform() const¶

void Look::setTransform(const ConstTransformRcPtr& transform)¶

Setting a transform to a non-null call makes it allowed.

ConstTransformRcPtr Look::getInverseTransform() const¶

void Look::setInverseTransform(const ConstTransformRcPtr& transform)¶

Setting a transform to a non-null call makes it allowed.

const char* Look::getDescription() const¶

void Look::setDescription(const char* description)¶

Processor¶

class Processor¶

static ProcessorRcPtr Processor::Create()¶

bool Processor::isNoOp() const¶

bool Processor::hasChannelCrosstalk() const¶

does the processor represent an image transformation that

introduces crosstalk between the image channels

ConstProcessorMetadataRcPtr Processor::getMetadata() const¶

shaderFcnName(in half4 inPixel, const uniform sampler3D lut3d)

Baker¶

In certain situations it is necessary to serialize transforms into a variety of application specific lut formats. The Baker can be used to create lut formats that ocio supports for writing.

Usage Example: Bake a houdini sRGB viewer lut

OCIO::ConstConfigRcPtr config = OCIO::Config::CreateFromEnv();
OCIO::BakerRcPtr baker = OCIO::Baker::Create();
baker->setConfig(config);
baker->setFormat("houdini"); // set the houdini type
baker->setType("3D"); // we want a 3D lut
baker->setInputSpace("lnf");
baker->setShaperSpace("log");
baker->setTargetSpace("sRGB");
std::ostringstream out;
baker->bake(out); // fresh bread anyone!
std::cout << out.str();

static BakerRcPtr Create()¶

create a new Baker

BakerRcPtr createEditableCopy() const¶

create a copy of this Baker

void setConfig(const ConstConfigRcPtr& config)¶

set the config to use

ConstConfigRcPtr getConfig() const¶

get the config to use

void setFormat(const char* formatName)¶

set the lut output format

const char* getFormat() const¶

get the lut output format

void setType(const char* type)¶

set the lut output type (1D or 3D)

const char* getType() const¶

get the lut output type

void setMetadata(const char* metadata)¶

set optional meta data for luts that support it

const char* getMetadata() const¶

get the meta data that has been set

void setInputSpace(const char* inputSpace)¶

set the input ColorSpace that the lut will be applied to

const char* getInputSpace() const¶

get the input ColorSpace that has been set

void setShaperSpace(const char* shaperSpace)¶

set an optional ColorSpace to be used to shape / transfer the input colorspace. This is mostly used to allocate an HDR luminance range into an LDR one. If a shaper space is not explicitly specified, and the file format supports one, the ColorSpace Allocation will be used

const char* getShaperSpace() const¶

get the shaper colorspace that has been set

void setLooks(const char* looks)¶

set the looks to be applied during baking Looks is a potentially comma (or colon) delimited list of lookNames, Where +/- prefixes are optionally allowed to denote forward/inverse look specification. (And forward is assumed in the absence of either)

const char* getLooks() const¶

get the looks to be applied during baking

void setTargetSpace(const char* targetSpace)¶

set the target device colorspace for the lut

const char* getTargetSpace() const¶

get the target colorspace that has been set

void setShaperSize(int shapersize)¶

override the default the shaper sample size, default: <format specific>

int getShaperSize() const¶

get the shaper sample size

void setCubeSize(int cubesize)¶

override the default cube sample size default: <format specific>

int getCubeSize() const¶

get the cube sample size

void bake(std::ostream& os) const¶

bake the lut into the output stream

static int getNumFormats()¶

get the number of lut writers

static const char* getFormatNameByIndex(int index)¶

get the lut writer at index, return empty string if an invalid index is specified

ImageDesc¶

const ptrdiff_t AutoStride¶

AutoStride

class ImageDesc¶

This is a light-weight wrapper around an image, that provides a context for pixel access. This does NOT claim ownership of the pixels or copy image data

ImageDesc::~ImageDesc()¶

GpuShaderDesc¶

class GpuShaderDesc¶

GpuShaderDesc::GpuShaderDesc()¶

GpuShaderDesc::~GpuShaderDesc()¶

void GpuShaderDesc::setLanguage(GpuLanguage lang)¶

Set the shader program language

GpuLanguage GpuShaderDesc::getLanguage() const¶

void GpuShaderDesc::setFunctionName(const char* name)¶

Set the function name of the shader program

const char* GpuShaderDesc::getFunctionName() const¶

void GpuShaderDesc::setLut3DEdgeLen(int len)¶

int GpuShaderDesc::getLut3DEdgeLen() const¶

const char* GpuShaderDesc::getCacheID() const¶

Context¶

class Context¶

static ContextRcPtr Context::Create()¶

ContextRcPtr Context::createEditableCopy() const¶

const char* Context::getCacheID() const¶

void Context::setSearchPath(const char* path)¶

const char* Context::getSearchPath() const¶

void Context::setWorkingDir(const char* dirname)¶

const char* Context::getWorkingDir() const¶

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

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

int Context::getNumStringVars() const¶

const char* Context::getStringVarNameByIndex(int index) const¶

void Context::clearStringVars()¶

void Context::setEnvironmentMode(EnvironmentMode mode)¶

EnvironmentMode Context::getEnvironmentMode() const¶

void Context::loadEnvironment()¶

Seed all string vars with the current environment.

const char* Context::resolveStringVar(const char* val) const¶

Do a file lookup.

Evaluate the specified variable (as needed). Will not throw exceptions.

const char* Context::resolveFileLocation(const char* filename) const¶

Do a file lookup.

Evaluate all variables (as needed). Also, walk the full search path until the file is found. If the filename cannot be found, an exception will be thrown.