Color Management Overview

3ds Max can work in three different color management modes: More...

Classes
class	ColorConverter< TSRC, TDST >
	This is a fully header-implemented class wrapping IColorEngine for type-safe color conversions. More...
class	IColorPipeline
	Interface class that defines color conversions from source color space to target color space. More...
class	IColorPipelineMgr
	This is the central class for handling system-wide color management related data and tasks. More...
class	ImageLayoutInfo
	Helper template class for providing memory layout information for various pixel data types. More...
class	QMaxSampleUnderlyingColorEvent
	Qt event used by the color picker system to request sampling of an underlying color. More...

Enumerations
enum	NotificationChangeMask : uint32_t {   ModeChanged = 1 << 0 , GammaModeSettingsChanged = 1 << 1 , OCIOModeSettingsChanged = 1 << 2 , InputSettingsChanged = 1 << 3 ,   OutputSettingsChanged = 1 << 4 , RenderingSpaceChanged = 1 << 5 , DisplayViewChanged = 1 << 6 , ParameterSpaceChanged = 1 << 7 ,   ModeReInitialized = 1 << 8 , ModeLockStateChanged = 1 << 9 }
	Change bit-mask that are passed with color management notification messages. More...
enum class	ColorPipelineMode : uint8_t {   kUNMANAGED , kGAMMA , kOCIO_DEFAULT , kOCIO_CUSTOM ,   kOCIO_ENVVAR , kNumColorPipelineModes }
	Enum for color management modes. More...
enum class	ModeStatus : uint8_t { kNORMAL , kFALLBACK_RAW , kINVALID }
	Enum for color management modes. More...
enum class	ConfigSource : uint8_t { kBUILT_IN , kENV_VARIABLE , kUSER_DEFINED }
	Enum for source of the config file that's used in the mode. More...
enum class	DisplayViewTarget : uint8_t {   kGLOBAL , kVIEWPORT , kFRAME_BUFFER , kMTL_EDITOR ,   kCOLOR_PICKER , kCOLOR_SWATCH , kNumDisplayViewTargets }
	Enum for identifying display/view pair targets. More...
enum class	OutputFormatType : uint8_t { kGAMMA_ENCODED , kLINEAR , kNumOutputFormatTypes }
	Enum for color management modes. More...
enum class	OutputConversion : uint8_t { kNO_CONVERSION , kCOLOR_SPACE_CONVERSION , kDISPLAY_VIEWTRANSFORM }
	Enum for Output Color conversion options. More...
enum class	ColorSpaceFlags : uint32_t {   kNONE = 0ul , kEXISTS = 1ul << 0 , kIS_DATA = 1ul << 1 , kHAS_FILETRANSFORM = 1ul << 2 ,   kIS_NAMEDTRANSFORM = 1ul << 3 }
	Flags that provide some information on color spaces. More than one flags can be present. More...
enum class	ListOptions : uint32_t { kNONE = 0ul , kUI_NAME = 1ul << 0 , kINCLUDE_ROLES = 1ul << 1 }
	Flags that can be passed to functions operating on lists (such as GetNumFileIOColorSpaces() ) to control the list content. More...
enum class	ColSpaceStatus { NotSet = 0 , Normal , ForcedDefault , Invalid }
	Enum for color space assignment state. More...
enum class	ColSpaceSource { NotSet = 0 , InputRules , User , SystemHeuristics }
	Enum for indicating the source of the assigned color space. More...

Detailed Description

3ds Max can work in three different color management modes:

• Unmanaged: All the color swatches and the bitmap pixel values are used as-is, i.e. no physical to perceptual conversions (like gamma encoding/decoding) will be performed.
• Gamma: This is also called "de-gamma/re-gamma work flow". In this mode all the input colors and textures are converted to linear space using the input gamma values. Similarly all the output colors are properly gamma-encoded for the output medium (monitor, file, etc). The color computations (like rendering) are done in linear (scene-referred) space. This mode assumes that all of the colors are expressed in the same color gamut (typically sRGB).

