BaseBitmap Class Reference

#include <c4d_basebitmap.h>

Inheritance diagram for BaseBitmap:

Detailed Description

The bitmap class can be used to load, read, draw and save bitmap pictures of various formats.
Bitmaps are organized so that the 2D point [0,0] is the top left corner. Be sure to call Init() before you attempt to use a newly allocated bitmap.

Note
Has to be created with Alloc() and destroyed with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.
Warning
Though BaseBitmap can work with other bit depths than 24 and 32, note that only these function support other bit depths:
GetBw(), GetBh(), GetBt(), GetBpz(), Init(), GetLine(), SetLine(), GetPixelCnt(), SetPixelCnt(), SetCMAP(),
AddChannel(), RemoveChannel(), GetAlphaPixel(), SetAlphaPixel(), GetInternalChannel(), GetChannelCount(), GetChannelNum()
To use higher bit depths or multiple channels, see MultipassBitmap.

Private Member Functions

 BaseBitmap ()
 
 ~BaseBitmap ()
 

Alloc/Free

static BaseBitmapAlloc (void)
 
static void Free (BaseBitmap *&bm)
 

Init

static IMAGERESULT Init (BaseBitmap *&res, const Filename &name, Int32 frame=-1, Bool *ismovie=nullptr, BitmapLoaderPlugin **loaderplugin=nullptr, const maxon::Delegate< void(Float progress)> &progressCallback=nullptr)
 
IMAGERESULT Init (const Filename &name, Int32 frame=-1, Bool *ismovie=nullptr)
 
IMAGERESULT Init (Int32 x, Int32 y, Int32 depth=24, INITBITMAPFLAGS flags=INITBITMAPFLAGS_0)
 

Reset

void FlushAll (void)
 

Save

IMAGERESULT Save (const Filename &name, Int32 format, BaseContainer *data, SAVEBIT savebits) const
 

Copy

BaseBitmapGetClone (void) const
 
BaseBitmapGetClonePart (Int32 x, Int32 y, Int32 w, Int32 h) const
 
Bool CopyTo (BaseBitmap *dst) const
 
Bool CopyPartTo (BaseBitmap *dst, Int32 x, Int32 y, Int32 w, Int32 h) const
 

Bitmap Information

Int32 GetBw (void) const
 
Int32 GetBh (void) const
 
Int32 GetBt (void) const
 
Int32 GetBpz (void) const
 
COLORMODE GetColorMode (void) const
 

Scaling

void ScaleIt (BaseBitmap *dst, Int32 intens, Bool sample, Bool nprop) const
 
void ScaleBicubic (BaseBitmap *dst, Int32 src_xmin, Int32 src_ymin, Int32 src_xmax, Int32 src_ymax, Int32 dst_xmin, Int32 dst_ymin, Int32 dst_xmax, Int32 dst_ymax) const
 

Drawing

void SetPen (Int32 r, Int32 g, Int32 b)
 
void Clear (Int32 r, Int32 g, Int32 b)
 
void Clear (Int32 x1, Int32 y1, Int32 x2, Int32 y2, Int32 r, Int32 g, Int32 b)
 
void Line (Int32 x1, Int32 y1, Int32 x2, Int32 y2)
 
void Arc (Int32 x, Int32 y, Float radius, Float angle_start, Float angle_end, Int32 subdiv=32)
 

Get/Set Pixels

void GetPixel (Int32 x, Int32 y, UInt16 *r, UInt16 *g, UInt16 *b) const
 
Bool SetPixel (Int32 x, Int32 y, Int32 r, Int32 g, Int32 b)
 
void GetAlphaPixel (BaseBitmap *channel, Int32 x, Int32 y, UInt16 *val) const
 
Bool SetAlphaPixel (BaseBitmap *channel, Int32 x, Int32 y, Int32 val)
 
void GetPixelCnt (Int32 x, Int32 y, Int32 cnt, UChar *buffer, Int32 inc, COLORMODE dstmode, PIXELCNT flags, ColorProfileConvert *conversion=nullptr) const
 
