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:
- BaseBitmap::Alloc(): Creates a new BaseBitmap.
- BaseBitmap::Free(): Deletes the given BaseBitmap.
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.
Filename selectedImageFile;
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
NONE
Definition: asset_browser.h:1
LOAD
Load.
Definition: c4d_filterdata.h:1
OK
User has selected a font.
Definition: customgui_fontchooser.h:0
IMAGES
Image files.
Definition: ge_prepass.h:1
return OK
Definition: apibase.h:2740
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:69
Bool ShowBitmap(const Filename &fn)
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
const Int32 height = 1080;
Random randomGen;
{
for (
Int32 y = 0; y < height; ++y)
{
bitmap->SetPixel(
x, y, red, green, blue);
}
}
PyObject * x
Definition: bytesobject.h:38
Py_UCS4 * res
Definition: unicodeobject.h:1113
IMAGERESULT
Definition: ge_prepass.h:3947
static const Float COLORTOINT_MULTIPLIER
Constant to convert from vectors color components to integers.
Definition: c4d_tools.h:26
maxon::Int32 Int32
Definition: ge_sys_math.h:51
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.
AutoBitmap cubeIcon(5159);
BaseBitmap* const bitmap = cubeIcon;
if (bitmap == nullptr)
AutoBitmap localIcon("icon.tif"_s);
if (localIcon == nullptr)
Copy
The content of a BaseBitmap can be copied and with these functions:
- BaseBitmap::GetClone: Returns a clone of the BaseBitmap.
- BaseBitmap::GetClonePart: Returns a clone of the defined part of the BaseBitmap.
- BaseBitmap::CopyTo: Copies the image data into the given BaseBitmap.
- BaseBitmap::CopyPartTo: Copies the defined part of the image data into the given BaseBitmap.
const Int32 height = sourceBitmap->GetBh();
BaseBitmap* leftBitmap = sourceBitmap->GetClonePart(0, 0, leftHalfWidth, height);
if (leftBitmap == nullptr)
BaseBitmap::Free(leftBitmap);
const Int32 rightHalfWidth =
width - leftHalfWidth;
BaseBitmap* rightBitmap = sourceBitmap->GetClonePart(leftHalfWidth, 0, rightHalfWidth, height);
if (rightBitmap == nullptr)
BaseBitmap::Free(rightBitmap);
Read-Only Properties
The basic properties of a BaseBitmap are accessed with:
- BaseBitmap::GetBw(): Returns the width of the BaseBitmap.
- BaseBitmap::GetBh(): Returns the height of the BaseBitmap.
- BaseBitmap::GetBt(): Returns the image depth in bits per pixel.
- BaseBitmap::GetBpz(): Returns the number of bytes per line.
- BaseBitmap::GetColorMode(): Returns the color mode, see COLORMODE. Do not confuse with COLORBYTES.
- BaseBitmap::GetMemoryInfo(): Returns the size of the memory used by the BaseBitmap.
const COLORMODE colorMode = bitmap->GetColorMode();
const Int32 bitsPerPixel = bitmap->GetBt();
const Int32 bytesPerPixel = bitsPerPixel / 8;
const Int32 bufferSize = bitmap->GetBpz();
const Int32 height = bitmap->GetBh();
for (
Int32 y = 0; y <= height; ++y)
{
InvertLineRGB(lineBuffer,
width);
}
#define NewMemClear(T, cnt)
Definition: defaultallocator.h:216
COLORMODE
::Int32 Get/Set. The color mode: COLORMODE
Definition: ge_prepass.h:4
RGB
8-bit RGB channels.
Definition: ge_prepass.h:7
UChar PIX
8-bit integer pixel type.
Definition: ge_math.h:26
void DeleteMem(T *&p)
Definition: defaultallocator.h:269
#define iferr_return
Definition: resultbase.h:1531
The used color profile is managed with:
- BaseBitmap::GetColorProfile(): Returns the used color profile.
- BaseBitmap::SetColorProfile(): Sets the used color profile.
See also ColorProfile and ColorProfileConvert.
const BaseContainer& docData =
doc->GetDataInstanceRef();
if (linearWorkflow)
_bitmap->SetColorProfile(ColorProfile::GetDefaultLinearRGB());
else
_bitmap->SetColorProfile(ColorProfile::GetDefaultSRGB());
DrawBitmap(_bitmap, 0, 0,
width, height, 0, 0,
width, height, drawMode);
@ DOCUMENT_LINEARWORKFLOW
Definition: ddoc.h:64
@ BMP_APPLY_COLORPROFILE
Applies the color profile.
Definition: gui.h:176
maxon::Bool Bool
Definition: ge_sys_math.h:46
const char * doc
Definition: pyerrors.h:226
Functionality
Bitmap
The content of a BaseBitmap can be scaled into another BaseBitmap:
- BaseBitmap::ScaleIt(): Scales the image data and stores the result in the given BaseBitmap.
- BaseBitmap::ScaleBicubic(): Scales the image data using bicubic interpolation and stores the result in the given BaseBitmap.
- Warning
- MultipassBitmap overwrites these functions. The overwritten functions will scale the layers but not the alpha channels.
AutoAlloc<BaseBitmap> scaledBitmap;
if (scaledBitmap == nullptr)
const Int32 originalWidth = sourceBitmap->GetBw();
const Int32 originalHeight = sourceBitmap->GetBh();
const Int32 scaledWidth = originalWidth * scale;
const Int32 scaledHeight = originalHeight * scale;
const IMAGERESULT res = scaledBitmap->Init(scaledWidth, scaledHeight);
const Int32 defaultBrightness = 256;
sourceBitmap->ScaleIt(scaledBitmap, defaultBrightness, true, false);
One can perform basic drawing operations with these functions:
- BaseBitmap::Clear(): Fills the BaseBitmap with the given color.
- BaseBitmap::SetPen(): Sets the color used with the following operations.
- BaseBitmap::Line(): Draws a line.
- BaseBitmap::Arc(): Draws an arc.
- Note
- For more advanced drawing operations use a GeClipMap, see GeClipMap Manual.
bitmap->Clear(255, 255, 255);
bitmap->SetPen(0, 0, 0);
bitmap->Line(100, 100, 300, 100);
bitmap->Line(100, 200, 300, 200);
bitmap->Arc(300, 150, 50.0, quarterCircle, -quarterCircle, 20);
bitmap->Arc(100, 150, 50.0, quarterCircle, threeQuarterCircle, 20);
Float32 DegToRad(Float32 r)
Definition: apibasemath.h:256
maxon::Float Float
Definition: ge_sys_math.h:57
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.
- BaseBitmap::GetData(): Returns the data for the given ID.
- BaseBitmap::SetData(): Sets the data for the given ID.
The settings are:
BitmapButtonCustomGui* const bitmapButtonGUI = static_cast<BitmapButtonCustomGui*>(customGUI);
if (bitmapButtonGUI)
{
AutoAlloc<BaseBitmap> bitmap;
if (bitmap)
{
const Float pixelRatio = GetPixelRatio();
if (pixelRatio == 1.0)
else
const String fullFileName = GetFullFilename(
filename);
{
bitmapButtonGUI->SetImage(bitmap, true, false);
}
}
}
PyCompilerFlags const char * filename
Definition: ast.h:15
#define BASEBITMAP_DATA_GUIPIXELRATIO
::Float.
Definition: c4d_basebitmap.h:103
@ 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.
- BaseBitmap::GetDirty(): Returns the incremental dirty state.
- BaseBitmap::SetDirty(): Increments the dirty state.
UInt32 dirtyState = bitmap->GetDirty();
bitmap->Clear(255, 255, 255);
bitmap->SetDirty();
dirtyState = bitmap->GetDirty();
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
maxon::UInt32 UInt32
Definition: ge_sys_math.h:52
Pixel Data
The internally stored bitmap data of a BaseBitmap can be accessed with:
- BaseBitmap::GetPixel(): Gets the RGB values for the given coordinates.
- BaseBitmap::SetPixel(): Sets the RGB values for the given coordinates.
- BaseBitmap::GetPixelCnt(): Copies the data of multiple pixel in a row into the given buffer.
- BaseBitmap::SetPixelCnt(): Copies the data of multiple pixels in a row from the given buffer into the BaseBitmap.
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.
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
const Int32 height = 1024;
const Int32 pixelBits = pixelBytes * 8;
for (
Int32 y = 0; y <= height; ++y)
{
{
lineBuffer[offset] = red;
lineBuffer[offset + 1] = green;
lineBuffer[offset + 2] = 0.0;
offset += 3;
}
}
RGBf
32-bit floating point RGB channels.
Definition: ge_prepass.h:30
#define COLORBYTES_RGBf
Floating point RGB.
Definition: c4d_basebitmap.h:92
maxon::UChar UChar
Definition: ge_sys_math.h:48
maxon::Float32 Float32
Definition: ge_sys_math.h:59
Float32 PIX_F
32-bit float pixel type.
Definition: ge_math.h:29
Alpha Channels
A BaseBitmap can contain up to four alpha channels. They are represented also with BaseBitmap instances:
- BaseBitmap::AddChannel(): Adds a new alpha channel.
- BaseBitmap::RemoveChannel(): Removes the given alpha channel.
- BaseBitmap::GetInternalChannel(): Returns the internal alpha channel.
- BaseBitmap::GetChannelCount(): Returns the number of alpha channels.
- BaseBitmap::GetChannelNum(): Returns the alpha channel with the given index.
- BaseBitmap::GetAlphaPixel(): Gets the alpha value from the given alpha channel and the given coordinates.
- BaseBitmap::SetAlphaPixel(): Sets the alpha value for the given alpha channel and the given coordinates.
bitmap->Clear(255, 255, 255);
BaseBitmap* alphaChannel = bitmap->AddChannel(true, false);
if (!alphaChannel)
{
for (
Int32 y = 0; y < height; ++y)
{
const Int32 alphaValueInt =
Int32(alphaValueFloat);
bitmap->SetAlphaPixel(alphaChannel,
x, y, alphaValueInt);
}
}
Filename saveImageFile;
SAVE
::Bool Get/Set. Determines if the layer is saved with the image or not if SAVEBIT::USESELECTEDLAYERS ...
Definition: ge_prepass.h:1
#define FILTER_PNG
PNG.
Definition: ge_prepass.h:202
ALPHA
Definition: lib_birender.h:3
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:
- BaseBitmap::IsMultipassBitmap(): Returns true if the BaseBitmap is a MultipassBitmap.
Filename selectedImageFile;
BaseBitmap* bitmap = nullptr;
if (bitmap->IsMultipassBitmap())
{
MultipassBitmap* const multipassBitmap = static_cast<MultipassBitmap*>(bitmap);
const Int32 layerCount = multipassBitmap->GetLayerCount();
}
else
{
}
BaseBitmap::Free(bitmap);
PyObject PyObject * result
Definition: abstract.h:43
A BaseBitmap also represents a maxon::ImageRef. This is obtained with:
- BaseBitmap::GetImageRef(): Returns the internally stored maxon::ImageRef. See Images Manual.
Disc I/O
A BaseBitmap can read the content of an image file and save its content to an image file.
- BaseBitmap::Init(): Loads the content of the given image file.
- BaseBitmap::Save(): Saves the bitmap data to the given image file.
Filename selectedImageFile;
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
if (selectedImageFile.CheckSuffix("jpg"_s) == false)
{
Filename jpgFileName = selectedImageFile;
BaseContainer jpgSettings;
}
if (selectedImageFile.CheckSuffix("png"_s) == false)
{
Filename pngFileName = selectedImageFile;
}
#define FILTER_JPG
JPEG.
Definition: ge_prepass.h:189
#define JPGSAVER_QUALITY
Quality of JPEG images. A value between 0 (lowest) and 100 (highest).
Definition: ge_prepass.h:243
Filename GeFilterSetSuffix(const Filename &name, Int32 id)
- 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:
- HyperFile::ReadImage(): Gets the BaseBitma from the HyperFile.
- HyperFile::WriteImage(): Writes the BaseBitmpa into the HyperFile.
Display
A BaseBitmap or MultipassBitmap can easily displayed in the Picture Viewer:
- ShowBitmap(): Opens the Picture Viewer to display a copy of the given BaseBitmap.
Filename selectedImageFile;
AutoAlloc<BaseBitmap> bitmap;
if (bitmap == nullptr)
Further Reading