GeClipMap Class Reference

#include <lib_clipmap.h>

Detailed Description

This class stores and manipulates a bitmap, providing more advanced drawing tools than BaseBitmap.
Be sure to call Init() before trying to use a newly allocated clip map.

Note
Though clip maps support other bit depths than 32, the functionality is severely limited.
It is recommended that the clip map class is only used for 32 bit bitmaps. (Please note that the default bit depth for BaseBitmap is 24).
Has to be created with Alloc() and destroyed with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Private Member Functions

 GeClipMap ()
 
 ~GeClipMap ()
 

Alloc/Free

static GeClipMapAlloc ()
 
static void Free (GeClipMap *&data)
 

Init

IMAGERESULT Init (Int32 w, Int32 h, Int32 bits)
 
IMAGERESULT Init (BaseBitmap *bm)
 
IMAGERESULT Init (BaseBitmap *bm, BaseBitmap *alpha_channel)
 
IMAGERESULT Init (const Filename &name, Int32 frame, Bool *ismovie)
 
IMAGERESULT Init (const IconData &iconData)
 

Destroy

void Destroy ()
 

Dimensions

void GetDim (Int32 *w, Int32 *h) const
 
Int32 GetBw () const
 
Int32 GetBh () const
 

Bitmap

BaseBitmapGetBitmap ()
 

Begin/End Draw

void BeginDraw ()
 
void EndDraw ()
 

Set Offset/Draw Mode/Color

void SetOffset (Int32 off_x, Int32 off_y)
 
void SetDrawMode (GE_CM_DRAWMODE mode, UInt32 par)
 
void SetColor (Int32 r, Int32 g, Int32 b, Int32 a=255)
 

Drawing

void SetPixel (Int32 x, Int32 y)
 