Bool SetPixelCnt (Int32 x, Int32 y, Int32 cnt, UChar *buffer, Int32 inc, COLORMODE srcmode, PIXELCNT flags)
 

Channels

BaseBitmapAddChannel (Bool internal, Bool straight)
 
void RemoveChannel (BaseBitmap *channel)
 
const BaseBitmapGetInternalChannel (void) const
 
BaseBitmapGetInternalChannel (void)
 
Int32 GetChannelCount (void) const
 
const BaseBitmapGetChannelNum (Int32 num) const
 
BaseBitmapGetChannelNum (Int32 num)
 

Get/Set Data

GeData GetData (Int32 id, const GeData &t_default) const
 
Bool SetData (Int32 id, const GeData &data)
 

Dirty

UInt32 GetDirty () const
 
void SetDirty ()
 

Update Region

const BaseBitmapGetUpdateRegionBitmap () const
 
BaseBitmapGetUpdateRegionBitmap ()
 

Color Profile

Bool SetColorProfile (const ColorProfile *profile)
 
const ColorProfileGetColorProfile () const
 

Miscellaneous

Int GetMemoryInfo (void) const
 
Bool IsMultipassBitmap (void) const
 
void SetCMAP (Int32 i, Int32 r, Int32 g, Int32 b)
 

Constructor & Destructor Documentation

§ BaseBitmap()

BaseBitmap ( )
private

§ ~BaseBitmap()

~BaseBitmap ( )
private

Member Function Documentation

§ Alloc()

static BaseBitmap* Alloc ( void  )
static

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

Returns
The allocated bitmap, or nullptr if the allocation failed.

§ Free()

static void Free ( BaseBitmap *&  bm)
static

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

Parameters
[in,out]bmThe bitmap to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

§ Init() [1/3]

static IMAGERESULT Init ( BaseBitmap *&  res,
const Filename name,
Int32  frame = -1,
Bool ismovie = nullptr,
BitmapLoaderPlugin **  loaderplugin = nullptr,
const maxon::Delegate< void(Float progress)> &  progressCallback = nullptr 
)
static

Loads a bitmap file. The format is automatically detected.

Note
The bitmap class only supports up to 4 channels. Also, most image loaders will only load one alpha channel.
Parameters
[out]resAssigned a pointer to a bitmap. The caller owns the pointed bitmap.
[in]nameA valid filename that can either refer a movie or a picture.
[in]frameThe frame number to load in a movie.
[in]ismovieIf not nullptr this pointer is assigned true if the loaded picture is a movie, otherwise false.
[in]loaderpluginIf not nullptr this pointer is assigned a bitmap loader plugin instance of the same type as the loaded bitmap. The caller owns the pointed bitmap loader.
[in]progressCallbackCallback which is triggered if the loader supports progress reporting. Since R19.
Returns
The image result: IMAGERESULT

§ Init() [2/3]

IMAGERESULT Init ( const Filename name,
Int32  frame = -1,
Bool ismovie = nullptr 
)

Loads a file into the bitmap. The file format is automatically detected.

Warning
Any previous data in the bitmap object is lost.
Note
The bitmap class only supports up to 4 channels. Also, most image loaders will only load one alpha channel.
Parameters
[in]nameA valid filename that can either refer a movie or a picture.
[in]frameThe frame number to load in a movie.
[in]ismovieIf not nullptr this pointer is assigned true if the loaded picture is a movie, otherwise false.
Returns
The image result: IMAGERESULT

§ Init() [3/3]

IMAGERESULT Init ( Int32  x,
Int32  y,
Int32  depth = 24,
INITBITMAPFLAGS  flags = INITBITMAPFLAGS_0 
)

Initializes the bitmap to the given [x,y] dimensions and depth.

Warning
Any previous data in the bitmap object is lost.
Parameters
[in]xThe requested width in pixels (Maximum 16 000 pixels).
[in]yThe requested height in pixels (Max. 16000 pixels).
[in]depthThe requested bit depth. The possible values are (1, 4, 8, 16, 24, 32, 64, 96). On some platforms 32-bit will be used even if 24 is requested, to allow for padding. In this case GetBt() will return 32.
[in]flagsThe initialization flags: INITBITMAPFLAGS
Returns
The image result: IMAGERESULT

