About

MultipassBitmap is a subclass of BaseBitmap that provides support for multiple folders and layers. Such a folder or layer is represented as another MultipassBitmap.

Warning
For MAXON API image classes see Images Manual. For MAXON API media input and output see Media Sessions Manual.
// This example creates a new MultipassBitmap with a custom layer.
// The bitmap is saved as a multi layer TIFF file.
const Int32 width = 1920;
const Int32 height = 1080;
const COLORMODE colorMode = COLORMODE::RGBf;
// create MultipassBitmap with the given dimensions and color mode
MultipassBitmap* multipassBitmap = MultipassBitmap::Alloc(width, height, colorMode);
if (multipassBitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// add a new layer
MultipassBitmap* const layer = multipassBitmap->AddLayer(nullptr, colorMode);
if (layer)
{
layer->SetParameter(MPBTYPE::NAME, "Custom Layer");
// fill layer
const Int32 bufferSize = width * 3; // rgb
ifnoerr (PIX_F * lineBuffer = NewMemClear(PIX_F, bufferSize))
{
for (Int32 y = 0; y < height; ++y)
{
const Float32 red = Float32(y) / Float32(height);
Int32 offset = 0;
for (Int32 x = 0; x < width; ++x)
{
const Float32 green = Float32(x) / Float32(width);
// fill line buffer
lineBuffer[offset] = red;
lineBuffer[offset + 1] = green;
lineBuffer[offset + 2] = 0;
offset = offset + 3;
}
// fill line
layer->SetPixelCnt(0, y, width, (UChar*)lineBuffer, COLORBYTES_RGBf, colorMode, PIXELCNT::NONE);
}
DeleteMem(lineBuffer);
}
}
// save to file
Filename imageFileName;
// select a file name
if (imageFileName.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::SAVE, "Save Image File"_s))
{
imageFileName = GeFilterSetSuffix(imageFileName, FILTER_TIF);
// save as multi layer 32-bit TIF
const IMAGERESULT res = multipassBitmap->Save(imageFileName, FILTER_TIF, nullptr, bits);
if (res != IMAGERESULT::OK)
ApplicationOutput("Error saving image.");
}
// destroy MultipassBitmap
MultipassBitmap::Free(multipassBitmap);

Access

A MultipassBitmap can be cast into a VPBuffer and vice versa in the rendering pipeline. If a given BaseBitmap pointer refers to a MultipassBitmap can be checked with BaseBitmap::IsMultipassBitmap().

Allocation/Deallocation

A MultipassBitmap can be created with the usual tools:

// This example creates a new MultipassBitmap.
const Int32 width = 1920;
const Int32 height = 1080;
const COLORMODE colorMode = COLORMODE::RGB;
// allocate MultipassBitmap with the given settings
MultipassBitmap* multipassBitmap = MultipassBitmap::Alloc(width, height, colorMode);
if (multipassBitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// use MultipassBitmap
// destroy MultipassBitmap
MultipassBitmap::Free(multipassBitmap);

A multi-layer image file can also be loaded into a MultipassBitmap using BaseBitmap::Init():

// This example lets the user select an image file that will be loaded.
// If the loaded image contains layers the layout count is printed.
Filename selectedImageFile;
// select image file
if (!selectedImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image"_s))
return maxon::OK;
// load image file
BaseBitmap* bitmap = nullptr;
const IMAGERESULT result = BaseBitmap::Init(bitmap, selectedImageFile);
// check success
if (result != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(selectedImageFile, MAXONCONVERTMODE::NONE), "Could not load image file."_s);
// check if it is a MultipassBitmap
if (bitmap->IsMultipassBitmap())
{
MultipassBitmap* const multipassBitmap = static_cast<MultipassBitmap*>(bitmap);
// get layer count
const Int32 layerCount = multipassBitmap->GetLayerCount();
ApplicationOutput("Layer Count: " + String::IntToString(layerCount));
}
else
{
// no MultipassBitmap, no layers
ApplicationOutput("No layers");
}

The image data stored in the layers can easily be deleted with:

Properties

Parameters

Multiple parameters can be set to define the behaviour of a given layer:

Note
Since a MultipassBitmap is used within the rendering pipeline some of these parameters are only relevant in that context.

The parameter IDs are:

Some of these parameters can be directly accessed with these convenience functions:

// This example adds and configures a new MultipassBitmap layer.
// add a new layer
MultipassBitmap* const layer = multipassBitmap->AddLayer(nullptr, colorMode);
if (layer)
{
// configure new layer
layer->SetName("New Layer"_s);
layer->SetParameter(MPBTYPE::SHOW, true);
layer->SetParameter(MPBTYPE::SAVE, false);
}
// show bitmap in Picture Viewer
ShowBitmap(multipassBitmap);

Layers

A MultipassBitmap can contain default layers, alpha layers and hidden layers:

These layers are accessed with:

// This example loops through all layers of
// the given MultipassBitmap.
// get layer count
const Int32 layerCount = multipassBitmap->GetLayerCount();
// loop through all layers
for (Int32 layerIndex = 0; layerIndex < layerCount; ++layerIndex)
{
MultipassBitmap* const layer = multipassBitmap->GetLayerNum(layerIndex);
if (layer)
{
// access and print layer name
const String layerName = layer->GetParameter(MPBTYPE::NAME).GetString();
ApplicationOutput("Layer: " + layerName);
}
}

Layers, folders and alpha layers are added with:

Further layer related functions are:

// This example adds a new folder with two layers
// to the given MultipassBitmap.
// add a new folder
MultipassBitmap* const folder = multipassBitmap->AddFolder(nullptr);
if (folder)
{
folder->SetName("Folder"_s);
// add a new layer
MultipassBitmap* const layerA = folder->AddLayer(nullptr, colorMode);
if (layerA)
{
// configure new layer
layerA->SetName("Layer A"_s);
layerA->SetParameter(MPBTYPE::SHOW, true);
layerA->SetParameter(MPBTYPE::SAVE, true);
}
// add a new layer
MultipassBitmap* const layerB = folder->AddLayer(nullptr, colorMode);
if (layerB)
{
// configure new layer
layerB->SetName("Layer B"_s);
layerB->SetParameter(MPBTYPE::SHOW, true);
layerB->SetParameter(MPBTYPE::SAVE, true);
}
}

Convert

The content of a MultipassBitmap can also be represented as a BodyPaint PaintBitmap:

// This example accesses the PaintBitmap representation of the
// given MultipassBitmap. The functions of the PaintBitmap class
// are used to merge the layers into one BaseBitmap.
AutoAlloc<BaseBitmap> mergedBitmap;
if (mergedBitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get PaintBitmap representation
PaintBitmap* const paintBitmap = multipassBitmap->GetPaintBitmap();
if (paintBitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// use PaintBitmap functionality to merge layers
const Int32 width = multipassBitmap->GetBw();
const Int32 height = multipassBitmap->GetBh();
const Int32 calcFlags = RECALC_NOGRID | RECALC_INITBMP;
// merge layers into one BaseBitmap
if (!paintBitmap->ReCalc(nullptr, 0, 0, width, height, mergedBitmap, calcFlags, 0))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(mergedBitmap);

Further Reading