RenderData Manual

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:

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

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

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

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

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
if (videoPost == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
renderData->InsertVideoPost(videoPost);
// set "Hardware" as active renderer
BaseContainer& bc = renderData->GetDataInstanceRef();

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().

// This example loops through all topmost render settings
// and checks if the given element is the active one.
RenderData* renderData = doc->GetFirstRenderData();
while (renderData)
{
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:

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

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)
{
GeData data;
// get the type of the multipass
const DescID typeParamID(MULTIPASSOBJECT_TYPE);
if (multipass->GetParameter(typeParamID, data, DESCFLAGS_GET::NONE))
{
// if this pass is a object buffer
{
// read the object buffer ID
const DescID bufferParamID(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.

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)
{
// check if this is a "Watermark"
if (videoPost->GetType() == 1025462)
{
break;
}
videoPost = videoPost->GetNext();
}

Further Reading