• OpenColorIO: There are two OCIO modes (ColorPipelineMode::kOCIO_DEFAULT and ColorPipelineMode::kOCIO_CUSTOM) which are the most powerful color management modes 3ds Max provides. In these modes the user can use textures and colors from different color spaces, can pick any linear color space (such as ACEScg) to perform renderings in, can work on monitors with different color gamuts and can save images in various color spaces with different view transforms applied. This mode uses OpenColorIO as the color management engine and the available color spaces, displays, transforms etc are defined in OCIO config files.

  IColorPipelineMgr is the central hub for controlling and querying the active color management mode, available color spaces, displays, views and and accessing the other settings. IModeSettings class provides access to detailed settings of each mode. (see IColorPipelineMgr::Settings() )

  If you need to convert colors from one color space to another, you'll need to create objects of class IColorPipeline. You can create IColorPipeline objects using various methods of the IColorPipelineMgr class. Although IColorPipeline defines the operations needed to transform colors, it can not do the computations by itself. The actual conversions are done by the ColorConverter class which is a template class and can perform operations in an optimized way for the specified input and output data types.

  Here is an example showing how the classes relate to each other and how to use them in some simple scenarios.

  // Get the pointer to the IColorPipelineMgr instance.  
  IColorPipelineMgr* colorPipelineMgr = IColorPipelineMgr::GetInstance();  
   
  // Get the pipeline for transforming colors from the current rendering space  
  // to default display/view pair.  
  auto pipeline = colorPipelineMgr->GetDefaultViewingPipeline();  
   
  // Get two converters, one for Color->BMM_Color_32, other for  
  // BMM_Color_64->BMM_Color_64 pixel data types.  
  auto conv_Flto32 = pipeline->GetColorConverter<Color, BMM_Color_32>();  
  auto conv_64to64 = pipeline->GetColorConverter<BMM_Color_64, BMM_Color_64>();  
   
  // Example 1: single color conversion from Color in rendering color space to  
  // BMM_Color_32 in default display/view color space.  
  BMM_Color_32 out32 = conv_Flto32->ConvertColor(Color(1.0f, 0.5f, 0.25f));
   
  // Example 2: in-place image conversion in parallel  
  BMM_Color_64 myImage[1280 * 1024];  
  parallel_for(  
      ...,  
      [&](...)  
      {  
          BMM_Color_64* bufferSliceForThread = ...  
          size_t sliceHeight = ...  
          conv_64to64->ConvertImage(bufferSliceForThread, 1280, sliceHeight);  
      }  
  );  

Enumeration Type Documentation

NotificationChangeMask

enum NotificationChangeMask : uint32_t

Change bit-mask that are passed with color management notification messages.

This bit mask is passed in NotifyInfo::callParam with the NOTIFY_COLOR_MANAGEMENT_POST_CHANGE and NOTIFY_COLOR_MANAGEMENT_POST_CHANGE2 notification codes. In rare occasions it's possible to get those notifications with none of the bits set, this happens during the "load color management settings" operation for example, where the loaded settings are the same as the previous ones.

Enumerator
ModeChanged	Color management mode has changed.
GammaModeSettingsChanged	Settings which are used in the ColorPipelineMode::kGAMMA mode have changed.
OCIOModeSettingsChanged	Settings which are used in the OCIO modes have changed.
InputSettingsChanged	Settings that affect the color management settings that are used in bitmap loading have changed.
OutputSettingsChanged	Settings that affect the color management settings that are used in bitmap saving have changed.
RenderingSpaceChanged	Rendering (working) color space has changed.
DisplayViewChanged	One or more of the display/view settings have changed.
ParameterSpaceChanged	The color space in which the color literals are stored has changed.
ModeReInitialized	Depending on the situation, re-initialization may change multiple things or may change nothing. Assume everything is changed.
ModeLockStateChanged	OCIO config path's lock state is changed in the ColorPipelineMode::kOCIO_CUSTOM mode.

