MultipassBitmap Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Properties
  • Parameters
  • Layers
• Convert
• Further Reading

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 SAVEBIT     bits = SAVEBIT::MULTILAYER | SAVEBIT::USE32BITCHANNELS;
    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:

• MultipassBitmap::Alloc(): Creates a new MultipassBitmap.
• MultipassBitmap::Free(): Deletes the given MultipassBitmap.
• MultipassBitmap::AllocWrapper(): Creates a new MultipassBitmap wrapping around the given BaseBitmap.

  // 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");
  }
 
  BaseBitmap::Free(bitmap);

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

• MultipassBitmap::ClearImageData(): Clears the image data for all layers without deleting the layers.

Properties

Parameters

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

• MultipassBitmap::GetParameter(): Returns the value stored with the given parameter ID.
• MultipassBitmap::SetParameter(): Set the value stored with the given parameter ID.

Note

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

The parameter IDs are:

• MPBTYPE::SHOW : Defines if the layer will be shown in the Picture Viewer.
• MPBTYPE::SAVE : Defines if the layer is saved when SAVEBIT::USESELECTEDLAYERS is used.
• MPBTYPE::PERCENT : Defines the blend value.
• MPBTYPE::BLENDMODE : Defines the blend mode.
• MPBTYPE::COLORMODE : Defines the color mode, see COLORMODE.
• MPBTYPE::BITMAPTYPE : Defines the bitmap type.
• MPBTYPE::NAME : Defines the name.
• MPBTYPE::DPI : Defines the DPI.
• MPBTYPE::USERID : Defines a user ID.
• MPBTYPE::USERSUBID : Defines a user sub-ID.
• MPBTYPE::FORCEBLEND : Defines if blend layers are forced.

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

• MultipassBitmap::GetUserID(): Returns the user ID.
• MultipassBitmap::SetUserID(): Sets the user ID.
• MultipassBitmap::SetUserSubID(): Sets the user sub-ID.
• MultipassBitmap::SetBlendMode(): Sets the blend mode.
• MultipassBitmap::SetName(): Sets the name.
• MultipassBitmap::SetColorMode(): Sets the color mode.
• MultipassBitmap::SetDpi(): Sets the DPI.

  // 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::BLENDMODE, LAYER_ADD);
    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:

• MultipassBitmap::GetLayerCount(): Returns the number of layers.
• MultipassBitmap::GetAlphaLayerCount(): Returns the number of alpha layers.
• MultipassBitmap::GetHiddenLayerCount(): Returns the number of hidden layers.

These layers are accessed with:

• MultipassBitmap::GetLayers(): Stores pointers to the layers into the given maxon::BaseArray.
• MultipassBitmap::FindUserID(): Returns the layer with the given ID and sub-ID.
• MultipassBitmap::GetSelectedLayer(): Returns the currently selected layer.
• MultipassBitmap::GetLayerNum(): Returns the layer with the given index.
• MultipassBitmap::GetAlphaLayerNum(): Returns the alpha layer with the given index.
• MultipassBitmap::GetHiddenLayerNum(): Returns the hidden layer with the given index.

    // 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:

• MultipassBitmap::AddLayer(): Adds a new layer or hidden layer.
• MultipassBitmap::AddFolder(): Adds a new folder.
• MultipassBitmap::AddAlpha(): Adds a new alpha layer.

Further layer related functions are:

• MultipassBitmap::DeleteLayer(): Deletes the given layer.
• MultipassBitmap::SetMasterAlpha(): Sets the master alpha layer.
• MultipassBitmap::FreeHiddenLayers(): Deletes the hidden layers.

  // 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:

• MultipassBitmap::GetPaintBitmap(): Returns the corresponding 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

• Files & Media
• Cinema API Files & Media
• BaseBitmap Manual