BaseBitmap Manual

About

A BaseBitmap object stores raster graphics image data. It can support multiple alpha channels. The BaseBitmap class is used in many different application areas inside Cinema 4D. An extensions of this class is MultipassBitmap which also supports multiple layers (see MultipassBitmap Manual).

Warning
For MAXON API image classes see Images Manual. For MAXON API media input and output see Media Sessions Manual.

Allocation/Deallocation

A BaseBitmap can be created with the usual tools:

After the BaseBitmap was created it has to be initiated with BaseBitmap::Init(). This can be done by

  • defining the dimensions of the new BaseBitmap
  • or by defining the file name of an image file to load

Also a static version of BaseBitmap::Init() exists that loads a image defined by a Filename into a given BaseBitmap object.

// This example opens a dialog to select an image file.
// The selected file is loaded into a BaseBitmap and displayed
// in the Picture Viewer window.
Filename selectedImageFile;
// select image file
if (!selectedImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image"_s))
return maxon::OK;
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// load image file into the given BaseBitmap
if (bitmap->Init(selectedImageFile) != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(selectedImageFile, MAXONCONVERTMODE::NONE), "Could not load image file."_s);
// show BaseBitmap in the Picture Viewer
ShowBitmap(bitmap);
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
@ NONE
No check if file exists under case-sensitive drives.
Bool ShowBitmap(const Filename &fn)
Definition: ge_autoptr.h:37
Manages file and path names.
Definition: c4d_file.h:94
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
return OK
Definition: apibase.h:2747
@ LOAD
Load dialog.
@ IMAGES
Image files.
@ OK
Image loaded/created.
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
// This example creates a new BaseBitmap with Full HD resolution.
// If the BaseBitmap could be created, it is filled with a color.
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// initialize the BaseBitmap with the given dimensions
const Int32 width = 1920;
const Int32 height = 1080;
const Int32 depth = 24;
const IMAGERESULT res = bitmap->Init(width, height, depth);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// loop through all pixels
Random randomGen;
for (Int32 x = 0; x < width; ++x)
{
for (Int32 y = 0; y < height; ++y)
{
// set to a 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);
bitmap->SetPixel(x, y, red, green, blue);
}
}
// show BaseBitmap in the Picture Viewer
ShowBitmap(bitmap);
static const Float COLORTOINT_MULTIPLIER
Constant to convert from vectors color components to integers.
Definition: c4d_tools.h:25
Definition: c4d_tools.h:835
MAXON_ATTRIBUTE_FORCE_INLINE Float Get01()
Definition: c4d_tools.h:865
PyObject * x
Definition: bytesobject.h:38
Py_UCS4 * res
Definition: unicodeobject.h:1113
maxon::Int32 Int32
Definition: ge_sys_math.h:60
IMAGERESULT
Definition: ge_prepass.h:3887
unsigned long Py_ssize_t width
Definition: pycore_traceback.h:88

AutoBitmap can be used to create a BaseBitmap from an image file in the plugin resource path or a resource ID. This is typically used in a "Register" function, see Registration.

// This example loads registered and local icons using AutoBitmap.
// load a registered icon ("Cube")
AutoBitmap cubeIcon(5159);
BaseBitmap* const bitmap = cubeIcon;
if (bitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(bitmap);
// load an image file in the plugin's "res" folder
AutoBitmap localIcon("icon.tif"_s);
if (localIcon == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(localIcon);
A simple BaseBitmap wrapper created from a filename or resource ID.
Definition: c4d_basebitmap.h:1538
Definition: c4d_basebitmap.h:435

Copy

The content of a BaseBitmap can be copied and with these functions:

// This example creates two clones of the given source bitmap.
// The two clones contain the left and right part of the bitmap.
// get original bitmap dimensions
const Int32 width = sourceBitmap->GetBw();
const Int32 height = sourceBitmap->GetBh();
// calculate left half width
const Int32 leftHalfWidth = width / 2;
// create clone with the left half of the bitmap
BaseBitmap* leftBitmap = sourceBitmap->GetClonePart(0, 0, leftHalfWidth, height);
if (leftBitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(leftBitmap);
BaseBitmap::Free(leftBitmap);
// create clone with the right half of the bitmap
const Int32 rightHalfWidth = width - leftHalfWidth;
BaseBitmap* rightBitmap = sourceBitmap->GetClonePart(leftHalfWidth, 0, rightHalfWidth, height);
if (rightBitmap == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ShowBitmap(rightBitmap);
BaseBitmap::Free(rightBitmap);
BaseBitmap * GetClonePart(Int32 x, Int32 y, Int32 w, Int32 h) const
static void Free(BaseBitmap *&bm)

Read-Only Properties

The basic properties of a BaseBitmap are accessed with:

// This example reads every line of the given BaseBitmap and
// inverts the RBG color.
// only handle 8-bit RGB bitmaps in this example
const COLORMODE colorMode = bitmap->GetColorMode();
if (colorMode != COLORMODE::RGB)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// get bit depth and buffer size for one line
const Int32 bitsPerPixel = bitmap->GetBt();
const Int32 bytesPerPixel = bitsPerPixel / 8;
const Int32 bufferSize = bitmap->GetBpz();
// allocate memory for one line
PIX* lineBuffer = NewMemClear(PIX, bufferSize) iferr_return;
// get bitmap dimensions
const Int32 width = bitmap->GetBw();
const Int32 height = bitmap->GetBh();
// loop through all lines
for (Int32 y = 0; y <= height; ++y)
{
// read full line from the bitmap
bitmap->GetPixelCnt(0, y, width, lineBuffer, bytesPerPixel, COLORMODE::RGB, PIXELCNT::NONE);
// this is a custom function
InvertLineRGB(lineBuffer, width);
// write full line back into the bitmap
bitmap->SetPixelCnt(0, y, width, lineBuffer, bytesPerPixel, COLORMODE::RGB, PIXELCNT::NONE);
}
// delete line memory
DeleteMem(lineBuffer);
void GetPixelCnt(Int32 x, Int32 y, Int32 cnt, UChar *buffer, Int32 inc, COLORMODE dstmode, PIXELCNT flags, ColorProfileConvert *conversion=nullptr) const
Definition: c4d_basebitmap.h:761
Int32 GetBw() const
Definition: c4d_basebitmap.h:574
Int32 GetBh() const
Definition: c4d_basebitmap.h:580
Bool SetPixelCnt(Int32 x, Int32 y, Int32 cnt, UChar *buffer, Int32 inc, COLORMODE srcmode, PIXELCNT flags)
Definition: c4d_basebitmap.h:774
Int32 GetBpz() const
Definition: c4d_basebitmap.h:592
COLORMODE GetColorMode() const
Int32 GetBt() const
Definition: c4d_basebitmap.h:586
#define NewMemClear(T, cnt)
Definition: defaultallocator.h:204
UChar PIX
8-bit integer pixel type.
Definition: ge_math.h:31
COLORMODE
Definition: ge_prepass.h:460
@ RGB
8-bit RGB channels.
@ NONE
None.
void DeleteMem(T *&p)
Definition: defaultallocator.h:257
#define iferr_return
Definition: resultbase.h:1521

The used color profile is managed with:

See also ColorProfile and ColorProfileConvert.

// This example sets the color profile according to the current
// settings of the given BaseDocument. The BaseBitmap is then drawn using
// this color profile inside a GeUserArea::DrawMsg() function.
// get linear workflow settings
const BaseContainer& docData = doc->GetDataInstanceRef();
const Bool linearWorkflow = docData.GetBool(DOCUMENT_LINEARWORKFLOW);
// set profile
if (linearWorkflow)
_bitmap->SetColorProfile(ColorProfile::GetDefaultLinearRGB());
else
_bitmap->SetColorProfile(ColorProfile::GetDefaultSRGB());
// draw bitmap using the profile
const Int32 drawMode = BMP_APPLY_COLORPROFILE;
DrawBitmap(_bitmap, 0, 0, width, height, 0, 0, width, height, drawMode);
Definition: c4d_basecontainer.h:48
Bool GetBool(Int32 id, Bool preset=false) const
Definition: c4d_basecontainer.h:332
static const ColorProfile * GetDefaultLinearRGB()
static const ColorProfile * GetDefaultSRGB()
@ DOCUMENT_LINEARWORKFLOW
Definition: ddoc.h:64
maxon::Bool Bool
Definition: ge_sys_math.h:55
@ BMP_APPLY_COLORPROFILE
Applies the color profile.
Definition: gui.h:176
const char * doc
Definition: pyerrors.h:226

Functionality

Bitmap

The content of a BaseBitmap can be scaled into another BaseBitmap:

Warning
MultipassBitmap overwrites these functions. The overwritten functions will scale the layers but not the alpha channels.
// This example creates a new bitmap with twice the size of the source bitmap.
// The new bitmap is filled with the scaled content of the source bitmap.
// create new bitmap
AutoAlloc<BaseBitmap> scaledBitmap;
if (scaledBitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get source bitmap dimensions
const Int32 originalWidth = sourceBitmap->GetBw();
const Int32 originalHeight = sourceBitmap->GetBh();
// initialize new bitmap with twice the size
const Int32 scale = 2;
const Int32 scaledWidth = originalWidth * scale;
const Int32 scaledHeight = originalHeight * scale;
const IMAGERESULT res = scaledBitmap->Init(scaledWidth, scaledHeight);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// fill new bitmap with scaled content of the source bitmap
const Int32 defaultBrightness = 256;
sourceBitmap->ScaleIt(scaledBitmap, defaultBrightness, true, false);

One can perform basic drawing operations with these functions:

Note
For more advanced drawing operations use a GeClipMap, see GeClipMap Manual.
// This example fills a BaseBitmap and draws a shape.
// fill the bitmap with white pixels
bitmap->Clear(255, 255, 255);
// set the pen to black
bitmap->SetPen(0, 0, 0);
// draw lines
bitmap->Line(100, 100, 300, 100);
bitmap->Line(100, 200, 300, 200);
// draw arcs
const Float quarterCircle = DegToRad(90.0);
const Float threeQuarterCircle = DegToRad(270.0);
bitmap->Arc(300, 150, 50.0, quarterCircle, -quarterCircle, 20);
bitmap->Arc(100, 150, 50.0, quarterCircle, threeQuarterCircle, 20);
void SetPen(Int32 r, Int32 g, Int32 b)
Definition: c4d_basebitmap.h:645
void Arc(Int32 x, Int32 y, Float radius, Float angle_start, Float angle_end, Int32 subdiv=32)
Definition: c4d_basebitmap.h:690
void Clear(Int32 r, Int32 g, Int32 b)
void Line(Int32 x1, Int32 y1, Int32 x2, Int32 y2)
Definition: c4d_basebitmap.h:679
maxon::Float Float
Definition: ge_sys_math.h:66
Float32 DegToRad(Float32 r)
Definition: apibasemath.h:256

Properties

A BaseBitmap is used as the target buffer of a rendering process. Details of that rendering process are stored with the bitmap itself and are displayed by the Picture Viewer. So these settings are mostly only relevant to the rendering pipeline were the given VPBuffer can be cast into a BaseBitmap / MultipassBitmap.

The settings are:

// This example adds a BitmapButton to the layout of the GeDialog.
// Depending on the pixel ratio a low-res or high-res bitmap file is loaded
// and applied to the BitmapButton.
void* const customGUI = AddCustomGui(1000, CUSTOMGUI_BITMAPBUTTON, ""_s, BFH_SCALEFIT, 300, 300, settings);
BitmapButtonCustomGui* const bitmapButtonGUI = static_cast<BitmapButtonCustomGui*>(customGUI);
if (bitmapButtonGUI)
{
// allocate bitmap
if (bitmap)
{
// get pixel ratio
const Float pixelRatio = GetPixelRatio();
// check if Retina or not
if (pixelRatio == 1.0)
filename = "lowRes.png";
else
filename = "highRes.png";
// load bitmap (GetFullFilename() is just a custom utility function)
const String fullFileName = GetFullFilename(filename);
if (bitmap->Init(fullFileName) == IMAGERESULT::OK)
{
// store ratio
bitmap->SetData(BASEBITMAP_DATA_GUIPIXELRATIO, pixelRatio);
// apply to BitmapButton
bitmapButtonGUI->SetImage(bitmap, true, false);
}
}
}
PyCompilerFlags const char * filename
Definition: ast.h:15
Definition: customgui_bitmapbutton.h:119
Bool SetImage(BaseBitmap *bmp, Bool copybmp, Bool secondstate=false)
Definition: c4d_string.h:39
#define CUSTOMGUI_BITMAPBUTTON
Bitmap button custom GUI ID.
Definition: customgui_bitmapbutton.h:25
#define BASEBITMAP_DATA_GUIPIXELRATIO
Float.
Definition: c4d_basebitmap.h:104
@ BFH_SCALEFIT
Scale fit. BFH_SCALE|BFH_FIT.
Definition: gui.h:316

Dirty

A BaseBitmap stores an incremental dirty state that is used in some scenarios to indicate that the BaseBitmap has changed.

// This example changes the given BaseBitmap and uses dirty flags
// to detect the change.
// check dirty state
UInt32 dirtyState = bitmap->GetDirty();
ApplicationOutput("Dirty State: " + String::UIntToString(dirtyState));
// edit bitmap and make dirty
bitmap->Clear(255, 255, 255);
bitmap->SetDirty();
// check dirty state
dirtyState = bitmap->GetDirty();
ApplicationOutput("Dirty State: " + String::UIntToString(dirtyState));
static String UIntToString(UInt32 v)
Definition: c4d_string.h:511
maxon::UInt32 UInt32
Definition: ge_sys_math.h:61
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210

Pixel Data

The internally stored bitmap data of a BaseBitmap can be accessed with:

Typically used pixel formats can be defined with:

  • PIX: 8-bit integer pixel type.
  • PIX_C: 8-bit integer pixel type.
  • PIX_W: 16-bit integer pixel type.
  • PIX_F: 32-bit float pixel type.

See also COLORBYTES for macros defining bytes per pixel and ::COLORMODE for a definition of the color mode.

// This example creates and fills a 32-bit RGBf BaseBitmap.
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// define bitmap dimensions and bit depth
const Int32 width = 1024;
const Int32 height = 1024;
const Int32 pixelBytes = COLORBYTES_RGBf; // RGBf format
const Int32 pixelBits = pixelBytes * 8;
// initialize the BaseBitmap with the given dimensions and bit depth
const IMAGERESULT res = bitmap->Init(width, height, pixelBits);
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// allocate memory for one line
const Int32 bufferSize = width * 3;
PIX_F* lineBuffer = NewMemClear(PIX_F, bufferSize) iferr_return;
// loop through all lines
for (Int32 y = 0; y <= height; ++y)
{
// shade of red based on the position
const Float32 red = Float32(y) / Float32(height);
Int32 offset = 0;
for (Int32 x = 0; x < width; ++x)
{
// shade of green based on the position
const Float32 green = Float32(x) / Float32(width);
// fill buffer
lineBuffer[offset] = red;
lineBuffer[offset + 1] = green;
lineBuffer[offset + 2] = 0.0;
offset += 3;
}
// write full line into the bitmap
bitmap->SetPixelCnt(0, y, width, (UChar*)lineBuffer, pixelBytes, COLORMODE::RGBf, PIXELCNT::NONE);
}
// delete line memory
DeleteMem(lineBuffer);
Float32 PIX_F
32-bit float pixel type.
Definition: ge_math.h:34
maxon::UChar UChar
Definition: ge_sys_math.h:57
maxon::Float32 Float32
Definition: ge_sys_math.h:68
#define COLORBYTES_RGBf
Floating point RGB.
Definition: c4d_basebitmap.h:93
@ RGBf
32-bit floating point RGB channels.

Alpha Channels

A BaseBitmap can contain up to four alpha channels. They are represented also with BaseBitmap instances:

// This example adds an alpha channel to the given BaseBitmap
// and stores the bitmap as a PNG file.
// fill image
bitmap->Clear(255, 255, 255);
// add alpha channel
BaseBitmap* alphaChannel = bitmap->AddChannel(true, false);
if (alphaChannel)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// set alpha value for each pixel
for (Int32 x = 0; x < width; ++x)
{
for (Int32 y = 0; y < height; ++y)
{
// create horizontal alpha gradient
const Float alphaValueFloat = (COLORTOINT_MULTIPLIER * Float(x)) / Float(width);
const Int32 alphaValueInt = Int32(alphaValueFloat);
bitmap->SetAlphaPixel(alphaChannel, x, y, alphaValueInt);
}
}
// save as PNG with alpha
Filename saveImageFile;
if (!saveImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::SAVE, "Save as PNG"_s))
return maxon::OK;
const IMAGERESULT saveRes = bitmap->Save(saveImageFile, FILTER_PNG, nullptr, SAVEBIT::ALPHA);
if (saveRes != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(saveImageFile, MAXONCONVERTMODE::NONE), "Could not save image file."_s);
@ SAVE
Save dialog.
#define FILTER_PNG
PNG.
Definition: ge_prepass.h:203
@ ALPHA
Save the alpha channel(s) in the file. (For filter plugins, do not save an alpha channel if this is n...

Convert

BaseBitmap is the base class of MultipassBitmap. If a pointer to a BaseBitmap is handed over one can check if it is actually a MultipassBitmap:

// This example lets the user select an image file that will be loaded.
// If the loaded image contains layers the layout count is printed.
Filename selectedImageFile;
// select image file
if (!selectedImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image"_s))
return maxon::OK;
// load image file
BaseBitmap* bitmap = nullptr;
const IMAGERESULT result = BaseBitmap::Init(bitmap, selectedImageFile);
// check success
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(selectedImageFile, MAXONCONVERTMODE::NONE), "Could not load image file."_s);
// check if it is a MultipassBitmap
if (bitmap->IsMultipassBitmap())
{
MultipassBitmap* const multipassBitmap = static_cast<MultipassBitmap*>(bitmap);
// get layer count
const Int32 layerCount = multipassBitmap->GetLayerCount();
ApplicationOutput("Layer Count: " + String::IntToString(layerCount));
}
else
{
// no MultipassBitmap, no layers
ApplicationOutput("No layers");
}
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)
Bool IsMultipassBitmap() const
Definition: c4d_basebitmap.h:975
Int32 GetLayerCount() const
Definition: c4d_basebitmap.h:1019
static String IntToString(Int32 v)
Definition: c4d_string.h:495
PyObject PyObject * result
Definition: abstract.h:43

A BaseBitmap also represents a maxon::ImageRef. This is obtained with:

Disc I/O

A BaseBitmap can read the content of an image file and save its content to an image file.

// This example let's the user select an image file.
// The loaded bitmap data is then saved in another image file format.
Filename selectedImageFile;
// select an image file
if (selectedImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image File"_s))
return maxon::OK;
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// load image file into the given BaseBitmap
if (bitmap->Init(selectedImageFile) != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(selectedImageFile, MAXONCONVERTMODE::NONE), "Could not load image file."_s);
// save bitmap data in different formats
// if the original file is no JPEG, save as JPEG
if (selectedImageFile.CheckSuffix("jpg"_s) == false)
{
Filename jpgFileName = selectedImageFile;
jpgFileName = GeFilterSetSuffix(jpgFileName, FILTER_JPG);
BaseContainer jpgSettings;
jpgSettings.SetInt32(JPGSAVER_QUALITY, 80);
if (bitmap->Save(jpgFileName, FILTER_JPG, &jpgSettings, SAVEBIT::NONE) != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, maxon::Url(jpgFileName.GetString()), "Could not save image file."_s);
}
// if the original file is no PNG, save as PNG
if (selectedImageFile.CheckSuffix("png"_s) == false)
{
Filename pngFileName = selectedImageFile;
pngFileName = GeFilterSetSuffix(pngFileName, FILTER_PNG);
if (bitmap->Save(pngFileName, FILTER_PNG, nullptr, SAVEBIT::NONE) != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(pngFileName, MAXONCONVERTMODE::NONE), "Could not save image file."_s);
}
Filename GeFilterSetSuffix(const Filename &name, Int32 id)
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:579
String GetString() const
Bool CheckSuffix(const maxon::String &str) const
Definition: url.h:942
#define FILTER_JPG
JPEG.
Definition: ge_prepass.h:190
#define JPGSAVER_QUALITY
Quality of JPEG images. A value between 0 (lowest) and 100 (highest).
Definition: ge_prepass.h:244
@ NONE
None.
Note
An alternative way of loading image files is to use SendPainterCommand() with PAINTER_LOADTEXTURE.

A BaseBitmap can also be stored in a HyperFile using:

Display

A BaseBitmap or MultipassBitmap can easily displayed in the Picture Viewer:

// This example opens a dialog to select an image file.
// The selected file is loaded into a BaseBitmap and displayed
// in the Picture Viewer window.
Filename selectedImageFile;
// select image file
if (!selectedImageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image"_s))
return maxon::OK;
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// load image file into the given BaseBitmap
if (bitmap->Init(selectedImageFile) != IMAGERESULT::OK)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(selectedImageFile, MAXONCONVERTMODE::NONE), "Could not load image file."_s);
// show BaseBitmap in the Picture Viewer
ShowBitmap(bitmap);

Further Reading