MultipassObject Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Navigate
• Types
• Further Reading

About

A MultipassObject represents a multipass element of the render settings. Cinema 4D's render engines will render and save different multipasses based on these settings.

MultipassObject objects are an instance of Zmultipass.

  // This example searches for the "depth" multipass.
  // If it is not found, it will be created.
 
  RenderData* const renderData = doc->GetActiveRenderData();
 
  MultipassObject* multipass = renderData->GetFirstMultipass();
  MultipassObject* depthPass = nullptr;
 
  while (multipass != nullptr)
  {
    BaseContainer& data = multipass->GetDataInstanceRef();
    const Int32    type = data.GetInt32(MULTIPASSOBJECT_TYPE);
 
    if (type == VPBUFFER_DEPTH)
    {
      depthPass = multipass;
      break;
    }
 
    multipass = multipass->GetNext();
  }
 
  if (depthPass == nullptr)
  {
    // allocate multipass
    depthPass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (depthPass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // set to depth pass
    BaseContainer& data = depthPass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_DEPTH);
 
    // insert
    renderData->InsertMultipass(depthPass);
    renderData->Message(MSG_UPDATE);
  }
 
  // enable multi-passes
  renderData->SetParameter(ConstDescID(DescLevel(RDATA_MULTIPASS_ENABLE)), true, DESCFLAGS_SET::NONE);

Access

Existing MultipassObject elements are stored in a list and can be accessed from a RenderData object:

• RenderData::GetFirstMultipass(): Returns the first MultipassObject element.

Allocation/Deallocation

The MultipassObject class does not offer a static "Alloc" or "Free" function so the functions of BaseList2D have to be used with Zmultipass.

• BaseList2D::Alloc(): Can be used to create a new MultipassObject object.
• BaseList2D::Free(): Can be used to delete the given MultipassObject object.

A newly created MultipassObject is added to the render settings by adding it to the RenderData object:

• RenderData::InsertMultipass(): inserts a MultipassObject element into the list.

  // allocate multipass
  MultipassObject* const depthPass = (MultipassObject*)BaseList2D::Alloc(Zmultipass);
  if (depthPass == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // set to depth pass
  BaseContainer& data = depthPass->GetDataInstanceRef();
  data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_DEPTH);
 
  // insert
  renderData->InsertMultipass(depthPass);

Navigate

MultipassObject objects are organized in a list:

• MultipassObject::GetNext(): Returns the next MultipassObject in the list.
• MultipassObject::GetPred(): Returns the previous MultipassObject in the list.

  // This example loops through all multipasses and prints their names.
 
  RenderData* const renderData = doc->GetActiveRenderData();
 
  MultipassObject* multipass = renderData->GetFirstMultipass();
 
  while (multipass != nullptr)
  {
    ApplicationOutput("Multipass: " + multipass->GetName());
    multipass = multipass->GetNext();
  }

Types

All multipasses are MultipassObject objects. They only differ in their parameters. The type of a multipass is defined with:

• MULTIPASSOBJECT_TYPE: The type of the multipass.

Simple multipass types are:

• VPBUFFER_RGBA: RGB and alpha multipass channel.
• VPBUFFER_AMBIENT: Ambient multipass channel.
• VPBUFFER_DIFFUSE: Diffuse multipass channel.
• VPBUFFER_SHADOW: Shadow multipass channel.
• VPBUFFER_TRANSPARENCY: Transparency multipass channel.
• VPBUFFER_RADIOSITY: Radiosity multipass channel.
• VPBUFFER_CAUSTICS: Caustics multipass channel.
• VPBUFFER_ATMOSPHERE: Atmosphere multipass channel.
• VPBUFFER_ATMOSPHERE_MUL: Atmosphere (multiply) multipass channel.
• VPBUFFER_DEPTH: Depth multipass channel.
• VPBUFFER_MAT_COLOR: Material color multipass channel.
• VPBUFFER_MAT_DIFFUSION: Material diffusion multipass channel.
• VPBUFFER_MAT_LUMINANCE: Material luminance multipass channel.
• VPBUFFER_MAT_TRANSPARENCY: Material transparency multipass channel.
• VPBUFFER_MAT_REFLECTION: Material reflection multipass channel.
• VPBUFFER_MAT_ENVIRONMENT: Material environment multipass channel.
• VPBUFFER_MAT_SPECULAR: Material specular multipass channel.
• VPBUFFER_MAT_SPECULARCOLOR: Material specular color multipass channel.
• VPBUFFER_ILLUMINATION: Illumination multipass channel.
• VPBUFFER_AMBIENTOCCLUSION: Ambient occlusion channel.
• VPBUFFER_MAT_NORMAL: Material normal channel.
• VPBUFFER_MAT_UV: Material UV channel.
• VPBUFFER_MOTIONVECTOR: Motion vector channel.
• VPBUFFER_SAMPLER: Sampler channel.
• VPBUFFER_ALPHA: Alpha multipass channel (for SDK request only).

Configurable multipass types are:

• VPBUFFER_OBJECTBUFFER: Object buffer multipass channel.
• VPBUFFER_BLEND: Blend multipass channel.
• VPBUFFER_REFLECTION: Reflection multipass channel.
• VPBUFFER_SPECULAR: Specular multipass channel.

The parameter IDs of configurable multipasses are defined in zmultipass.h.

Additional multipass types are:

• VPBUFFER_ALLPOSTEFFECTS: All post effects channel. Use this to create the "Post Effects" multipass needed to support custom multipasses created by VideoPostData plugins.
• VPBUFFER_IMAGEBUILDING_PASS: The maximum number of the image building layers. This can be used to loop through the multipass types.

Example object buffer:

    // This example creates an object buffer multipass.
 
    MultipassObject* const multipass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (multipass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    BaseContainer& data = multipass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_OBJECTBUFFER);
    data.SetInt32(MULTIPASSOBJECT_OBJECTBUFFER, 99);
 
    renderData->InsertMultipass(multipass);

Example blend channel:

    // This example creates an blend multipass.
 
    MultipassObject* const multipass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (multipass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    BaseContainer& data = multipass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_BLEND);
    data.SetBool(MULTIPASSOBJECT_DIFFUSE, true);
    data.SetBool(MULTIPASSOBJECT_SHADOW, true);
 
    renderData->InsertMultipass(multipass);

Example reflection channel:

    // This example creates a reflection multipass.
 
    MultipassObject* const multipass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (multipass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    BaseContainer& data = multipass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_REFLECTION);
    data.SetInt32(MULTIPASSOBJECT_REFLECTION_MATERIALS, MULTIPASSOBJECT_REFLECTION_SEPARATE_ALL);
 
    renderData->InsertMultipass(multipass);

Example specular channel:

    // This example creates a specular multipass.
 
    MultipassObject* const multipass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (multipass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    BaseContainer& data = multipass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_SPECULAR);
    data.SetInt32(MULTIPASSOBJECT_SPECULAR_MATERIALS, MULTIPASSOBJECT_SPECULAR_SEPARATE_ALL);
 
    renderData->InsertMultipass(multipass);

Further Reading

• Scene Data Overview
• BaseDocument Manual
• RenderData Manual