GeClipMap Manual

Table of Contents

• About
• Allocation/Deallocation
• Read-Only Properties
• Drawing
  • Drawing Operations
  • Drawing Text
• Further Reading

About

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

Allocation/Deallocation

A GeClipMap can be created with the usual tools:

• GeClipMap::Alloc(): Creates a new GeClipMap.
• GeClipMap::Free(): Deletes the given GeClipMap.

The created GeClipMap can be initiated in multiple ways:

• GeClipMap::Init(Int32 w, Int32 h, Int32 bits): Initiates the GeClipMap with the given dimensions.
• GeClipMap::Init(BaseBitmap *bm): Initiates the GeClipMap by loading the given BaseBitmap.
• GeClipMap::Init(BaseBitmap *bm, BaseBitmap *alpha_channel): Initiates the GeClipMap by loading the given BaseBitmap and alpha channel.
• GeClipMap::Init(const Filename &name, Int32 frame, Bool *ismovie): Initiates the GeClipMap by loading the given image file.
• GeClipMap::Init(const IconData &iconData): Initiates the GeClipMap by loading the IconData.

  // This example creates a new GeClipMap, fills it with a
  // color and displays the result in the Picture Viewer.
 
  // create GeClipMap
  AutoAlloc<GeClipMap> clipMap;
  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:

• GeClipMap::Destroy(): Resets the clip map to its initial state.

Read-Only Properties

The basic settings of a GeClipMap are accessed with:

• GeClipMap::GetDim(): Gets the dimensions of the GeClipMap.
• GeClipMap::GetBw(): Returns the width of the GeClipMap.
• GeClipMap::GetBh(): Returns the height of the GeClipMap.

The bitmap data is stored internally as a BaseBitmap:

• GeClipMap::GetBitmap(): Returns a pointer to the internal BaseBitmap.

Drawing

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

• GeClipMap::BeginDraw(): Must be called before any drawing operation.
• GeClipMap::EndDraw(): Must be called after a sequence of drawing operations.

The drawing operations can be modified with:

• GeClipMap::SetDrawMode(): Sets the raw mode, see ::GE_CM_DRAWMODE.
• GeClipMap::SetColor(): Sets the currently used color.
• GeClipMap::SetOffset(): Sets the offset for all following drawing operations.

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

• GeClipMap::SetClipRgn(): Sets the clipping region.
• GeClipMap::ClipPoint(): Returns true if the given point is in the clipping region.
• GeClipMap::ClipArea(): Returns true if the given area is in the clipping region.

Single pixels of the GeClipMap can be accessed with:

• GeClipMap::GetPixelRGBA(): Gets the RGBA values of the given coordinates.
• GeClipMap::SetPixelRGBA(): Sets the RGBA values of the given coordinates.

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

• GeClipMap::Blit(): Copies (a part) of the source GeClipMap into the 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().

• GeClipMap::SetPixel(): Sets the given pixel.
• GeClipMap::Line(): Draws a line.
• GeClipMap::PolyLine(): Draws a polygon line using ::GE_POINT2D.
• GeClipMap::FillPolygon(): Draws a filled polygon using ::GE_POINT2D.
• GeClipMap::Rect(): Draws a rectangle.
• GeClipMap::FillRect(): Draws a filled rectangle.
• GeClipMap::Arc(): Draws an arc.
• GeClipMap::FillArc(): Draws a filled arc.
• GeClipMap::Ellipse(): Draws an ellipse.
• GeClipMap::FillEllipse(): Draws a filled ellipse.
• GeClipMap::DrawBezierSegment(): Draws a Bezier segment.
• GeClipMap::SupportsDrawBezierSegment(): Returns true if the GeClipMap supports GeClipMap::DrawBezierSegment().

  // 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:

• GeClipMap::TextAt(): Draws the given text at the given coordinates.
• GeClipMap::GetTextWidth(): Returns the width of the given text using the current font.
• GeClipMap::GetTextHeight(): Returns the text height using the current font.
• GeClipMap::GetTextAscent(): Returns the ascent using the current font.

The currently used font is defined with:

• GeClipMap::GetFont(): Gets a BaseContainer with the current font description.
• GeClipMap::SetFont(): Sets the currently used font using a BaseContainer.

  // 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.
 
  AutoAlloc<GeClipMap> clipMap;
  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:

• GeClipMap::GetDefaultFont(): Gets a description of the default font.
• GeClipMap::GetFontDescription(): Gets a description of the given fonts. Currently supports only ::GE_FONT_NAME_POSTSCRIPT.
• GeClipMap::EnumerateFonts(): Gets a BaseContainer with a list of all fonts.
• GeClipMap::GetFontName(): Gets the font name from the given font description.
• GeClipMap::GetFontSize(): Gets the font size from the given font description.
• GeClipMap::SetFontSize(): Sets the font size in the given font description.

See also FontData and GeChooseFont().

  // This example gets all installed fonts and prints their names.
 
  // get all fonts
  BaseContainer fonts;
  GeClipMap::EnumerateFonts(&fonts, GE_CM_FONTSORT::HIERARCHICAL);
 
  // loop trough all fonts
 
  Int32 containerElement;
  GeData*         fontData = nullptr;
  BrowseContainer browse(&fonts);
 
  // browse
  while (browse.GetNext(&containerElement, &fontData))
  {
    const BaseContainer* const font = fontData->GetContainer();
    const BaseContainer* const fontInstance = font->GetContainerInstance(0);
 
    ApplicationOutput("Font:");
 
    // 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

• Files & Media
• Cinema API Files & Media
• BaseBitmap Manual
• BaseContainer Manual