§ FlushAll()

void FlushAll ( void  )

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

§ Save()

IMAGERESULT Save ( const Filename name,
Int32  format,
BaseContainer data,
SAVEBIT  savebits 
) const

Saves the bitmap to a file.

Parameters
[in]nameA valid filename that can either refer a movie or a picture.
[in]formatThe image format: FILTER
[in]dataThe additional settings for some formats. MISCSAVER
Can be nullptr, which means the same as an empty container. The caller owns the pointed container.
[in]savebitsA combination of the following flags: SAVEBIT
Returns
The image result: IMAGERESULT

§ GetClone()

BaseBitmap* GetClone ( void  ) const

Copies the bitmap.

Warning
Do not use GetClone() in a NodeData::CopyTo method. This will cause memory leaks. Use CopyTo() instead.
Returns
The cloned bitmap, or nullptr if an error occured. The caller owns the pointed bitmap.

§ GetClonePart()

BaseBitmap* GetClonePart ( Int32  x,
Int32  y,
Int32  w,
Int32  h 
) const

Copies a part of the bitmap, specified by the rectangle [x,y] to [x+w,y+h].

Parameters
[in]xThe upper left X coordinate of the rectangle.
[in]yThe upper left Y coordinate of the rectangle.
[in]wThe width of the rectangle.
[in]hThe height of the rectangle.
Returns
The cloned part of the bitmap, or nullptr if an error occured. The caller owns the pointed bitmap.

§ CopyTo()

Bool CopyTo ( BaseBitmap dst) const

Copies the bitmap from *this to *dst.

Parameters
[out]dstThe bitmap to copy this bitmap to. The caller owns the pointed bitmap.
Returns
true if the bitmap was successfully copied, otherwise false.

§ CopyPartTo()

Bool CopyPartTo ( BaseBitmap dst,
Int32  x,
Int32  y,
Int32  w,
Int32  h 
) const

Copies a part of the bitmap from *this to *dst.

Parameters
[out]dstThe bitmap to copy this bitmap to. The caller owns the pointed bitmap.
[in]xThe X position of the part to be copied from *this.
[in]yThe Y position of the part to be copied from *this.
[in]wThe width of the part to be copied.
[in]hThe height of the part to be copied.
Returns
true if the bitmap part was successfully copied, otherwise false.

§ GetBw()

Int32 GetBw ( void  ) const

Gets the width of the bitmap in pixels. If the bitmap has not been initialized the return value is 0.

Note
Calling this method is the only way to see if a bitmap passed by Cinema 4D or some other source has been initialized.
Returns
The bitmap width in pixels, or 0 if the bitmap is not initialized.

§ GetBh()

Int32 GetBh ( void  ) const

Gets the height of the bitmap in pixels.

Returns
The bitmap height in pixels.

§ GetBt()

Int32 GetBt ( void  ) const

Gets the number of bits per pixel.

Returns
The number of bits per pixel.

§ GetBpz()

Int32 GetBpz ( void  ) const

Gets the number of bytes per line.

Returns
The number of bytes per line.

§ GetColorMode()

COLORMODE GetColorMode ( void  ) const

Gets the color mode of the bitmap.

Returns
The color mode: COLORMODE

§ ScaleIt()

void ScaleIt ( BaseBitmap dst,
Int32  intens,
Bool  sample,
Bool  nprop 
) const

Scales the bitmap to fit in the destination bitmap and copies it there.
The destination bitmap dst needs to be initialized with the destination size before calling this function.

Parameters
[out]dstThe destination bitmap. The caller owns the pointed bitmap.
[in]intensLets you change brightness of the image (128 = 50% brightness, 256 = unchanged).
[in]sampleIf true a better scaling algorithm is used, which results in a better quality but a bit slower.
[in]npropMust be true if non-proportional scaling is wanted.