void Line (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 
void PolyLine (Int32 cnt, GE_POINT2D *points)
 
void FillPolygon (Int32 cnt, GE_POINT2D *points)
 
void Rect (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 
void FillRect (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 
void Arc (Int32 x1, Int32 y1, Int32 x2, Int32 y2, GE_CM_ARCSEGMENT seg)
 
void FillArc (Int32 x1, Int32 y1, Int32 x2, Int32 y2, GE_CM_ARCSEGMENT seg)
 
void Ellipse (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 
void FillEllipse (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 

Get/Set Pixel

void GetPixelRGBA (Int32 x, Int32 y, Int32 *r, Int32 *g, Int32 *b, Int32 *a)
 
void SetPixelRGBA (Int32 x, Int32 y, Int32 r, Int32 g, Int32 b, Int32 a=255)
 

Text

void TextAt (Int32 x, Int32 y, const String &txt)
 
Int32 GetTextWidth (const String &txt)
 
Int32 GetTextHeight ()
 
Int32 GetTextAscent ()
 

Blit

void Blit (Int32 dx, Int32 dy, const GeClipMap &s_dp, Int32 sx1, Int32 sy1, Int32 sx2, Int32 sy2, GE_CM_BLIT rop)
 

Clipping

void SetClipRgn (Int32 left, Int32 top, Int32 right, Int32 bottom)
 
void SetClipRgn (GE_POINT2D *points, Int32 count, GE_CM_CLIPREGION mode)
 
Bool ClipPoint (Int32 x, Int32 y)
 
Int32 ClipArea (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 

Font

static Bool GetFontName (BaseContainer const *font_description, GeFontNameType type, String *dst)
 
static Bool GetFontDescription (String const &name, GeFontNameType type, BaseContainer *dst)
 
static void EnumerateFonts (BaseContainer *dst, GE_CM_FONTSORT sort_mode)
 
static Bool GetDefaultFont (GeFontDefaultType type, BaseContainer *font_description)
 
static Bool GetFontSize (BaseContainer const *font_description, GeFontSizeType type, Float *size)
 
static Bool SetFontSize (BaseContainer *font_description, GeFontSizeType type, Float size)
 
Bool SetFont (BaseContainer const *font_description, Float font_size=0.0)
 
Float GetFont (BaseContainer *font_description)
 

Constructor & Destructor Documentation

§ GeClipMap()

GeClipMap ( )
private

§ ~GeClipMap()

~GeClipMap ( )
private

Member Function Documentation

§ Alloc()

static GeClipMap* Alloc ( )
static

Allocates a clip map. Destroy the allocated clip map with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Returns
The allocated clip map, or nullptr if the allocation failed.

§ Free()

static void Free ( GeClipMap *&  data)
static

Destructs clip maps allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in]dataThe clip map to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

§ Init() [1/5]

IMAGERESULT Init ( Int32  w,
Int32  h,
Int32  bits 
)

Initializes the clip map bitmap to the given dimensions and depth. Any previous data is lost.

Parameters
[in]wThe width in pixels.
[in]hThe height in pixels.
[in]bitsThe requested bit depth. The possible values are {1, 4, 8, 16, 24, 32}. On some platforms 32 bits will be used even if 24 is requested, to allow for padding.
Returns
The result: IMAGERESULT

§ Init() [2/5]

IMAGERESULT Init ( BaseBitmap bm)

Loads the clip map bitmap from bm. Any previous data is lost.

Parameters
[in]bmThe bitmap to initialize the clip map with. The pointed bitmap is copied.
Returns
The result: IMAGERESULT

§ Init() [3/5]

IMAGERESULT Init ( BaseBitmap bm,
BaseBitmap alpha_channel 
)

Loads the clip map bitmap from bm with the specified alpha channel. Any previous data is lost.

Parameters
[in]bmThe bitmap to initialize the clip map with. The pointed bitmap is copied.
[in]alpha_channelThe alpha channel to use in bm. The pointed bitmap is copied.
Returns
The result: IMAGERESULT

§ Init() [4/5]

IMAGERESULT Init ( const Filename name,
Int32  frame,
Bool ismovie 
)

Loads the clip map bitmap from the file specified by name. The file can be either a movie or a picture. The file format is automatically detected. Any previous data is lost.

Parameters
[in]nameA valid filename.
[in]frameThe frame number to load in a movie.
[out]ismovieIf not nullptr this is assigned true if the loaded picture was a movie, and false otherwise.
Returns
The result: IMAGERESULT

§ Init() [5/5]

IMAGERESULT Init ( const IconData iconData)

Loads the clip map bitmap from iconData. Any previous data is lost.

Parameters
[in]iconDataThe icon data to initialize the clip map with.
Returns
The result: IMAGERESULT

§ Destroy()

void Destroy ( )

Resets the clip map to its initial state and frees allocated memory.
Requires a new call to Init() before the clip map can be used again.

§ GetDim()

void GetDim ( Int32 w,
Int32 h 
) const

Retrieves the pixel dimensions of the clip map.

Parameters
[in]wAssigned the width.
[in]hAssigned the height.

§ GetBw()

Int32 GetBw ( ) const

Retrieves the pixel width of the clip map.

Returns
The width.

§ GetBh()

Int32 GetBh ( ) const

Retrieves the pixel height of the clip map.

Returns
The height.

§ GetBitmap()

BaseBitmap* GetBitmap ( )

Retrieves a pointer to the internal bitmap.

Warning
The clip map alpha channel will not be encoded in this bitmap. This is a limitation.
Returns
The internal bitmap. The clip map owns the pointed bitmap.

§ BeginDraw()

void BeginDraw ( )

Must be called before any drawing functions.

§ EndDraw()

void EndDraw ( )

Must be called after a sequence of drawing functions to free the memory allocated by BeginDraw().

§ SetOffset()

void SetOffset ( Int32  off_x,
Int32  off_y 
)

Offsets all the following draw commands by the given amount.

Note
The clip region is not offset.
Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]off_xThe X distance in pixels.
[in]off_yThe Y distance in pixels.

§ SetDrawMode()

void SetDrawMode ( GE_CM_DRAWMODE  mode,
UInt32  par 
)

Sets the draw mode.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]modeThe draw mode: GE_CM_DRAWMODE
[in]parThe parameter, depends on mode.

§ SetColor()

void SetColor ( Int32  r,
Int32  g,
Int32  b,
Int32  a = 255 
)

Sets the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]rThe red value. (Between 0 and 255.)
[in]gThe green value. (Between 0 and 255.)
[in]bThe blue value. (Between 0 and 255.)
[in]aThe alpha value. (Between 0 and 255.)

§ SetPixel()

void SetPixel ( Int32  x,
Int32  y 
)

Sets the pixel at (x,y) to the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.

§ Line()

void Line ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Draws a line from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The first X coordinate.
[in]y1The first Y coordinate.
[in]x2The second X coordinate.
[in]y2The second Y coordinate.

§ PolyLine()

void PolyLine ( Int32  cnt,
GE_POINT2D points 
)

Draws the polygon line specified by the cnt points with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]cntThe number of elements in points.
[in]pointsThe points in the polygon line. The caller owns the pointed array.

§ FillPolygon()

void FillPolygon ( Int32  cnt,
GE_POINT2D points 
)

Fills the polygon line specified by the cnt points with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]cntThe number of elements in points.
[in]pointsThe points in the polygon. The caller owns the pointed array.

