Token System Manual

内容表

关于
Handling Tokens
Custom Tokens

关于

See the overview on Token System Overview .

Handling Tokens

Getting Tokens

GetAllTokenEntries() : Using GetAllTokenEntries() it is possible to get all registered Tokens. This can be used to populate a ComboBox or to print a help for the user.

Converting Tokens

StringConvertTokens() / FilenameConvertTokens() : Using these conversion functions, a path containing Tokens can be converted into a complete file path. The Tokens will be evaluated and replaced by the actual data based on RenderPathData . There are two flavors, one taking String and the other taking Filename as an input parameter.
StringConvertTokensFilter() / FilenameConvertTokensFilter() : There may be situations, where one wants to evaluate only a subset of Tokens, while keeping others for later evaluation. That's what the *ConvertTokensFilter () functions are for.

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

注意: 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()

定义： c4d_baselist.h:2266

BaseContainer::GetFilename

Filename GetFilename(Int32 id, const Filename &preset=Filename()) const

定义： c4d_basecontainer.h:403

IMAGERESULT::OK

@ OK

Image loaded/created.

@ RDATA_YRES

定义： drendersettings.h:153

RENDERRESULT

定义： ge_prepass.h:409

定义： lib_takesystem.h:319

RENDERRESULT RenderDocument(BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)

Manages file and path names.

定义： c4d_file.h:93

return OK

定义： apibase.h:2532

Bool RegisterToken(const String &key, const String &help, const String &example, TOKENHOOK *hook)

MAXON_SOURCE_LOCATION

#define MAXON_SOURCE_LOCATION

定义： memoryallocationbase.h:66

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)

@ RDATA_PATH

定义： drendersettings.h:68

定义： c4d_string.h:38

RENDERRESULT::OK

@ OK

Function was successful.

RenderPathData::_cTake

BaseTake * _cTake

The BaseTake used for rendering.

定义： lib_token.h:110

maxon::Result< void >

@ RDATA_XRES

定义： drendersettings.h:152

#define NOTOK

定义： ge_sys_math.h:265

#define FILTER_PNG

PNG.

定义： ge_prepass.h:196

maxon::Int32 Int32

定义： ge_sys_math.h:58

BaseContainer::SetFloat

void SetFloat(Int32 id, Float r)

定义： c4d_basecontainer.h:533

定义： ge_autoptr.h:36

定义： c4d_basedocument.h:136

maxon::Bool Bool

定义： ge_sys_math.h:53

BaseList2D::GetName

String GetName() const

定义： c4d_baselist.h:2318

BaseBitmap::Save

IMAGERESULT Save(const Filename &name, Int32 format, BaseContainer *data, SAVEBIT savebits) const

Filename::IsPopulated

Bool IsPopulated() const

Data structure to collect render information in handling Tokens in render output path.

定义： lib_token.h:85

定义： c4d_basecontainer.h:46

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