#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 GeClipMap *	Alloc ()

static void	Free (GeClipMap *&data)

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)

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)

IMAGERESULT	Init (GeUserArea *userArea, Int32 x, Int32 y, Int32 w, Int32 h)

Destroy
void	Destroy ()

Dimensions
void	GetDim (Int32 w, Int32 h) const

Int32	GetBw () const

Int32	GetBh () const

Bitmap
BaseBitmap *	GetBitmap ()

const BaseBitmap *	GetBitmap () const

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)

Bool	SupportsDrawBezierSegment () const

void	DrawBezierSegment (const maxon::Vector2d *p)

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)

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] data The clip map to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

◆ Init() [1/6]

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]	w	The width in pixels.
[in]	h	The height in pixels.
[in]	bits	The 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/6]

IMAGERESULT Init ( BaseBitmap * bm )

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

Parameters

[in] bm The bitmap to initialize the clip map with. The caller owns the pointed bitmap.

Returns: The result: IMAGERESULT

◆ Init() [3/6]

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]	bm	The bitmap to initialize the clip map with. The caller owns the pointed bitmap.
[in]	alpha_channel	The alpha channel to use in bm. The caller owns the pointed bitmap.

Returns: The result: IMAGERESULT

◆ Init() [4/6]

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]	name	A valid filename.
[in]	frame	The frame number to load in a movie.
[out]	ismovie	If not nullptr this is assigned true if the loaded picture was a movie, and false otherwise.

Returns: The result: IMAGERESULT

◆ Init() [5/6]

IMAGERESULT Init ( const IconData & iconData )

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

Parameters

[in] iconData The icon data to initialize the clip map with.

Returns: The result: IMAGERESULT

◆ Init() [6/6]

IMAGERESULT Init	(	GeUserArea *	userArea,
		Int32	x,
		Int32	y,
		Int32	w,
		Int32	h
	)

◆ 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]	w	Assigned the width.
[in]	h	Assigned 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() [1/2]

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.

◆ GetBitmap() [2/2]

const BaseBitmap* GetBitmap ( ) const

◆ 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_x	The X distance in pixels.
[in]	off_y	The 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]	mode	The draw mode: GE_CM_DRAWMODE
[in]	par	The 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]	r	The red value. (Between 0 and 255.)
[in]	g	The green value. (Between 0 and 255.)
[in]	b	The blue value. (Between 0 and 255.)
[in]	a	The 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]	x	The X coordinate.
[in]	y	The 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]	x1	The first X coordinate.
[in]	y1	The first Y coordinate.
[in]	x2	The second X coordinate.
[in]	y2	The 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]	cnt	The number of elements in points.
[in]	points	The points in the polygon line. The caller owns the pointed array.

◆ SupportsDrawBezierSegment()

Bool SupportsDrawBezierSegment ( ) const

SupportsDrawBezierSegment returns true if the clipmap supports DrawBezierSegment().

Returns: true on success.

◆ DrawBezierSegment()

void DrawBezierSegment ( const maxon::Vector2d * p )

DrawBezierSegment description.

Parameters

[in] p 4 points for the bezier segment [p1, c1, c2, p2].

