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());
String GetName() const
Definition: c4d_baselist.h:2544
Definition: c4d_basedocument.h:143
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
const char * doc
Definition: pyerrors.h:226

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);
void SetName(const maxon::String &name, Bool setDirty=true)
Definition: c4d_baselist.h:2550
static RenderData * Alloc()
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67

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);
RenderData * GetUp()
Definition: c4d_basedocument.h:186

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);
Definition: c4d_basecontainer.h:48
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:580
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:587
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2518
@ RDATA_STEREO
Definition: drendersettings.h:428
@ RDATA_XRES
Definition: drendersettings.h:152
@ RDATA_YRES
Definition: drendersettings.h:153

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();
Definition: c4d_videopost.h:24
static BaseVideoPost * Alloc(Int32 type)
void InsertVideoPost(BaseVideoPost *pvp, BaseVideoPost *pred=nullptr)
@ RDATA_RENDERENGINE_PREVIEWHARDWARE
Definition: drendersettings.h:41
@ RDATA_RENDERENGINE
Definition: drendersettings.h:39

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();
}
Bool GetBit(Int32 mask) const
Definition: c4d_baselist.h:2441
RenderData * GetNext()
Definition: c4d_basedocument.h:174
#define BIT_ACTIVERENDERDATA
Active render data.
Definition: ge_prepass.h:935

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);
maxon::Result< void > SetImageSettingsDictionary(const maxon::DataDictionary &settings, BaseContainer *data, Int32 filterId)
void SetContainer(Int32 id, const BaseContainer &s)
Definition: c4d_basecontainer.h:679
const BaseContainer * GetDataInstance() const
Definition: c4d_baselist.h:2530
@ RDATA_FORMAT
Definition: drendersettings.h:67
@ RDATA_SAVEOPTIONS
Definition: drendersettings.h:69
#define FILTER_EXR
EXR.
Definition: ge_prepass.h:202
#define iferr_return
Definition: resultbase.h:1524
// 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);
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);
const char * format
Definition: abstract.h:183
maxon::Result< maxon::DataDictionary > GetImageSettingsDictionary(const BaseContainer *data, Int32 filterId)
Int32 GetInt32(Int32 id, Int32 preset=0) const
Definition: c4d_basecontainer.h:348
BaseContainer GetContainer(Int32 id) const
Definition: c4d_basecontainer.h:463
Definition: apibaseid.h:243
maxon::Int Int
Definition: ge_sys_math.h:60
return OK
Definition: apibase.h:2735
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
struct _Py_Identifier struct _Py_Identifier PyObject struct _Py_Identifier PyObject PyObject struct _Py_Identifier PyObject PyObject PyObject ** method
Definition: object.h:330

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
if (multipass->GetParameter(typeParamID, data, DESCFLAGS_GET::NONE))
{
// if this pass is a object buffer
{
// read the object buffer ID
multipass->GetParameter(bufferParamID, data, DESCFLAGS_GET::NONE);
const Int32 bufferID = data.GetInt32();
ApplicationOutput("Buffer ID: " + String::IntToString(bufferID));
}
}
multipass = multipass->GetNext();
}
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags) const
Definition: lib_description.h:355
Definition: c4d_gedata.h:83
Int32 GetInt32() const
Definition: c4d_gedata.h:456
Definition: c4d_basedocument.h:112
MultipassObject * GetNext()
Definition: c4d_basedocument.h:126
MultipassObject * GetFirstMultipass()
static String IntToString(Int32 v)
Definition: c4d_string.h:497
maxon::Int32 Int32
Definition: ge_sys_math.h:56
#define VPBUFFER_OBJECTBUFFER
Object buffer multipass channel.
Definition: c4d_videopostdata.h:141
#define ConstDescID(...)
Definition: lib_description.h:594
Represents a level within a DescID.
Definition: lib_description.h:298
@ MULTIPASSOBJECT_TYPE
Definition: zmultipass.h:6
@ MULTIPASSOBJECT_OBJECTBUFFER
Definition: zmultipass.h:8

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();
}
BaseVideoPost * GetNext() const
Definition: c4d_videopost.h:56
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Int32 GetType() const
Definition: c4d_baselist.h:1537
BaseVideoPost * GetFirstVideoPost()
@ VP_WATERMARK_TEXT_ENABLE
Definition: vpwatermark.h:68

Further Reading