Basic functions and classes

This page describes some general parts of the C.O.F.F.E.E. SDK that could belong to any program's SDK, not just C4D's.

Files

Files are accessed in two steps in C.O.F.F.E.E. First there is the Filename class that points to specific file on the computer, exisiting or non-existing. There are three ways to create a filename:

Using the GeGetStartupPath() function. It returns a filename with the path to the C4D directory.
Using the similar GeGetRootFilename() function. It returns a filename pointing to the current .cof or .cob file.
Using the SetFullString() member function of the Filename class. It lets you set the path using an OS specific path string.

Once you have a valid filename, for example the C4D path, you can also use the FileSelect() function to bring up a file selection dialog, where the user can specify a file for loading or saving. You can also manually add or substract from the filename's path using other member functions of the class:

var fn = GeGetRootFilename(); // The path to the current .cof file
fn->RemoveLast();             // The path to the .cof file's directory
fn->AddLast("icon.tif");      // The path to the file icon.tif in that directory

The filename can then be passed to the BaseFile class to open a file for reading or writing:

var f = new(BaseFile);
f->Open(fn, GE_READ);

There are functions for manipulating files, for example copying and moving, as well as functions for opening files and applications. Use them with care, so that you don't destroy the user's data!

Note: To avoid the possibility of C4D being used to spread viruses, C.O.F.F.E.E expressions (those that are included in .c4d files) cannot use any file functions or classes.

Containers

An important class in the C4D SDK is the BaseContainer class. A C4D container is a storage class that stores different types of values with a unique id for each value (like an STL map<int, AnyType>). If you create your own container, the ids can just be any number you want:

var myId = 10000;
var myValue = "Hello World!";

// Store (STL: map[myId] = myValue)
var bc = new(BaseContainer);
bc->SetData(myId, myValue);

// Get (STL: value = map[myId])
var value = bc->GetData(myId);

Normally you will use containers that C4D has created, where the ids are stored as enumerated constants that you can use, e.g. LIGHT_MAIN_F:

// Gets lightObj's container, and extracts the color of the light
var lightBc = lightObj->GetContainer();
var lightCol = lightBc->GetData(LIGHT_MAIN_F);

Many values in the SDK are stored in this way. To change a value, just store it and set the container back again:

// Changes the focus to 20.0
var camBc = camObj->GetContainer();
camBc->SetData(CAMERAOBJECT_FOCUS, 20.0);
camObj->SetContainer(camBc);

Note: You can store your own values in an object container, such as the camera's, but then you must get a unique container id from http://www.plugincafe.com: (Otherwise there might be severe data corruption, if you overwrite C4D's own container values!)

// Unique id from PluginCafe
var MYPLUGIN_DIRTY_BIT_ID = 1001369; 

// Store your own value in the object container
var bc = obj->GetContainer();
bc->SetData(MYPLUGIN_DIRTY_BIT_ID, TRUE);
obj->SetContainer();

Note: No kidding! The id really has to be unique!

Instead of always using the GetData() function, it's recommended that you use the typed functions (e.g. GetString()) so that you can supply a default value:

var myString = bc->GetString(MYSTRING_ID, "ERROR! String not found!");

Other functions

For more general functions, please see Math Functions and Basic Functions.