◆ 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]	cnt	The number of elements in points.
[in]	points	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The bottom right Y coordinate.
[in]	seg	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The bottom right Y coordinate.
[in]	seg	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The 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]	x	The X coordinate.
[in]	y	The Y coordinate.
[out]	r	Assigned the red value. (Between 0 and 255.)
[out]	g	Assigned the green value. (Between 0 and 255.)
[out]	b	Assigned the blue value. (Between 0 and 255.)
[out]	a	Assigned 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]	x	The X coordinate.
[in]	y	The Y coordinate.
[in]	r	The red value. (Between 0 and 255.)
[in]	g	The green value. (Between 0 and 255.)
[in]	b	The blue value. (Between 0 and 255.)
[in]	a	Alpha 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]	x	The top left X coordinate.
[in]	y	The top left Y coordinate.
[in]	txt	The 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] txt The 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]	dx	The top left destination X coordinate.
[in]	dy	The top left destination Y coordinate.
[in]	s_dp	The source.
[in]	sx1	The top left source X coordinate.
[in]	sy1	The top left source Y coordinate.
[in]	sx2	The bottom right source X coordinate.
[in]	sy2	The bottom right source Y coordinate.
[in]	rop	The 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]	left	The left position of the clipping region.
[in]	top	The top position of the clipping region.
[in]	right	The right position of the clipping region.
[in]	bottom	The 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]	points	An array of count points with the polygonal path. The caller owns the pointed array.
[in]	count	The number of elements in the points array.
[in]	mode	The 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]	x	The X coordinate.
[in]	y	The 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]	x1	The top left X coordinate.
[in]	y1	The top left Y coordinate.
[in]	x2	The bottom right X coordinate.
[in]	y2	The 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_description	The font description. Obtained from GeChooseFont(), GetFontDescription(), EnumerateFonts() or nullptr for the default font. The caller owns the pointed base container.
[in]	font_size	The 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_description Assigned 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_description	The font description. The caller owns the pointed base container.
[in]	type	The type of name: GeFontNameType
[out]	dst	Assigned 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]	name	The font name.
[in]	type	The type of font name: GeFontNameType
[out]	dst	Assigned 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]	dst	Assigned the font list. The caller owns the pointed base container.
[in]	sort_mode	The sort mode: GE_CM_FONTSORT

◆ GetDefaultFont()

static Bool GetDefaultFont	(	GeFontDefaultType	type,
		BaseContainer *	font_description
	)

static

Retrieves Cinema 4D's default font.

Parameters

[in]	type	The default font type: GeFontDefaultType
[out]	font_description	Assigned 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_description	The font description. The caller owns the pointed base container.
[in]	type	The font size type: GeFontSizeType
[out]	size	Assigned 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_description	The font description. The caller owns the pointed base container.
[in]	type	The font size type: GeFontSizeType
[in]	size	The font size to set.

Returns: true if successful, otherwise false.

Detailed Description

Private Member Functions

Alloc/Free

Font

Init

Destroy

Dimensions

Bitmap

Begin/End Draw

Set Offset/Draw Mode/Color

Drawing

Get/Set Pixel

Text

Blit

Clipping

Constructor & Destructor Documentation

◆ GeClipMap()

◆ ~GeClipMap()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ Init() [1/6]

◆ Init() [2/6]

◆ Init() [3/6]

◆ Init() [4/6]

◆ Init() [5/6]

◆ Init() [6/6]

◆ Destroy()

◆ GetDim()

◆ GetBw()

◆ GetBh()

◆ GetBitmap() [1/2]

◆ GetBitmap() [2/2]

◆ BeginDraw()

◆ EndDraw()

◆ SetOffset()

◆ SetDrawMode()

◆ SetColor()

◆ SetPixel()

◆ Line()

◆ PolyLine()

◆ SupportsDrawBezierSegment()

◆ DrawBezierSegment()

◆ FillPolygon()

◆ Rect()

◆ FillRect()

◆ Arc()

◆ FillArc()

◆ Ellipse()

◆ FillEllipse()

◆ GetPixelRGBA()

◆ SetPixelRGBA()

◆ TextAt()

◆ GetTextWidth()

◆ GetTextHeight()

◆ GetTextAscent()

◆ Blit()

◆ SetClipRgn() [1/2]

◆ SetClipRgn() [2/2]

◆ ClipPoint()

◆ ClipArea()

◆ SetFont()

◆ GetFont()

◆ GetFontName()

◆ GetFontDescription()

◆ EnumerateFonts()

◆ GetDefaultFont()

◆ GetFontSize()

◆ SetFontSize()