GeClipMap Manual

About

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

Allocation/Deallocation

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);
if (res != IMAGERESULT::OK)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// fill ClipMap
clipMap->BeginDraw();
clipMap->SetColor(255, 0, 0); // red
clipMap->FillRect(0, 0, width - 1, height - 1);
clipMap->EndDraw();
// show result in Picture Viewer
BaseBitmap* const bitmap = clipMap->GetBitmap();
if (bitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(bitmap);

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:

Drawing

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.
clipMap->BeginDraw();
// 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;
}
clipMap->EndDraw();

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);
clipMap->BeginDraw();
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);
}
}
clipMap->EndDraw();

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->BeginDraw();
targetClipMap->SetDrawMode(GE_CM_DRAWMODE::COPY, 256);
targetClipMap->Blit(0, 0, *sourceClipMap, 0, 0, targetWidth, targetHeight, GE_CM_BLIT::COPY);
targetClipMap->EndDraw();
}

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.
clipMap->BeginDraw();
// 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);
clipMap->EndDraw();

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);
if (res != IMAGERESULT::OK)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
clipMap->BeginDraw();
clipMap->SetFont(&fontSettings, 20.0);
// get dimensions needed for given string
const Int32 textWidth = clipMap->GetTextWidth(text);
const Int32 textHeight = clipMap->GetTextHeight();
// end
clipMap->EndDraw();
clipMap->Destroy();
// re-init to draw text
res = clipMap->Init(textWidth, textHeight, 32);
if (res != IMAGERESULT::OK)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
clipMap->BeginDraw();
// 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
clipMap->EndDraw();

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);
}

Further Reading

GE_FONT_NAME_FAMILY
@ GE_FONT_NAME_FAMILY
Font family name (e.g. "Helvetica").
Definition: lib_clipmap.h:110
IMAGERESULT::OK
@ OK
Image loaded/created.
GeClipMap::Init
IMAGERESULT Init(Int32 w, Int32 h, Int32 bits)
GE_FONT_NAME_DISPLAY
@ GE_FONT_NAME_DISPLAY
Human readable font name (e.g. "Helvetica Bold").
Definition: lib_clipmap.h:109
GeClipMap::Destroy
void Destroy()
GE_CM_FONTSORT::HIERARCHICAL
@ HIERARCHICAL
One BaseContainer per font, no order guaranteed.
GeClipMap::Arc
void Arc(Int32 x1, Int32 y1, Int32 x2, Int32 y2, GE_CM_ARCSEGMENT seg)
GeClipMap::SetPixelRGBA
void SetPixelRGBA(Int32 x, Int32 y, Int32 r, Int32 g, Int32 b, Int32 a=255)
GE_CM_ARCSEGMENT::RIGHTBOTTOM
@ RIGHTBOTTOM
(x2,y1) -> (x2,y2) -> (x1,y2)
BaseContainer::GetContainerInstance
BaseContainer * GetContainerInstance(Int32 id)
Definition: c4d_basecontainer.h:425
GE_CM_ARCSEGMENT::LEFTBOTTOM
@ LEFTBOTTOM
(x2,y2) -> (x1,y2) -> (x1,y1)
iferr_return
#define iferr_return
Definition: resultbase.h:1434
GE_CM_DRAWMODE::COPY
@ COPY
New pixels overwrite old ones.
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
GeClipMap::GetFontName
static Bool GetFontName(BaseContainer const *font_description, GeFontNameType type, String *dst)
GeClipMap::GetTextHeight
Int32 GetTextHeight()
GeClipMap::GetDim
void GetDim(Int32 *w, Int32 *h) const
GeClipMap::GetFontDescription
static Bool GetFontDescription(String const &name, GeFontNameType type, BaseContainer *dst)
GeClipMap::BeginDraw
void BeginDraw()
Must be called before any drawing functions.
GeClipMap::TextAt
void TextAt(Int32 x, Int32 y, const String &txt)
GeClipMap::GetBitmap
BaseBitmap * GetBitmap()
String
Definition: c4d_string.h:39
GeClipMap::SetColor
void SetColor(Int32 r, Int32 g, Int32 b, Int32 a=255)
GeData
Definition: c4d_gedata.h:83
GE_CM_BLIT::COPY
@ COPY
Source overwrites destination.
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:58
GeClipMap::SetOffset
void SetOffset(Int32 off_x, Int32 off_y)
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
ShowBitmap
Bool ShowBitmap(const Filename &fn)
GeClipMap::FillRect
void FillRect(Int32 x1, Int32 y1, Int32 x2, Int32 y2)
GeClipMap::EnumerateFonts
static void EnumerateFonts(BaseContainer *dst, GE_CM_FONTSORT sort_mode)
COLORTOINT_MULTIPLIER
static const Float COLORTOINT_MULTIPLIER
Constant to convert from vectors color components to integers.
Definition: c4d_tools.h:25
GE_FONT_NAME_POSTSCRIPT
@ GE_FONT_NAME_POSTSCRIPT
Font postscript name (e.g. "Helvetica-Bold").
Definition: lib_clipmap.h:112
GeClipMap::GetTextWidth
Int32 GetTextWidth(const String &txt)
BaseBitmap
Definition: c4d_basebitmap.h:411
Random::Get01
Float Get01(void)
AutoAlloc
Definition: ge_autoptr.h:37
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:53
GeClipMap::EndDraw
void EndDraw()
Must be called after a sequence of drawing functions to free the memory allocated by BeginDraw().
BrowseContainer
Definition: c4d_gedata.h:674
Random
Definition: c4d_tools.h:812
IMAGERESULT
IMAGERESULT
Definition: ge_prepass.h:3660
GeClipMap::SetFont
Bool SetFont(BaseContainer const *font_description, Float font_size=0.0)
GeData::GetContainer
BaseContainer * GetContainer(void) const
Definition: c4d_gedata.h:487
BaseContainer
Definition: c4d_basecontainer.h:47
GeClipMap::FillEllipse
void FillEllipse(Int32 x1, Int32 y1, Int32 x2, Int32 y2)