All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
OCIO_NAMESPACE::ColorSpace Class Reference

#include <OpenColorIO.h>

Public Member Functions

ColorSpaceRcPtr createEditableCopy () const
const char * getName () const noexcept
void setName (const char *name) noexcept
 If the name is already an alias, that alias is removed. More...
size_t getNumAliases () const noexcept
const char * getAlias (size_t idx) const noexcept
 Return empty string if idx is out of range. More...
void addAlias (const char *alias) noexcept
void removeAlias (const char *alias) noexcept
 Does nothing if alias is not present. More...
void clearAliases () noexcept
const char * getFamily () const noexcept
void setFamily (const char *family)
 Set the family, for use in user interfaces (optional) More...
const char * getEqualityGroup () const noexcept
void setEqualityGroup (const char *equalityGroup)
const char * getDescription () const noexcept
void setDescription (const char *description)
BitDepth getBitDepth () const noexcept
void setBitDepth (BitDepth bitDepth)
ReferenceSpaceType getReferenceSpaceType () const noexcept
 A display color space will use the display-referred reference space. More...
bool hasCategory (const char *category) const
 Return true if the category is present. More...
void addCategory (const char *category)
 Add a single category. More...
void removeCategory (const char *category)
 Remove a category. More...
int getNumCategories () const
 Get the number of categories. More...
const char * getCategory (int index) const
 Return the category name using its index. More...
void clearCategories ()
 Clear all the categories. More...
const char * getEncoding () const noexcept
void setEncoding (const char *encoding)
bool isData () const noexcept
void setIsData (bool isData) noexcept
Allocation getAllocation () const noexcept
void setAllocation (Allocation allocation) noexcept
int getAllocationNumVars () const
void getAllocationVars (float *vars) const
void setAllocationVars (int numvars, const float *vars)
ConstTransformRcPtr getTransform (ColorSpaceDirection dir) const noexcept
void setTransform (const ConstTransformRcPtr &transform, ColorSpaceDirection dir)
 ColorSpace (const ColorSpace &)=delete
ColorSpaceoperator= (const ColorSpace &)=delete
 ~ColorSpace ()
 Do not use (needed only for pybind11). More...

Static Public Member Functions

static ColorSpaceRcPtr Create ()
static ColorSpaceRcPtr Create (ReferenceSpaceType referenceSpace)

Detailed Description

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

Definition at line 1465 of file OpenColorIO.h.

Constructor & Destructor Documentation

OCIO_NAMESPACE::ColorSpace::ColorSpace ( const ColorSpace )
OCIO_NAMESPACE::ColorSpace::~ColorSpace ( )

Do not use (needed only for pybind11).

Member Function Documentation

void OCIO_NAMESPACE::ColorSpace::addAlias ( const char *  alias)

Add an alias for the color space name (the aliases may be used as a synonym for the name). Nothing will be added if the alias is already the color space name, one of its aliases, or the argument is null. The aliases must not conflict with existing roles, color space names, named transform names, or other aliases. This is verified when adding the color space to the config.

void OCIO_NAMESPACE::ColorSpace::addCategory ( const char *  category)

Add a single category.

Will do nothing if the category already exists.
void OCIO_NAMESPACE::ColorSpace::clearAliases ( )
void OCIO_NAMESPACE::ColorSpace::clearCategories ( )

Clear all the categories.

static ColorSpaceRcPtr OCIO_NAMESPACE::ColorSpace::Create ( )
static ColorSpaceRcPtr OCIO_NAMESPACE::ColorSpace::Create ( ReferenceSpaceType  referenceSpace)
ColorSpaceRcPtr OCIO_NAMESPACE::ColorSpace::createEditableCopy ( ) const
const char* OCIO_NAMESPACE::ColorSpace::getAlias ( size_t  idx) const

Return empty string if idx is out of range.

Allocation OCIO_NAMESPACE::ColorSpace::getAllocation ( ) const


If this colorspace needs to be transferred to a limited dynamic range coding space (such as during display with a GPU path), use this allocation to maximize bit efficiency.

int OCIO_NAMESPACE::ColorSpace::getAllocationNumVars ( ) const

Specify the optional variable values to configure the allocation. If no variables are specified, the defaults are used.


2 vars: [min, max]


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