§ Rect()

void Rect ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Draws the outline of a rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.

§ FillRect()

void FillRect ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.

§ Arc()

void Arc ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2,
GE_CM_ARCSEGMENT  seg 
)

Draws an arc within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.
[in]segThe arc is drawn in the direction given by: GE_CM_ARCSEGMENT

§ FillArc()

void FillArc ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2,
GE_CM_ARCSEGMENT  seg 
)

Fills an arc within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.
[in]segThe arc is drawn in the direction given by: GE_CM_ARCSEGMENT

§ Ellipse()

void Ellipse ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Draws an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.

§ FillEllipse()

void FillEllipse ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Fills an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.

§ GetPixelRGBA()

void GetPixelRGBA ( Int32  x,
Int32  y,
Int32 r,
Int32 g,
Int32 b,
Int32 a 
)

Retrieves the color of the pixel at (x,y).

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
[out]rAssigned the red value. (Between 0 and 255.)
[out]gAssigned the green value. (Between 0 and 255.)
[out]bAssigned the blue value. (Between 0 and 255.)
[out]aAssigned the alpha value. (Between 0 and 255.)

§ SetPixelRGBA()

void SetPixelRGBA ( Int32  x,
Int32  y,
Int32  r,
Int32  g,
Int32  b,
Int32  a = 255 
)

Sets the pixel at (x,y) to the specified color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
[in]rThe red value. (Between 0 and 255.)
[in]gThe green value. (Between 0 and 255.)
[in]bThe blue value. (Between 0 and 255.)
[in]aAlpha value. (Between 0 and 255.)

§ TextAt()

void TextAt ( Int32  x,
Int32  y,
const String txt 
)

Draws the string txt at (x,y) with the current draw color.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]xThe top left X coordinate.
[in]yThe top left Y coordinate.
[in]txtThe text.

§ GetTextWidth()

Int32 GetTextWidth ( const String txt)

Calculates the width of the string txt in the current font.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]txtThe text.
Returns
The text width.

§ GetTextHeight()

Int32 GetTextHeight ( )

Calculates the maximum height of text in the current font.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Returns
The text height.

§ GetTextAscent()

Int32 GetTextAscent ( )

Calculates the ascent in the current font. This is the distance from the baseline to the ascender line and usually represents the height of capital letters.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Returns
The text ascent.

§ Blit()

void Blit ( Int32  dx,
Int32  dy,
const GeClipMap s_dp,
Int32  sx1,
Int32  sy1,
Int32  sx2,
Int32  sy2,
GE_CM_BLIT  rop 
)

Blits from s_dp to the clip map.
The region (sx1,sy1) to (sx2,sy2) from the source will be copied into the region with the top left corner at (dx,dy) in the destination. Additionally specify a raster operation with rop.

Warning
This function must be enclosed between BeginDraw() and EndDraw().
Parameters
[in]dxThe top left destination X coordinate.
[in]dyThe top left destination Y coordinate.
[in]s_dpThe source.
[in]sx1The top left source X coordinate.
[in]sy1The top left source Y coordinate.
[in]sx2The bottom right source X coordinate.
[in]sy2The bottom right source Y coordinate.
[in]ropThe raster operation: GE_CM_BLIT

§ SetClipRgn() [1/2]

void SetClipRgn ( Int32  left,
Int32  top,
Int32  right,
Int32  bottom 
)

