Bitmap Color Management Overview

The Bitmap class has properties and methods related to OCIO-based color management as well as the older gamma workflow — which ones are relevant depends on the color management settings of the scene.

In either case, the function Bitmap::GetPixels() returns pixels as they are represented in memory, and the function Bitmap::GetLinearPixels() returns the pixel colors in the rendering (i.e. physical) space:

• In OCIO mode, Bitmap::GetLinearPixels() applies the appropriate transform to convert from the bitmap's assigned color space. If the bitmap is already in the rendering space then the null transform is applied.
• In gamma mode, it performs an inverse gamma using the input gamma if the bitmap is in perceptual space. If the bitmap is already in physical space then it returns the pixels as is.

OCIO-based Modes

When using OCIO-based color management, BitmapInfo::ColorSpace() returns the assigned color space of the bitmap. You can also find extra color space information using related functions in BitmapInfo.

When saving, the default output conversion depends on the settings defined in IColorPipelineMgr. You can override this output conversion for an individual bitmap using BitmapInfo::SetOutputColorConversion.

Gamma Workflow

When using gamma-based color management, the bitmap gamma is used to convert between perceptual space and physical space representation of images. The precise usage of gamma depends on the kind of bitmap.

• Low Dynamic Range (LDR) bitmaps - This is the most common kind of bitmap. An LDR bitmap is virtually always in perceptual space. In 3ds Max an LDR bitmap is represented using the class BitmapStorageLDR.
• High Dynamic Range (HDR) bitmaps - HDR bitmaps are usually (as per recommendation) a representation of an image in physical space on disk. An example is the raw result of a render. In 3ds Max an HDR bitmap is represented using the class BitmapStorageLDR.

When a bitmap is loaded from disk into 3ds Max, the memory representation of a bitmap is as it is stored on disk. When a bitmap is the result of a render the memory representation will always be in physical space.

When saving a bitmap to disk:

• An LDR bitmap must be converted to perceptual space.
• An HDR bitmap must be saved as is (i.e. physical space).

The Two BitmapInfo Gamma Values

A BitmapInfo struct contains two gamma values: the file gamma and the custom gamma.

• File Gamma - The file gamma is the gamma which was embedded in the original file on disk. For bitmap file types that support this value it indicates the output gamma used when the file was originally save. The file gamma is accessed via BitmapInfo::Gamma() and set using BitmapInfo::SetGamma(). A bitmap will use file gamma as its input gamma if the BMM_CUSTOM_FILEGAMMA flag is set via BitmapInfo::SetCustomFlags().
• Custom Gamma - This is either an override gamma value provided by the user or the default gamma value, depending on options specified by the user when the file was loaded. It is important to set this to 1.0 for bump or displacement maps because they encode linear data. The custom gamma can be read using BitmapInfo::GetCustomGamma() and set using BitmapInfo::SetCustomGamma(). A bitmap will use the custom gamma as its input gamma if the BMM_CUSTOM_GAMMA flag is set via BitmapInfo::SetCustomFlags().

The method BitmapInfo::GetEffectiveGamma() will return either the custom gamma or file gamma, depending on the flags set in the bitmap.