void OCIO_NAMESPACE::ColorSpace::getAllocationVars ( float vars) const
BitDepth OCIO_NAMESPACE::ColorSpace::getBitDepth ( ) const
const char* OCIO_NAMESPACE::ColorSpace::getCategory ( int  index) const

Return the category name using its index.

Will be null if the index is invalid.
const char* OCIO_NAMESPACE::ColorSpace::getDescription ( ) const
const char* OCIO_NAMESPACE::ColorSpace::getEncoding ( ) const


It is sometimes useful for applications to group color spaces based on how the color values are digitally encoded. For example, images in scene-linear, logarithmic, video, and data color spaces could have different default views. Unlike the Family and EqualityGroup attributes of a color space, the list of Encodings is predefined in the OCIO documentation (rather than being config-specific) to make it easier for applications to utilize.

Here is an example config entry that could appear under a ColorSpace:

encoding: scene-linear

Encoding strings are not case-sensitive. Although users may add their own encodings, the strings will typically come from a fixed set listed in the documentation (similar to roles).

const char* OCIO_NAMESPACE::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'.

const char* OCIO_NAMESPACE::ColorSpace::getFamily ( ) const

Get the family, for use in user interfaces (optional) The family string could use a '/' separator to indicate levels to be used by hierarchical menus.

const char* OCIO_NAMESPACE::ColorSpace::getName ( ) const
size_t OCIO_NAMESPACE::ColorSpace::getNumAliases ( ) const
int OCIO_NAMESPACE::ColorSpace::getNumCategories ( ) const

Get the number of categories.

ReferenceSpaceType OCIO_NAMESPACE::ColorSpace::getReferenceSpaceType ( ) const

A display color space will use the display-referred reference space.

ConstTransformRcPtr OCIO_NAMESPACE::ColorSpace::getTransform ( ColorSpaceDirection  dir) const


If a transform in the specified direction has been specified, return it. Otherwise return a null ConstTransformRcPtr

bool OCIO_NAMESPACE::ColorSpace::hasCategory ( const char *  category) const

Return true if the category is present.

A category is used to allow applications to filter the list of color spaces they display in menus based on what that color space is used for.

Here is an example config entry that could appear under a ColorSpace:

categories: [ file-io, working-space, basic-3d ]

The example contains three categories: 'file-io', 'working-space' and 'basic-3d'.

Category strings are not case-sensitive and the order is not significant.

There is no limit imposed on length or number. Although users may add their own categories, the strings will typically come from a fixed set listed in the documentation (similar to roles).

bool OCIO_NAMESPACE::ColorSpace::isData ( ) const


ColorSpaces that are data are treated a bit special. Basically, any colorspace transforms you try to apply to them are ignored. (Think of applying a gamut mapping transform to an ID pass). However, the setDataBypass method on ColorSpaceTransform and DisplayViewTransform allow applications to process data when necessary. (Think of sending mattes to an HDR monitor.)

This is traditionally used for pixel data that represents non-color pixel data, such as normals, point positions, ID information, etc.

ColorSpace& OCIO_NAMESPACE::ColorSpace::operator= ( const ColorSpace )
void OCIO_NAMESPACE::ColorSpace::removeAlias ( const char *  alias)

Does nothing if alias is not present.

void OCIO_NAMESPACE::ColorSpace::removeCategory ( const char *  category)

Remove a category.

Will do nothing if the category is missing.
void OCIO_NAMESPACE::ColorSpace::setAllocation ( Allocation  allocation)
void OCIO_NAMESPACE::ColorSpace::setAllocationVars ( int  numvars,
const float vars 
void OCIO_NAMESPACE::ColorSpace::setBitDepth ( BitDepth  bitDepth)
void OCIO_NAMESPACE::ColorSpace::setDescription ( const char *  description)
void OCIO_NAMESPACE::ColorSpace::setEncoding ( const char *  encoding)
void OCIO_NAMESPACE::ColorSpace::setEqualityGroup ( const char *  equalityGroup)
void OCIO_NAMESPACE::ColorSpace::setFamily ( const char *  family)

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

void OCIO_NAMESPACE::ColorSpace::setIsData ( bool  isData)
void OCIO_NAMESPACE::ColorSpace::setName ( const char *  name)

If the name is already an alias, that alias is removed.

void OCIO_NAMESPACE::ColorSpace::setTransform ( const ConstTransformRcPtr transform,
ColorSpaceDirection  dir 

Specify the transform for the appropriate direction. Setting the transform to null will clear it.

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