RenderData Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Navigation
• Properties
  • Data
  • Multipasses
  • Post Effects
• Further Reading

About

A RenderData object represents a set of render settings of a BaseDocument. The render settings include:

• Various parameters like resolution, image format, save path etc.
• A list of MultipassObject elements that represent multipasses.
• A list of BaseVideoPost elements that represent post filters or render engines.

RenderData objects are an instance of Rbase.

Access

RenderData elements can be accessed from the BaseDocument:

• BaseDocument::GetFirstRenderData(): Returns the first RenderData object in the tree.
• BaseDocument::GetActiveRenderData(): Returns the currently active render settings.

  // This example prints the name of the active render settings.
 
  const RenderData* const renderData = doc->GetActiveRenderData();
 
  ApplicationOutput("Active RenderData: " + renderData->GetName());

Allocation/Deallocation

RenderData objects can be created with the usual tools:

• RenderData::Alloc(): Creates a new RenderData object.
• RenderData::Free(): Deletes the given RenderData object.

The RenderData object can be handed over to a BaseDocument using:

• BaseDocument::InsertRenderData(): Adds the given RenderData to the BaseDocument as the first element in the list.
• BaseDocument::InsertRenderDataLast(): Adds the given RenderData to the BaseDocument as the last element in the list.
• BaseDocument::SetActiveRenderData(): Sets the given RenderData as the currently active render settings.

  // This example adds a new RenderData to the document and set this RenderData as the active one.
 
  RenderData* const renderData = RenderData::Alloc();
  if (renderData == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  renderData->SetName("Preview Render Settings"_s);
  doc->InsertRenderDataLast(renderData);
  doc->SetActiveRenderData(renderData);

Navigation

RenderData is based on ::GeListNode and the render settings are organized in a tree. This tree can be navigated with:

• RenderData::GetNext(): Returns the next RenderData object.
• RenderData::GetPred(): Returns the previous RenderData object.
• RenderData::GetUp(): Returns the parent RenderData object.
• RenderData::GetDown(): Returns the child RenderData object.
• RenderData::GetDownLast(): Returns the last RenderData child object.

  // This example searches for the topmost parent of the active RenderData
  // and sets it as the active one.
 
  RenderData* const renderData = doc->GetActiveRenderData();
  RenderData*       parentRenderData = renderData;
 
  // search for the topmost parent
  while (parentRenderData->GetUp())
  {
    parentRenderData = parentRenderData->GetUp();
  }
 
  doc->SetActiveRenderData(parentRenderData);

Properties

The RenderData object gives access to render settings, Multipasses and post effects.

Data

RenderData is based on ::BaseList2D so the data can be accessed with

• BaseList2D::GetData(): Returns a copy of the object's BaseContainer.
• BaseList2D::GetDataInstance(): Returns a pointer to the object's BaseContainer.

The container IDs are defined in drendersettings.h.

  // This example sets the resolution of the active render settings to 720p
  // and enables the "Stereoscopic" parameter group
 
  RenderData* const renderData = doc->GetActiveRenderData();
 
  BaseContainer& bc = renderData->GetDataInstanceRef();
  bc.SetInt32(RDATA_XRES, 1280);
  bc.SetInt32(RDATA_YRES, 720);
  bc.SetBool(RDATA_STEREO, true);

Changing the RDATA_RENDERENGINE parameter to change the render engine will not automatically create the needed video post for that render engine. The video post has to be created manually.

  // This example sets "Hardware" as the current renderer.
  // and adds the "Hardware" post effect
 
  RenderData* const renderData = RenderData::Alloc();
  if (renderData == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  renderData->SetName("Hardware Rendering"_s);
 
  // insert render data
  doc->InsertRenderDataLast(renderData);
 
  // add "Hardware" post effect
  BaseVideoPost* const videoPost = BaseVideoPost::Alloc(RDATA_RENDERENGINE_PREVIEWHARDWARE);
  if (videoPost == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  renderData->InsertVideoPost(videoPost);
 
  // set "Hardware" as active renderer
  BaseContainer& bc = renderData->GetDataInstanceRef();
  bc.SetInt32(RDATA_RENDERENGINE, RDATA_RENDERENGINE_PREVIEWHARDWARE);

If a given RenderData element is active can be checked with a bit. To set a given RenderData object as the active one, use BaseDocument::SetActiveRenderData().

• BIT_ACTIVERENDERDATA: The bit is set if the given RenderData object is active.

  // This example loops through all topmost render settings
  // and checks if the given element is the active one.
 
  RenderData* renderData = doc->GetFirstRenderData();
 
  while (renderData != nullptr)
  {
    ApplicationOutput("RenderData: " + renderData->GetName());
 
    // check if this RenderData object is the active render setting
    if (renderData->GetBit(BIT_ACTIVERENDERDATA))
      ApplicationOutput("--> active RenderData");
 
    renderData = renderData->GetNext();
  }

The image format settings are defined in a maxon::DataDictionary that is saved within the BaseContainer. These functions are used to access the image format settings:

• GetImageSettingsDictionary(): Returns the maxon::DataDictionary that holds the image format settings stored in the given BaseContainer.
• SetImageSettingsDictionary(): Stores the given image format settings within the given BaseContainer.

  // This example sets the render image format and configures its settings.
 
  // access render data
  RenderData*    const renderData = doc->GetActiveRenderData();
  if (renderData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  BaseContainer* const renderDataBaseContainer = renderData->GetDataInstance();
  if (renderDataBaseContainer == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // set OpenEXR format
  renderDataBaseContainer->SetInt32(RDATA_FORMAT, FILTER_EXR);
 
  // define OpenEXR settings
  maxon::DataDictionary exportSettings;
  exportSettings.Set(maxon::MEDIASESSION::OPENEXR::EXPORT::HALFFLOAT, true) iferr_return;
  exportSettings.Set(maxon::MEDIASESSION::OPENEXR::EXPORT::LAYERNUMBERING, true) iferr_return;
  exportSettings.Set(maxon::MEDIASESSION::OPENEXR::EXPORT::COMPRESSIONMETHOD, maxon::MEDIASESSION::OPENEXR::EXPORT::COMPRESSIONMETHOD.ENUM_NONE) iferr_return;
 
  // store settings in BaseContainer
  BaseContainer subContainer;
  SetImageSettingsDictionary(exportSettings, &subContainer, FILTER_EXR) iferr_return;
 
  // store container in render data
  renderDataBaseContainer->SetContainer(RDATA_SAVEOPTIONS, subContainer);

  // This example reads the target image settings.
 
  // access render data
  RenderData*    const renderData = doc->GetActiveRenderData();
  if (renderData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  BaseContainer* const renderDataBaseContainer = renderData->GetDataInstance();
  if (renderDataBaseContainer == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // check for openEXR
  const Int format = renderDataBaseContainer->GetInt32(RDATA_FORMAT);
  if (format != FILTER_EXR)
    return maxon::OK;
 
  // get container with format options
  BaseContainer subContainer = renderDataBaseContainer->GetContainer(RDATA_SAVEOPTIONS);
 
  // get DataDictionary
  const maxon::DataDictionary data = GetImageSettingsDictionary(&subContainer, FILTER_EXR) iferr_return;
 
  // get compression method
  maxon::Id method = data.GetOrDefault(maxon::MEDIASESSION::OPENEXR::EXPORT::COMPRESSIONMETHOD);
  DiagnosticOutput("OpenEXR compression method: @", method);

Multipasses

A render multipass contains different elements of the render result. What multipasses should be created is stored in a list of MultipassObject elements.

• RenderData::GetFirstMultipass(): Returns the first MultipassObject element.
• RenderData::InsertMultipass(): Inserts a MultipassObject element into the list.

See also MultipassObject Manual.

  // This code loops though all multipasses searching for render buffers.
 
  RenderData* const renderData = doc->GetActiveRenderData();
  MultipassObject*  multipass  = renderData->GetFirstMultipass();
 
  while (multipass != nullptr)
  {
    GeData data;
 
    // get the type of the multipass
    const DescID typeParamID = ConstDescID(DescLevel(MULTIPASSOBJECT_TYPE));
    if (multipass->GetParameter(typeParamID, data, DESCFLAGS_GET::NONE))
    {
      // if this pass is a object buffer
      if (data.GetInt32() == VPBUFFER_OBJECTBUFFER)
      {
        // read the object buffer ID
        const DescID bufferParamID = ConstDescID(DescLevel(MULTIPASSOBJECT_OBJECTBUFFER));
        multipass->GetParameter(bufferParamID, data, DESCFLAGS_GET::NONE);
 
        const Int32 bufferID = data.GetInt32();
        ApplicationOutput("Buffer ID: " + String::IntToString(bufferID));
      }
    }
 
    multipass = multipass->GetNext();
  }

Post Effects

Post effects are executed during the rendering process to apply filters like color correction to the final image. BaseVideoPost objects can also represent a render engine. These BaseVideoPost elements are stored in a list.

• RenderData::GetFirstVideoPost(): Returns the first BaseVideoPost element.
• RenderData::InsertVideoPost(): Adds the given BaseVideoPost element to the list.
• RenderData::InsertVideoPostLast(): Adds the given BaseVideoPost element as the last element to the list.

See also BaseVideoPost Manual.

  // This example loops through all video posts,
  // searches for the "Watermark" post effect and enables it
 
  RenderData*    const renderData = doc->GetActiveRenderData();
  BaseVideoPost*       videoPost  = renderData->GetFirstVideoPost();
 
  while (videoPost != nullptr)
  {
    // check if this is a "Watermark"
    if (videoPost->GetType() == 1025462)
    {
      videoPost->SetParameter(ConstDescID(DescLevel(VP_WATERMARK_TEXT_ENABLE)), true, DESCFLAGS_SET::NONE);
      break;
    }
 
    videoPost = videoPost->GetNext();
  }

Further Reading

• Scene Data Overview
• BaseDocument Manual
• MultipassObject Manual
• BaseVideoPost Manual