Token System Manual

About

See the overview on Token System Overview.

Handling Tokens

Getting Tokens

Converting Tokens

// This example renders a BaseDocument and saves the resulting image using a filename handling tokens:
const Int32 width = 1280;
const Int32 height = 720;
// Prepare bitmap
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
if (bitmap->Init(width, height) != IMAGERESULT::OK)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
// Define render settings
RenderData* const renderData = renderDocument->GetActiveRenderData();
if (renderData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
BaseContainer renderSettings = renderData->GetData();
renderSettings.SetFloat(RDATA_XRES, width);
renderSettings.SetFloat(RDATA_YRES, height);
// Get filename
const Filename savePath = renderSettings.GetFilename(RDATA_PATH);
if (savePath.IsPopulated() == false)
return maxon::OK;
// Render the document
const RENDERRESULT res = RenderDocument(renderDocument, renderSettings, nullptr, nullptr, bitmap, RENDERFLAGS::NODOCUMENTCLONE, nullptr);
if (res != RENDERRESULT::OK)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
// Save result
// Convert tokens
const RenderPathData rpd = RenderPathData(renderDocument, renderData, &renderSettings, nullptr, 1, String(), String(), NOTOK);
Filename finalFilename = FilenameConvertTokens(savePath, &rpd);
// Save
finalFilename.SetSuffix("png"_s);
bitmap->Save(finalFilename, FILTER_PNG, nullptr, SAVEBIT::NONE);

Dissecting Tokens

There are a bunch of functions to dissect a path containing Tokens. In the following an exemplary path /myprojects/topnotchproject/$take/beautiful.tif is assumed.

  • StringExtractRoot() / FilenameExtractRoot(): Both return the "constant" part of a path. With the above path, these functions return /myprojects/topnotchproject/.
  • FilenameSlicePath(): This function is similar, but it also returns the part containing Tokens. With above path, it will return /myprojects/topnotchproject/ and $take/beautiful.tif.

Custom Tokens

  • RegisterToken(): Using RegisterToken() custom Tokens can be registered within Cinema 4D. Therefore RegisterToken() gets provided with all information needed by a TokenEntry (key, help and example) and a pointer to the TOKENHOOK function. The example below shows how the "$take" Token is implemented.
  • RegisterHiddenToken(): This function registers a hidden token that is not displayed in Render Settings.
  • RegisterPythonToken(): Registers a new Python token.
  • RegisterPythonHiddenToken(): Registers a new Python token that is not displayed in Render Settings.
Note
When registering custom Tokens, it is recommended to use a prefix to avoid collision with already existing Tokens. For example, the plugin name could be used.
// The custom token callback
static String ExampleTakeTokenHook(void* data)
{
RenderPathData* const rDataPath = (RenderPathData*)data;
if (rDataPath == nullptr)
return String();
BaseTake* const take = rDataPath->_cTake;
if (take != nullptr)
return take->GetName();
return String();
}
static maxon::Result<void> RegisterExampleToken()
{
// NOTE: When registering a custom Token, use a prefix like for example "myplugin.take"
const Bool success = RegisterToken(
String("example.take"),
String("Current Take Name"),
String("MyTake"),
ExampleTakeTokenHook);
if (success == false)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
return maxon::OK;
}
BaseList2D::GetData
BaseContainer GetData()
Definition: c4d_baselist.h:2296
BaseContainer::GetFilename
Filename GetFilename(Int32 id, const Filename &preset=Filename()) const
Definition: c4d_basecontainer.h:403
IMAGERESULT::OK
@ OK
Image loaded/created.
RDATA_PATH
@ RDATA_PATH
Definition: drendersettings.h:68
RENDERRESULT
RENDERRESULT
Definition: ge_prepass.h:413
BaseTake
Definition: lib_takesystem.h:319
RenderDocument
RENDERRESULT RenderDocument(BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)
Filename
Manages file and path names.
Definition: c4d_file.h:93
maxon::OK
return OK
Definition: apibase.h:2620
RegisterToken
Bool RegisterToken(const String &key, const String &help, const String &example, TOKENHOOK *hook)
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
BaseBitmap::Init
static IMAGERESULT Init(BaseBitmap *&res, const Filename &name, Int32 frame=-1, Bool *ismovie=nullptr, BitmapLoaderPlugin **loaderplugin=nullptr, const maxon::Delegate< void(Float progress)> &progressCallback=nullptr)
Filename::SetSuffix
void SetSuffix(const maxon::String &str)
String
Definition: c4d_string.h:38
RENDERRESULT::OK
@ OK
Function was successful.
RenderPathData::_cTake
BaseTake * _cTake
The BaseTake used for rendering.
Definition: lib_token.h:110
maxon::Result< void >
NOTOK
#define NOTOK
Definition: ge_sys_math.h:267
FILTER_PNG
#define FILTER_PNG
PNG.
Definition: ge_prepass.h:196
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
BaseContainer::SetFloat
void SetFloat(Int32 id, Float r)
Definition: c4d_basecontainer.h:533
AutoAlloc
Definition: ge_autoptr.h:36
RDATA_YRES
@ RDATA_YRES
Definition: drendersettings.h:154
RenderData
Definition: c4d_basedocument.h:142
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
RDATA_XRES
@ RDATA_XRES
Definition: drendersettings.h:153
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
BaseBitmap::Save
IMAGERESULT Save(const Filename &name, Int32 format, BaseContainer *data, SAVEBIT savebits) const
Filename::IsPopulated
Bool IsPopulated() const
RenderPathData
Data structure to collect render information in handling Tokens in render output path.
Definition: lib_token.h:85
BaseContainer
Definition: c4d_basecontainer.h:46
SAVEBIT::NONE
@ NONE
None.
FilenameConvertTokens
Filename FilenameConvertTokens(const Filename &path, const RenderPathData *rpData)
RENDERFLAGS::NODOCUMENTCLONE
@ NODOCUMENTCLONE
Set to avoid an automatic clone of the scene sent to RenderDocument().