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);
if ((resSource == IMAGERESULT::OK) && (resTarget == IMAGERESULT::OK))
{
// 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