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 != 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:

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

Further Reading

RDATA_FORMAT
@ RDATA_FORMAT
Definition: drendersettings.h:69
BaseList2D::GetBit
Bool GetBit(Int32 mask) const
Definition: c4d_baselist.h:2237
RDATA_YRES
@ RDATA_YRES
Definition: drendersettings.h:153
Int
maxon::Int Int
Definition: ge_sys_math.h:64
BaseDocument::GetFirstRenderData
RenderData * GetFirstRenderData(void)
FILTER_EXR
#define FILTER_EXR
EXR.
Definition: ge_prepass.h:195
RDATA_STEREO
@ RDATA_STEREO
Definition: drendersettings.h:427
BaseList2D::GetDataInstance
const BaseContainer * GetDataInstance() const
Definition: c4d_baselist.h:2313
DescID
Definition: lib_description.h:327
BaseContainer::SetInt32
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:505
maxon::OK
return OK
Definition: apibase.h:2547
RenderData::GetFirstVideoPost
BaseVideoPost * GetFirstVideoPost()
maxon::Id
Definition: apibaseid.h:250
iferr_return
#define iferr_return
Definition: resultbase.h:1434
BIT_ACTIVERENDERDATA
#define BIT_ACTIVERENDERDATA
Active render data.
Definition: ge_prepass.h:886
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
RDATA_RENDERENGINE
@ RDATA_RENDERENGINE
Definition: drendersettings.h:39
BaseDocument::SetActiveRenderData
void SetActiveRenderData(RenderData *rd)
BaseContainer::SetBool
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:498
BaseVideoPost::Alloc
static BaseVideoPost * Alloc(Int32 type)
DESCFLAGS_SET::NONE
@ NONE
None.
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
RenderData::GetNext
RenderData * GetNext(void)
Definition: c4d_basedocument.h:168
SetImageSettingsDictionary
maxon::Result< void > SetImageSettingsDictionary(const maxon::DataDictionary &settings, BaseContainer *data, Int32 filterId)
RenderData::Alloc
static RenderData * Alloc(void)
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:495
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
RenderData::GetUp
RenderData * GetUp(void)
Definition: c4d_basedocument.h:180
MULTIPASSOBJECT_OBJECTBUFFER
@ MULTIPASSOBJECT_OBJECTBUFFER
Definition: zmultipass.h:8
GeData::GetInt32
Int32 GetInt32(void) const
Definition: c4d_gedata.h:427
BaseContainer::GetContainer
BaseContainer GetContainer(Int32 id) const
Definition: c4d_basecontainer.h:418
BaseList2D::GetDataInstanceRef
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2329
BaseVideoPost
Definition: c4d_videopost.h:23
RDATA_XRES
@ RDATA_XRES
Definition: drendersettings.h:152
MultipassObject::GetNext
MultipassObject * GetNext(void)
Definition: c4d_basedocument.h:120
GeData
Definition: c4d_gedata.h:82
BaseList2D::SetName
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2354
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
GetImageSettingsDictionary
maxon::Result< maxon::DataDictionary > GetImageSettingsDictionary(const BaseContainer *data, Int32 filterId)
VPBUFFER_OBJECTBUFFER
#define VPBUFFER_OBJECTBUFFER
Object buffer multipass channel.
Definition: c4d_videopostdata.h:140
RenderData::GetFirstMultipass
MultipassObject * GetFirstMultipass()
VP_WATERMARK_TEXT_ENABLE
@ VP_WATERMARK_TEXT_ENABLE
Definition: vpwatermark.h:68
BaseVideoPost::GetNext
BaseVideoPost * GetNext(void)
Definition: c4d_videopost.h:56
BaseDocument::InsertRenderDataLast
void InsertRenderDataLast(RenderData *rd)
RDATA_SAVEOPTIONS
@ RDATA_SAVEOPTIONS
Definition: drendersettings.h:71
BaseDocument::GetActiveRenderData
RenderData * GetActiveRenderData(void)
DESCFLAGS_GET::NONE
@ NONE
None.
BaseContainer::SetContainer
void SetContainer(Int32 id, const BaseContainer &s)
Definition: c4d_basecontainer.h:597
RenderData
Definition: c4d_basedocument.h:136
MultipassObject
Definition: c4d_basedocument.h:105
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
MULTIPASSOBJECT_TYPE
@ MULTIPASSOBJECT_TYPE
Definition: zmultipass.h:6
RenderData::InsertVideoPost
void InsertVideoPost(BaseVideoPost *pvp, BaseVideoPost *pred=nullptr)
C4DAtom::GetType
Int32 GetType() const
Definition: c4d_baselist.h:1378
BaseContainer::GetInt32
Int32 GetInt32(Int32 id, Int32 preset=0) const
Definition: c4d_basecontainer.h:303
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
BaseContainer
Definition: c4d_basecontainer.h:46
RDATA_RENDERENGINE_PREVIEWHARDWARE
@ RDATA_RENDERENGINE_PREVIEWHARDWARE
Definition: drendersettings.h:41