{
    ModeChanged             = 1 << 0,   
    GammaModeSettingsChanged= 1 << 1,   
    OCIOModeSettingsChanged = 1 << 2,   
    InputSettingsChanged    = 1 << 3,   
    OutputSettingsChanged   = 1 << 4,   
    RenderingSpaceChanged   = 1 << 5,   
    DisplayViewChanged      = 1 << 6,   
    ParameterSpaceChanged   = 1 << 7,   
    ModeReInitialized       = 1 << 8,   
    ModeLockStateChanged    = 1 << 9,   
};

ColorPipelineMode

enum class ColorPipelineMode : uint8_t

strong

Enum for color management modes.

Enumerator
kUNMANAGED	Color management turned off.
kGAMMA	Color management using de-gamma/re-gamma work flow.
kOCIO_DEFAULT	Uses the built-in OCIO config.
kOCIO_CUSTOM	Uses custom OCIO config.
kOCIO_ENVVAR	Using the config file pointed by the OCIO environment variable.
kNumColorPipelineModes

{
    kUNMANAGED,     
    kGAMMA,         
    kOCIO_DEFAULT,  
    kOCIO_CUSTOM,   
    kOCIO_ENVVAR,   
 
    kNumColorPipelineModes
};

ColSpaceStatus

enum class ColSpaceStatus

strong

Enum for color space assignment state.

In a modern color management system, color holding entities (such as bitmaps) need to have valid color spaces assigned to them so that they can be converted to and from the working (rendering) color space. Unlike the floating point gamma value used in the simple de-gamma/re-gamma work flows, the assigned color space may not always be a valid value, therefore it's important to keep track of the assigned color space and validity of it all the time. This enum provides different states the color space assignment may be in.

See also

BitmapInfo::ColorSpace, BitmapInfo::ColorSpaceStatus

Enumerator
NotSet	No color space is assigned yet.
Normal	A valid color space is assigned. Things are healthy.
ForcedDefault	System has force-assigned a color space probably because a previously assigned color space became unavailable.
Invalid	Assigned color space is invalid, things will not work properly. See also BitmapInfo::ValidateColorSpace

{
    NotSet = 0,     
    Normal,         
    ForcedDefault,  
    Invalid,        
};

ModeStatus

enum class ModeStatus : uint8_t

strong

Enum for color management modes.

Enumerator
kNORMAL	Mode is initialized as intended and is healthy.
kFALLBACK_RAW	Mode initialization failed but initialized as "raw". If this mode is selected 3ds Max will operate as colors unmanaged.
kINVALID	Something terrible happened, Switching to this mode may make system unstable.

{
    kNORMAL,       
    kFALLBACK_RAW, 
    kINVALID,      
};

ConfigSource

enum class ConfigSource : uint8_t

strong

Enum for source of the config file that's used in the mode.

Enumerator
kBUILT_IN	The OCIO Setting is based on a build-in OCIO config.
kENV_VARIABLE	The OCIO Setting is based on a OCIO config file specified by the 'OCIO' environment variable.
kUSER_DEFINED	The OCIO Setting is based on a user-provided OCIO config file.

{
    kBUILT_IN,     
    kENV_VARIABLE, 
    kUSER_DEFINED  
};

DisplayViewTarget

enum class DisplayViewTarget : uint8_t

strong

Enum for identifying display/view pair targets.

Enumerator
kGLOBAL	The Global default - all automatic view targets derive from this.
kVIEWPORT	The Viewport.
kFRAME_BUFFER	The FrameBuffer.
kMTL_EDITOR	The Material Editor.
kCOLOR_PICKER	The Color Picker - the Color Swatch will derive from this, if it is set to automatic.
kCOLOR_SWATCH	The Color Swatch - when set to automatic, the value from the Color-Picker will be derived.
kNumDisplayViewTargets