§ ScaleBicubic()

void ScaleBicubic ( BaseBitmap dst,
Int32  src_xmin,
Int32  src_ymin,
Int32  src_xmax,
Int32  src_ymax,
Int32  dst_xmin,
Int32  dst_ymin,
Int32  dst_xmax,
Int32  dst_ymax 
) const

Scales the bitmap rectangle [src_xmin,src_ymin,src_xmax,src_ymax] to fit in the destination bitmap rectangle [dst_xmin,dst_ymin,dst_xmax,dst_ymax] and copies it there.
The scaling, if necessary, is done using Bicubic interpolation.
The destination bitmap dst needs to be initialized before calling this function.

Note
This function can currently only scale down, i.e. the destination needs to be smaller or equal to the source in size.
Parameters
[out]dstThe destination bitmap. The caller owns the pointed bitmap.
[in]src_xminThe source top left X coordinate.
[in]src_yminThe source top left Y coordinate.
[in]src_xmaxThe source bottom right X coordinate.
[in]src_ymaxThe source bottom right Y coordinate.
[in]dst_xminThe destination top left X coordinate.
[in]dst_yminThe destination top left Y coordinate.
[in]dst_xmaxThe destination bottom right X coordinate.
[in]dst_ymaxThe destination bottom right Y coordinate.

§ SetPen()

void SetPen ( Int32  r,
Int32  g,
Int32  b 
)

Sets the color for the following drawing operations.
The range of the parameters is 0 to 255, where (255,255,255) is white, regardless of the bit depth of the image.

Note
This method only works with bit depth 24 and 32.
Parameters
[in]rThe red component.
[in]gThe green component.
[in]bThe blue component.

§ Clear() [1/2]

void Clear ( Int32  r,
Int32  g,
Int32  b 
)

Sets all pixels in the bitmap to the color specified by (r,g,b).
The range of the parameters is 0 to 255, where (255,255,255) is white, regardless of the bit depth of the image.

Note
This method only works with bit depth 24 and 32.
Parameters
[in]rThe red component.
[in]gThe green component.
[in]bThe blue component.

§ Clear() [2/2]

void Clear ( Int32  x1,
Int32  y1,
Int32  x2,
Int32  y2,
Int32  r,
Int32  g,
Int32  b 
)

Sets all pixels within the rectangle specified by [x1,y1] and [x2,y2] to the color specified by (r,g,b).
The range of the parameters is 0 to 255, where (255,255,255) is white, regardless of the bit depth of the image.

Note
This method only works with bit depth 24 and 32.
Parameters
[in]x1The top left X coordinate of the rectangle.
[in]y1The top left Y coordinate of the rectangle.
[in]x2The bottom right X coordinate of the rectangle.
[in]y2The bottom right Y coordinate of the rectangle.
[in]rThe red component.
[in]gThe green component.
[in]bThe blue component.

§ Line()

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

Draws a line with the current pen color between (x1,y1) and (x2,y2).

Note
This method only works with bit depth 24 and 32.
Parameters
[in]x1The start X coordinate.
[in]y1The start Y coordinate.
[in]x2The end X coordinate.
[in]y2The end Y coordinate.

§ Arc()

void Arc ( Int32  x,
Int32  y,
Float  radius,
Float  angle_start,
Float  angle_end,
Int32  subdiv = 32 
)

Draws an arc (section of a circle) with the current pen color at [x,y].

Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
[in]radiusThe radius of the ellipse.
[in]angle_startThe start of the angle in radians.
[in]angle_endThe end of the angle in radians.
[in]subdivThe range between angle_start and angle_end is divided into subdiv line segments.

§ GetPixel()

void GetPixel ( Int32  x,
Int32  y,
UInt16 r,
UInt16 g,
UInt16 b 
) const

Gets the color at [x,y] and assigns it to the passed (r,g,b) parameters.
The range of the assigned r, g and b parameters is 0 to 255, where (255,255,255) is white, regardless of the bit depth of the image.

Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
[out]rAssigned the red component.
[out]gAssigned the green component.
[out]bAssigned the blue component.