Sets the clipping region of the clip map. This affects all drawing commands so that nothing is drawn outside the region specified by (left,top) to (right,bottom).

Parameters
[in]leftThe left position of the clipping region.
[in]topThe top position of the clipping region.
[in]rightThe right position of the clipping region.
[in]bottomThe bottom position of the clipping region.

§ SetClipRgn() [2/2]

void SetClipRgn ( GE_POINT2D points,
Int32  count,
GE_CM_CLIPREGION  mode 
)

Sets the stored region to the inside of the polygonal path specified by the points array.

Parameters
[in]pointsAn array of count points with the polygonal path. The caller owns the pointed array.
[in]countThe number of elements in the points array.
[in]modeThe method used to determine the inside of the path: GE_CM_CLIPREGION

§ ClipPoint()

Bool ClipPoint ( Int32  x,
Int32  y 
)

Checks if a point is inside the clipping region.

Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
Returns
true if the point is inside the clipping region, otherwise false.

§ ClipArea()

Int32 ClipArea ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2 
)

Checks if a rectangle is inside the clipping region.

Parameters
[in]x1The top left X coordinate.
[in]y1The top left Y coordinate.
[in]x2The bottom right X coordinate.
[in]y2The bottom right Y coordinate.
Returns
The result.

§ SetFont()

Bool SetFont ( BaseContainer const *  font_description,
Float  font_size = 0.0 
)

Sets the current font.

Parameters
[in]font_descriptionThe font description. Obtained from GeChooseFont(), GetFontDescription(), EnumerateFonts() or nullptr for the default font. The caller owns the pointed base container.
[in]font_sizeThe font size, or 0.0 for the default height.
Returns
true if successful, otherwise false.

§ GetFont()

Float GetFont ( BaseContainer font_description)

Retrieves the current font.

Parameters
[out]font_descriptionAssigned the current font description. The caller owns the pointed base container.
Returns
The font size.

§ GetFontName()

static Bool GetFontName ( BaseContainer const *  font_description,
GeFontNameType  type,
String dst 
)
static

Retrieves the font name from a font description.

Parameters
[in]font_descriptionThe font description. The caller owns the pointed base container.
[in]typeThe type of name: GeFontNameType
[out]dstAssigned the font name. The caller owns the pointed string.
Returns
true if successful, otherwise false.

§ GetFontDescription()

static Bool GetFontDescription ( String const &  name,
GeFontNameType  type,
BaseContainer dst 
)
static

Retrieves a font description.

Parameters
[in]nameThe font name.
[in]typeThe type of font name: GeFontNameType
[out]dstAssigned the font description. The caller owns the pointed base container.
Returns
true if successful, otherwise false.

§ EnumerateFonts()

static void EnumerateFonts ( BaseContainer dst,
GE_CM_FONTSORT  sort_mode 
)
static

Enumerates all fonts and returns them in a container.
For each font a container (font description) will be inserted. They can be used for SetFont(), GetFontName() or as input for GeChooseFont().

Parameters
[out]dstAssigned the font list. The caller owns the pointed base container.
[in]sort_modeThe sort mode: GE_CM_FONTSORT

§ GetDefaultFont()

static Bool GetDefaultFont ( GeFontDefaultType  type,
BaseContainer font_description 
)
static

Retrieves Cinema 4D's default font.

Parameters
[in]typeThe default font type: GeFontDefaultType
[out]font_descriptionAssigned the font description. The caller owns the pointed base container.
Returns
true if successful, otherwise false.

§ GetFontSize()

static Bool GetFontSize ( BaseContainer const *  font_description,
GeFontSizeType  type,
Float size 
)
static

Retrieves the font size for a given font.

Parameters
[in]font_descriptionThe font description. The caller owns the pointed base container.
[in]typeThe font size type: GeFontSizeType
[out]sizeAssigned the font size.
Returns
true if successful, otherwise false.

§ SetFontSize()

static Bool SetFontSize ( BaseContainer font_description,
GeFontSizeType  type,
Float  size 
)
static

Sets the font size for a given font.

Parameters
[in]font_descriptionThe font description. The caller owns the pointed base container.
[in]typeThe font size type: GeFontSizeType
[in]sizeThe font size to set.
Returns
true if successful, otherwise false.