{
    kGLOBAL,       
    kVIEWPORT,     
    kFRAME_BUFFER, 
    kMTL_EDITOR,   
    kCOLOR_PICKER, 
    kCOLOR_SWATCH, 
 
    kNumDisplayViewTargets
};

OutputFormatType

enum class OutputFormatType : uint8_t

strong

Enum for color management modes.

Enumerator
kGAMMA_ENCODED	Image file formats that use gamma encoding (such as jpeg, png etc).
kLINEAR	Image file formats that use linear and log encoding (hdr, exr etc). See also BitmapIOMetaData::UseLinearStorage()
kNumOutputFormatTypes

{
    kGAMMA_ENCODED,   
    kLINEAR,          
 
    kNumOutputFormatTypes
};

OutputConversion

enum class OutputConversion : uint8_t

strong

Enum for Output Color conversion options.

Enumerator
kNO_CONVERSION	No conversion - output images will be saved in the Rendering Color Space.
kCOLOR_SPACE_CONVERSION	Color Space conversion: output images will be converted into the given Output Color Space.
kDISPLAY_VIEWTRANSFORM	Display/View Transform: output images will be converted into the given Display Color Space and and optionally given View Transform may be applied.

{
    kNO_CONVERSION,          
    kCOLOR_SPACE_CONVERSION, 
    kDISPLAY_VIEWTRANSFORM,  
};

ColorSpaceFlags

enum class ColorSpaceFlags : uint32_t

strong

Flags that provide some information on color spaces. More than one flags can be present.

Enumerator
kNONE
kEXISTS	This color space exists. If flags is zero passed color space name is not valid.
kIS_DATA	This is a data color space, colors won't be altered by the color pipelines.
kHAS_FILETRANSFORM	Color space has one or more file transforms in its definition.
kIS_NAMEDTRANSFORM	This is a named transform.

{
    kNONE               = 0ul,
    kEXISTS             = 1ul << 0, 
    kIS_DATA            = 1ul << 1, 
    kHAS_FILETRANSFORM  = 1ul << 2, 
    kIS_NAMEDTRANSFORM  = 1ul << 3  
};

ListOptions

enum class ListOptions : uint32_t

strong

Flags that can be passed to functions operating on lists (such as GetNumFileIOColorSpaces() ) to control the list content.

Enumerator
kNONE
kUI_NAME	Instead of returning original names, return decorated UI names (which may not be valid names to pass to functions).
kINCLUDE_ROLES	Color space lists will include roles in them.

{
    kNONE           = 0ul,
    kUI_NAME        = 1ul << 0, 
    kINCLUDE_ROLES  = 1ul << 1, 
};

ColSpaceSource

enum class ColSpaceSource

strong

Enum for indicating the source of the assigned color space.

In a modern color management system, color holding entities (such as bitmaps) need to have valid color spaces assigned to them so that they can be converted to and from the working (rendering) color space. This assignment can be done automatically based on the file name or type or can be done explicitly by the users. 3ds Max keeps track of the source of the color space assignment so that if for some reason color space becomes unavailable (see ColSpaceStatus), an informed decision can be made to re-assign one of the currently available color spaces. Knowing the source of the color space assignment will also make trouble shooting a color space related problems easier.

See also

BitmapInfo::ColorSpaceSource, BitmapInfo::SetRequestedColorSpace, BitmapInfo::GetRequestedColorSpaceSource

Enumerator
NotSet	No color space is assigned yet.
InputRules	Color space assigned automatically based on the file name (see GetColorSpaceFromImageFilePath).
User	User has assigned color space manually.
SystemHeuristics	System heuristics are used to assign most suitable color space.

{
    NotSet = 0,         
    InputRules,         
    User,               
    SystemHeuristics,   
};