§ SetPixel()

Bool SetPixel ( Int32  x,
Int32  y,
Int32  r,
Int32  g,
Int32  b 
)

Sets the pixel at [x,y] to the color specified by (r,g,b) (0 <= r/g/b <= 255).
The range of the r, g and b parameters is 0 to 255, where (255,255,255) is white, regardless of the bit depth of the image.

Parameters
[in]xThe X coordinate.
[in]yThe Y coordinate.
[in]rThe red component.
[in]gThe green component.
[in]bThe blue component.
Returns
true if the pixel was successfully set, otherwise false.

§ GetAlphaPixel()

void GetAlphaPixel ( BaseBitmap channel,
Int32  x,
Int32  y,
UInt16 val 
) const

Gets the alpha value at [x,y] and assigns it to the passed parameter val (0 <= val <= 255).

Parameters
[in]channelThe alpha channel to use.
[in]xThe X coordinate.
[in]yThe Y coordinate.
[out]valAssigned the alpha value.

§ SetAlphaPixel()

Bool SetAlphaPixel ( BaseBitmap channel,
Int32  x,
Int32  y,
Int32  val 
)

Sets the alpha value at [x,y] to val.

Parameters
[in]channelThe alpha channel to use.
[in]xThe X coordinate.
[in]yThe Y coordinate.
[in]valThe alpha value. 0 <= val <= 255

§ GetPixelCnt()

void GetPixelCnt ( Int32  x,
Int32  y,
Int32  cnt,
UChar buffer,
Int32  inc,
COLORMODE  dstmode,
PIXELCNT  flags,
ColorProfileConvert conversion = nullptr 
) const

Reads cnt pixels from [x,y] in the bitmap to the buffer with the color mode dstmode, incrementing inc bytes for each pixel.

Parameters
[in]xThe X coordinate of the first pixel to get.
[in]yThe Y coordinate of the first pixel to get.
[in]cntThe number of pixels to get.
[out]bufferA pointer to a large enough memory buffer where the pixel data will be written. The caller owns the pointed buffer.
[in]incThe byte increment per pixel in the buffer.
[in]dstmodeThe destination color mode: COLORMODE
[in]flagsThe flags: PIXELCNT
[in]conversionThis should be normally set to nullptr. Pass a color profile only if a conversion is wanted before retrieving the pixel data.
This only works if either the bitmap is 32-bit per component (so no 8/16-bit images) or the dstmode is 32-bit per component.
The conversion is done before color reduction (e.g. if dstmode is 16-bit the profile is first applied and then the data resampled to 16-bit).

§ SetPixelCnt()

Bool SetPixelCnt ( Int32  x,
Int32  y,
Int32  cnt,
UChar buffer,
Int32  inc,
COLORMODE  srcmode,
PIXELCNT  flags 
)

Sets cnt pixels at [x,y] in the bitmap from buffer with color mode srcmode, incrementing inc bytes for each pixel.

Parameters
[in]xThe X coordinate of the first pixel to set.
[in]yThe Y coordinate of the first pixel to set.
[in]cntThe number of pixels to set.
[in]bufferA pointer to a large enough memory buffer containing the pixels to set. The caller owns the pointed buffer.
[in]incThe byte increment per pixel in the buffer.
[in]srcmodeThe source color mode: COLORMODE
Warning
None of the alpha modes are supported.
Parameters
[in]flagsThe flags: PIXELCNT
Returns
true if successful, otherwise false.

§ AddChannel()

BaseBitmap* AddChannel ( Bool  internal,
Bool  straight 
)

Adds a new alpha channel to the bitmap.

Note
The bitmap class only supports up to 4 channels.
Parameters
[in]internalShould only be true for the first alpha. The internal alpha will be stored within a bitmaps if its format supports alphas.
[in]straightShould be true if the bitmap has to be interpreted as straight.
For information about straight alphas please take a look at the corresponding option in the render settings and the manual of Cinema 4D.
Returns
The newly added channel if successful, otherwise nullptr.

