GeClipMap Manual


GeClipMap is a utility class that allows to perform advanced drawing operations.


A GeClipMap can be created with the usual tools:

The created GeClipMap can be initiated in multiple ways:

// This example creates a new GeClipMap, fills it with a
// color and displays the result in the Picture Viewer.
// create GeClipMap
if (clipMap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// init GeClipMap
const Int32 width = 1024;
const Int32 height = 1024;
const Int32 depth = 32;
const IMAGERESULT res = clipMap->Init(width, height, depth);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// fill ClipMap
clipMap->SetColor(255, 0, 0); // red
clipMap->FillRect(0, 0, width - 1, height - 1);
// show result in Picture Viewer
BaseBitmap* const bitmap = clipMap->GetBitmap();
if (bitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
Bool ShowBitmap(const Filename &fn)
Definition: ge_autoptr.h:37
Definition: c4d_basebitmap.h:428
Py_UCS4 * res
Definition: unicodeobject.h:1113
maxon::Int32 Int32
Definition: ge_sys_math.h:60
Definition: ge_prepass.h:3914
@ OK
Image loaded/created.
Definition: memoryallocationbase.h:67
unsigned long Py_ssize_t width
Definition: pycore_traceback.h:88

A GeClipMap is easily cleared with:

Read-Only Properties

The basic settings of a GeClipMap are accessed with:

The bitmap data is stored internally as a BaseBitmap:


Every drawing operation performed with a GeClipMap must be encapsulated between these two functions:

The drawing operations can be modified with:

// This example draws multiple elements into the given GeClipMap.
// SetOffset() is used to define an offset for the drawing operations
// of each element. This way these drawing operations can be defined
// in local space.
// fill background with white
clipMap->SetColor(255, 255, 255);
clipMap->FillRect(0, 0, width - 1, height - 1);
// draw multiple elements
for (Int32 i = 0; i < elementCnt; ++i)
// define offset for each drawn element
const Int32 offsetX = 10 + (i * 100);
const Int32 offsetY = 10;
clipMap->SetOffset(offsetX, offsetY);
// draw element with the defined offset
// DrawElement() is a custom function
DrawElement(clipMap) iferr_return;
Py_ssize_t i
Definition: abstract.h:645
#define iferr_return
Definition: resultbase.h:1465

A clipping region defines the part of the GeClipMap which will be affected by the following drawing operations.

Single pixels of the GeClipMap can be accessed with:

// This example fills the given GeClipMap
// with randomly colored pixels.
// get GeClipMap dimensions
Int32 clipMapWidth = 0;
Int32 clipMapHeight = 0;
clipMap->GetDim(&clipMapWidth, &clipMapHeight);
Random randomGen;
// loop through all pixels
for (Int32 x = 0; x < clipMapWidth; ++x)
for (Int32 y = 0; y < clipMapHeight; ++y)
// get random color
const Int32 red = Int32(randomGen.Get01() * COLORTOINT_MULTIPLIER);
const Int32 green = Int32(randomGen.Get01() * COLORTOINT_MULTIPLIER);
const Int32 blue = Int32(randomGen.Get01() * COLORTOINT_MULTIPLIER);
clipMap->SetPixelRGBA(x, y, red, green, blue);
Constant to convert from vectors color components to integers.
Definition: c4d_tools.h:25
Definition: c4d_tools.h:812
Float Get01(void)
PyObject * x
Definition: bytesobject.h:38

A blit operations allows to easily copy a part of a GeClipMap into another GeClipMap.

// This example creates two GeClipMaps. A part of the content of
// one GeClipMap is copied to the other GeClipMap using Blit().
// get bitmap data from a given BaseBitmap
const IMAGERESULT resSource = sourceClipMap->Init(sourceBitmap);
// init target GeClipMap
const IMAGERESULT resTarget = targetClipMap->Init(targetWidth, targetHeight, 32);
const Bool sourceImageOK = resSource == IMAGERESULT::OK;
const Bool targetImageOK = resTarget == IMAGERESULT::OK;
if (sourceImageOK && targetImageOK)
// copy image data from source to target using Blit()
targetClipMap->SetDrawMode(GE_CM_DRAWMODE::COPY, 256);
targetClipMap->Blit(0, 0, *sourceClipMap, 0, 0, targetWidth, targetHeight, GE_CM_BLIT::COPY);
maxon::Bool Bool
Definition: ge_sys_math.h:55
Source overwrites destination.
New pixels overwrite old ones.

Drawing Operations

These drawing operations allow to create basic shapes. The use the current color defined with GeClipMap::SetColor().

// This example draws a smiley into the given GeClipMap.
// draw a smiley
// base shape
clipMap->SetColor(255, 255, 0); // yellow
clipMap->FillEllipse(10, 10, 90, 90);
// mouth
clipMap->SetColor(0, 0, 0); // black
clipMap->Arc(20, 60, 50, 80, GE_CM_ARCSEGMENT::LEFTBOTTOM);
clipMap->Arc(50, 60, 80, 80, GE_CM_ARCSEGMENT::RIGHTBOTTOM);
// eyes
clipMap->FillEllipse(30, 30, 40, 50);
clipMap->FillEllipse(60, 30, 70, 50);
(x2,y2) -> (x1,y2) -> (x1,y1)
(x2,y1) -> (x2,y2) -> (x1,y2)

Drawing Text

These functions are used to handle and draw text:

The currently used font is defined with:

// This example creates a GeClipMap and gets the dimensions needed to
// display the given text. The GeClipMap is then initiated with that
// dimensions to draw the text.
if (clipMap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get font settings
BaseContainer fontSettings;
if (!GeClipMap::GetFontDescription("CourierNewPS-ItalicMT", GE_FONT_NAME_POSTSCRIPT, &fontSettings))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// init
IMAGERESULT res = clipMap->Init(1, 1, 32);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
clipMap->SetFont(&fontSettings, 20.0);
// get dimensions needed for given string
const Int32 textWidth = clipMap->GetTextWidth(text);
const Int32 textHeight = clipMap->GetTextHeight();
// end
// re-init to draw text
res = clipMap->Init(textWidth, textHeight, 32);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// fill background with white
clipMap->SetColor(255, 255, 255, 255);
clipMap->FillRect(0, 0, textWidth - 1, textHeight - 1);
// draw black text
clipMap->SetColor(0, 0, 0, 255);
clipMap->SetFont(&fontSettings, 20.0);
clipMap->TextAt(0, 0, text);
// end drawing
Definition: c4d_basecontainer.h:47
static Bool GetFontDescription(String const &name, GeFontNameType type, BaseContainer *dst)
Font postscript name (e.g. "Helvetica-Bold").
Definition: lib_clipmap.h:112
PyObject * text
Definition: pycore_traceback.h:70

These static functions are used to manage fonts:

See also FontData and GeChooseFont().

// This example gets all installed fonts and prints their names.
// get all fonts
// loop trough all fonts
Int32 containerElement;
GeData* fontData = nullptr;
BrowseContainer browse(&fonts);
// browse
while (browse.GetNext(&containerElement, &fontData))
BaseContainer* const font = fontData->GetContainer();
BaseContainer* const fontInstance = font->GetContainerInstance(0);
// postscript
String postScript;
if (GeClipMap::GetFontName(fontInstance, GE_FONT_NAME_POSTSCRIPT, &postScript))
ApplicationOutput("- PostScript: " + postScript);
// display name
String displayName;
if (GeClipMap::GetFontName(fontInstance, GE_FONT_NAME_DISPLAY, &displayName))
ApplicationOutput("- Display: " + displayName);
// family name
String familyName;
if (GeClipMap::GetFontName(fontInstance, GE_FONT_NAME_FAMILY, &familyName))
ApplicationOutput("- Family: " + familyName);
BaseContainer * GetContainerInstance(Int32 id)
Definition: c4d_basecontainer.h:425
Definition: c4d_gedata.h:674
static Bool GetFontName(BaseContainer const *font_description, GeFontNameType type, String *dst)
static void EnumerateFonts(BaseContainer *dst, GE_CM_FONTSORT sort_mode)
Definition: c4d_gedata.h:83
BaseContainer * GetContainer(void) const
Definition: c4d_gedata.h:487
Definition: c4d_string.h:39
One BaseContainer per font, no order guaranteed.
Font family name (e.g. "Helvetica").
Definition: lib_clipmap.h:110
Human readable font name (e.g. "Helvetica Bold").
Definition: lib_clipmap.h:109
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210

Further Reading