§ RemoveChannel()

void RemoveChannel ( BaseBitmap channel)

Removes the specified channel from the bitmap.

Parameters
[in]channelThe alpha channel to remove.

§ GetInternalChannel() [1/2]

const BaseBitmap* GetInternalChannel ( void  ) const

Gets the internal read-only alpha channel.

Note
The internal alpha channel is the one that is saved together with the picture, with those formats that support this.
Returns
The read-only internal alpha channel, or nullptr if no internal alpha is available. The bitmap owns the pointed channel.

§ GetInternalChannel() [2/2]

BaseBitmap* GetInternalChannel ( void  )

Gets the internal alpha channel.

Note
The internal alpha channel is the one that is saved together with the picture, with those formats that support this.
Returns
The read-only internal alpha channel, or nullptr if no internal alpha is available. The bitmap owns the pointed channel.

§ GetChannelCount()

Int32 GetChannelCount ( void  ) const

Gets the number of alpha channels in the bitmap, including the internal channel.

Returns
The number of alpha channels.

§ GetChannelNum() [1/2]

const BaseBitmap* GetChannelNum ( Int32  num) const

Gets the read-only alpha channel specified by num.

Parameters
[in]numAn alpha channel index between 0 and GetChannelCount().
Returns
The requested read-only channel.

§ GetChannelNum() [2/2]

BaseBitmap* GetChannelNum ( Int32  num)

Gets the alpha channel specified by num.

Parameters
[in]numAn alpha channel index between 0 and GetChannelCount().
Returns
The requested channel.

§ GetData()

GeData GetData ( Int32  id,
const GeData t_default 
) const

Gets bitmap data. Private.

Parameters
[in]idThe data ID to Get: BASEBITMAP_DATA
[in]t_defaultThe default data to use.
Returns
The retrieved data.

§ SetData()

Bool SetData ( Int32  id,
const GeData data 
)

Sets bitmap data. Private.

Parameters
[in]idThe data ID to set: BASEBITMAP_DATA
[in]dataThe data to set.
Returns
true if the data could be set, otherwise false.

§ GetDirty()

UInt32 GetDirty ( ) const

Gets the incremented dirty count when the bitmap changes. Private.

Returns
The dirty count.

§ SetDirty()

void SetDirty ( )

Makes the bitmap dirty. Private.

§ GetUpdateRegionBitmap() [1/2]

const BaseBitmap* GetUpdateRegionBitmap ( ) const

Gets the updated region of a bitmap (read-only).

Returns
The updated region.

§ GetUpdateRegionBitmap() [2/2]

BaseBitmap* GetUpdateRegionBitmap ( )

Gets the updated region of a bitmap.

Returns
The updated region.

§ SetColorProfile()

Bool SetColorProfile ( const ColorProfile profile)

Sets the color profile for the bitmap.

Parameters
[in]profileThe new color profile. The caller owns the pointed color profile.
Returns
true if the color profile was successfully set, otherwise false.

§ GetColorProfile()

const ColorProfile* GetColorProfile ( ) const

Gets the color profile of the bitmap.

Returns
The color profile of the bitmap, or nullptr if not available.

§ GetMemoryInfo()

Int GetMemoryInfo ( void  ) const

Gets the size of the memory used by the bitmap.

Returns
The memory size of the bitmap.

§ IsMultipassBitmap()

Bool IsMultipassBitmap ( void  ) const

Checks if this BaseBitmap instance is a MultipassBitmap.

Returns
true if the instance can be safely casted to MultipassBitmap, otherwise false.

§ SetCMAP()

void SetCMAP ( Int32  i,
Int32  r,
Int32  g,
Int32  b 
)

If the image in the bitmap has 8-bit indexed color, this function can be used to set the palette entries.

Note
All four parameters must be between 0 and 255.
Parameters
[in]iThe index. 0 <= i <= 255
[in]rThe red component. 0 <= r <= 255
[in]gThe green component. 0 <= g <= 255
[in]bThe blue component. 0 <= b <= 255