Represents a pixel buffer used for drawing, image transfer and display backing.

The Bitmap class describes a rectangular block of pixel data together with its dimensions, colour format, palette, clipping region and drawing state. Bitmaps are used directly by Display and Image objects and provide the low-level pixel storage behind much of Kōtuku's 2D graphics pipeline.

To create a bitmap, set Width and Height before initialisation. The pixel format can be selected explicitly with BitsPerPixel, BytesPerPixel, AmtColours and Type, or left for Query() and Init() to derive from the current display environment. MemType controls whether the bitmap uses regular CPU-accessible memory or a platform-specific video or texture resource where supported.

Direct CPU access is reliable for regular data bitmaps. Bitmaps backed by video or texture resources may require Lock() before reading or writing Data, and Unlock() after direct access is complete. Code that uses the drawing methods exposed by this class does not normally need to manage locking itself.

Bitmap methods are intentionally low-level and operate on immediate pixel data. Use the Vector module when retained scene graphs, paths, gradients, filters or higher-level drawing composition are required. Use Image when decoding or encoding image formats is the main concern.

Raw image bytes can be read and written with Read() and Write(). SaveImage() writes the clipped bitmap image as PCX data to a destination object that supports writing.

Structure

The Bitmap class consists of the following fields:

Access

Name

Type

Comment

AmtColours INT The maximum number of colours represented by the bitmap format.

For indexed bitmaps, this is the size of the usable palette. For direct-colour bitmaps, it reflects the colour range implied by BitsPerPixel and the selected ColourFormat.

BitsPerPixel INT The number of bits used to represent each pixel.

This includes all bits used by the pixel format, including alpha bits where present.

Bkgd RGB8 Background colour in RGB format.

The background colour is used by operations that need a default fill colour, such as Clear(), Draw() and some resize paths. The default background colour is black.

The BkgdIndex will be updated as a result of setting this field.

BkgdIndex INT Background colour as a packed pixel value or palette index.

Use Bkgd for most updates. Set BkgdIndex directly only when the caller has already calculated the target bitmap's native pixel value or palette index.

BlendMode BLM Defines the blending algorithm to use when rendering transparent pixels.

The default value is BLM::AUTO, which selects the preferred blending path for the current bitmap and graphics backend.

Name	Description
BLM::AUTO	Use the most suitable of the available algorithms.
BLM::GAMMA	Use gamma correct blending. This algorithm is slow but produces a high quality result.
BLM::LINEAR	Use linear blending. Applicable if the bitmap is in linear colour space.
BLM::NONE	Never blend transparent pixels, just copy as-is.
BLM::SRGB	Use sRGB linear blending. This algorithm is extremely efficient but produces poor quality results.

ByteWidth INT The width of the bitmap, in bytes.

ByteWidth is calculated from Width, Type and BytesPerPixel. It describes the meaningful pixel bytes in a row and does not include alignment padding.

The formulas used to calculate the value of this field are:

Planar      = Width/8
Chunky/8    = Width
Chunky/15   = Width * 2
Chunky/16   = Width * 2
Chunky/24   = Width * 3
Chunky/32   = Width * 4

To learn the total byte-width per line including any additional padded bytes, refer to the LineWidth field.

BytesPerPixel INT The number of bytes per pixel.

This field reflects the byte count used by one chunky pixel. Values normally range from 1 to 4. For planar bitmaps, BitsPerPixel is the more useful format indicator.

Clip struct ClipRectangle Defines the bitmap's clipping region.

Clip is a shorthand reference for ClipLeft, ClipTop, ClipRight and ClipBottom, returning all four values as a single ClipRectangle structure.

ClipBottom INT The exclusive bottom edge of the bitmap clipping region.

The default clipping region matches the bitmap dimensions. Drawing operations are limited to the active clipping region.

ClipLeft INT The left-most edge of a bitmap's clipping region.

The default clipping region matches the bitmap dimensions. Drawing operations are limited to the active clipping region.

ClipRight INT The exclusive right edge of the bitmap clipping region.

The default clipping region matches the bitmap dimensions. Drawing operations are limited to the active clipping region.

ClipTop INT The top-most edge of a bitmap's clipping region.

The default clipping region matches the bitmap dimensions. Drawing operations are limited to the active clipping region.

ColourFormat struct ColourFormat * Describes the colour format used to construct each bitmap pixel.

ColourFormat points to the structure that describes how packed pixel values map to red, green, blue and alpha channels. It is relevant for direct-colour bitmaps, normally those with two or more bytes per pixel.

Field	Type	Description
RedShift	UINT8	Right shift value for red (15/16 bit formats only)
GreenShift	UINT8	Right shift value for green
BlueShift	UINT8	Right shift value for blue
AlphaShift	UINT8	Right shift value for alpha
RedMask	UINT8	Unshifted mask value for red (ranges from 0x00 to 0xff)
GreenMask	UINT8	Unshifted mask value for green
BlueMask	UINT8	Unshifted mask value for blue
AlphaMask	UINT8	Unshifted mask value for alpha
RedPos	UINT8	Left shift/positional value for red
GreenPos	UINT8	Left shift/positional value for green
BluePos	UINT8	Left shift/positional value for blue
AlphaPos	UINT8	Left shift/positional value for alpha
BitsPerPixel	UINT8	Number of bits per pixel for this format.

The following C++ helper methods can be called on a bitmap to build packed colour values from channel components:

packPixel(Red, Green, Blue)
packPixel(Red, Green, Blue, Alpha)
packAlpha(Alpha)
packPixelRGB(RGB8 &RGB)
packPixelRGBA(RGB8 &RGB)

The following C macros are optimised forms for 24 and 32-bit bitmaps:

PackPixelWB(Red, Green, Blue)
PackPixelWBA(Red, Green, Blue, Alpha)

The following C++ helper methods unpack individual colour components from a packed colour value:

unpackRed(Colour)
unpackGreen(Colour)
unpackBlue(Colour)
unpackAlpha(Colour)

ColourSpace CS Defines the colour space for RGB values.

Name	Description
CS::CIE_LAB	Cartesian Lab* colour space defined by CIE 15.
CS::CIE_LCH	Polar L*CHab colour space defined by CIE 15.
CS::LINEAR_RGB	Linear RGB is used to improve colour balance in blending operations.
CS::SRGB	The default colour-space is sRGB.

Data UINT8[] Provides direct access to the bitmap's data area.

Data points to the first byte of the bitmap's pixel buffer when CPU-visible memory is available. Caller-supplied memory can be used for data-backed bitmaps, but most callers should let Init() allocate the correctly sized buffer.

For video or texture-backed bitmaps, Data may be unavailable until Lock() succeeds.

DrawUCPixel FUNCTION * Points to a C function that draws pixels to the bitmap using colour indexes.

DrawUCPixel points to the active low-level pixel writer for packed colour or palette-index values. It is intended for C callers that need direct pixel access. No clipping or bounds checks are performed.

The prototype of the DrawUCPixel function is Function(*Bitmap, LONG X, LONG Y, UINT Colour).

The new pixel value is supplied in the Colour parameter.

DrawUCRIndex FUNCTION * Points to a C function that draws pixels to the bitmap in RGB format.

DrawUCRIndex points to the active low-level RGB pixel writer for a caller-supplied address inside Data. It is intended for C callers that need direct pixel access. No clipping, bounds or address validation is performed.

The prototype of the DrawUCRIndex function is Function(*Bitmap, BYTE *Data, RGB8 *RGB).

The Data parameter must point to a location within the Bitmap's graphical address space. The new pixel value must be defined in the RGB parameter.

There is no colour-index equivalent because callers can write indexed pixel bytes directly through Data.

DrawUCRPixel FUNCTION * Points to a C function that draws pixels to the bitmap in RGB format.

DrawUCRPixel points to the active low-level RGB pixel writer for X, Y coordinates. It is intended for C callers that need direct pixel access. No clipping or bounds checks are performed.

The prototype of the DrawUCRPixel function is Function(*Bitmap, LONG X, LONG Y, RGB8 *RGB).

The new pixel value must be defined in the RGB parameter.

Flags BMF Optional flags.

Name	Description
BMF::ACCELERATED_2D	2D video acceleration is available.
BMF::ACCELERATED_3D	3D video acceleration is available.
BMF::ALPHA_CHANNEL	For 32-bit images, indicates that an alpha channel is present.
BMF::BLANK_PALETTE	Forces a blank/black palette on initialisation.
BMF::CLEAR	Clear graphics on initialisation and when resizing.
BMF::COMPRESSED	The bitmap data is compressed.
BMF::FIXED_DEPTH	Prevent changing of bitmap depth after initialisation (e.g. via `Resize()`).
BMF::INVERSE_ALPHA	Indicates reverse alpha blending, higher values are transparent.
BMF::MASK	Declare the Bitmap as a 1 or 8 bit mask. Must be set in conjunction with the Bitmap⇒BitsPerPixel field on initialisation.
BMF::NEVER_SHRINK	Ignore resize requests that would shrink the size of the bitmap.
BMF::NO_DATA	Do not allocate memory in the Data field on initialisation.
BMF::PREMUL	The RGB values are premultiplied (32-bit only).
BMF::QUERIED	Automatically set after a `Query()` on the bitmap.
BMF::TRANSPARENT	Indicates that the bitmap utilises a transparent colour. This is automatically set if the Bitmap⇒TransIndex or Bitmap⇒TransColour is defined, and support exists in functions such as CopyArea().
BMF::USER	This user flag can be used to tag bitmaps with special meaning. Not used internally.

Handle APTR Platform-dependent field for referencing video memory.

Height INT The height of the bitmap, in pixels.

LineWidth INT The length of each bitmap line in bytes, including alignment.

LineWidth includes any row padding required by the active bitmap type or platform backend. Use ByteWidth for the number of meaningful pixel bytes in a row.

MemType BMT Defines the memory type used to host a bitmap's data area.

MemType controls the kind of backing storage requested during initialisation. The available values are BMT::DATA, BMT::VIDEO and BMT::TEXTURE.

Video or texture-backed bitmaps can be faster for some drawing paths, but direct CPU access is platform dependent. Use Lock() before reading or writing Data directly when the bitmap is not a regular data bitmap.

Name	Description
BMT::DATA	The default type, indicates a standard memory allocation from system RAM.
BMT::TEXTURE	Identifies non-displayable video memory, e.g. texture graphics.
BMT::VIDEO	Identifies video memory, such as the frame buffer.

Opacity INT Determines the translucency setting to use in drawing operations.

Opacity is an 8-bit alpha multiplier used by drawing operations that support translucent bitmap copies. A value of 255 is fully opaque and disables additional translucency. Lower values make copied pixels more transparent.

This value is separate from any per-pixel alpha channel stored in the bitmap.

Palette struct RGBPalette * Points to a bitmap's colour palette.

Palette points to the bitmap's colour table. Indexed bitmaps use this table to map pixel values to RGB colours, and some conversion paths use it even when the bitmap itself is direct-colour.

The structure starts with the palette header and colour count, followed by colour entries in index order. There is no terminating entry.

The following example is for a 32 colour palette:

RGBPalette Palette = {
  ID_PALETTE, VER_PALETTE, 32,
  {{ 0x00,0x00,0x00 }, { 0x10,0x10,0x10 }, { 0x17,0x17,0x17 }, { 0x20,0x20,0x20 },
   { 0x27,0x27,0x27 }, { 0x30,0x30,0x30 }, { 0x37,0x37,0x37 }, { 0x40,0x40,0x40 },
   { 0x47,0x47,0x47 }, { 0x50,0x50,0x50 }, { 0x57,0x57,0x57 }, { 0x60,0x60,0x60 },
   { 0x67,0x67,0x67 }, { 0x70,0x70,0x70 }, { 0x77,0x77,0x77 }, { 0x80,0x80,0x80 },
   { 0x87,0x87,0x87 }, { 0x90,0x90,0x90 }, { 0x97,0x97,0x97 }, { 0xa0,0xa0,0xa0 },
   { 0xa7,0xa7,0xa7 }, { 0xb0,0xb0,0xb0 }, { 0xb7,0xb7,0xb7 }, { 0xc0,0xc0,0xc0 },
   { 0xc7,0xc7,0xc7 }, { 0xd0,0xd0,0xd0 }, { 0xd7,0xd7,0xd7 }, { 0xe0,0xe0,0xe0 },
   { 0xe0,0xe0,0xe0 }, { 0xf0,0xf0,0xf0 }, { 0xf7,0xf7,0xf7 }, { 0xff,0xff,0xff }
   }
};

Palettes are created for all bitmap types, including RGB bitmaps above 8-bit colour, because several drawing functions use a palette table when converting between bitmap formats.

Parent objects such as Display may need to be updated separately before palette changes are reflected by the visible display.

PlaneMod INT The differential between each bitmap plane.

PlaneMod specifies the byte distance between each bitplane in planar bitmaps. For chunky bitmaps, it reflects the total size of the bitmap buffer.

Position INT The current read/write data position.

Position is the byte offset used by Read() and Write(). Use Seek() to change it.

ReadUCPixel FUNCTION * Points to a C function that reads pixels from the bitmap in colour index format.

ReadUCPixel points to the active low-level pixel reader for packed colour or palette-index values. It is intended for C callers that need direct pixel access. No clipping or bounds checks are performed.

The prototype of the ReadUCPixel function is Function(*Bitmap, LONG X, LONG Y, LONG *Index).

The pixel value will be returned in the Index parameter.

ReadUCRIndex FUNCTION * Points to a C function that reads pixels from the bitmap in RGB format.

ReadUCRIndex points to the active low-level RGB pixel reader for a caller-supplied address inside Data. It is intended for C callers that need direct pixel access. No clipping, bounds or address validation is performed.

The prototype of the ReadUCRIndex function is Function(*Bitmap, BYTE *Data, RGB8 *RGB).

The Data parameter must point to a location within the Bitmap's graphical address space. The pixel value will be returned in the RGB parameter.

There is no colour-index equivalent because callers can read indexed pixel bytes directly through Data.

ReadUCRPixel FUNCTION * Points to a C function that reads pixels from the bitmap in RGB format.

ReadUCRPixel points to the active low-level RGB pixel reader for X, Y coordinates. It is intended for C callers that need direct pixel access. No clipping or bounds checks are performed.

The prototype of the ReadUCRPixel function is Function(*Bitmap, LONG X, LONG Y, RGB8 *RGB).

The pixel value is returned in the RGB parameter. Because this function expands the pixel value to RGB components, ReadUCPixel or ReadUCRIndex may be faster when RGB decomposition is not required.

Size INT The total size of the bitmap, in bytes.

TransColour RGB8 The transparent colour of the bitmap, in RGB format.

Pixels matching this colour are skipped by drawing operations that honour colour-key transparency.

Do not use colour-key transparency on bitmaps that use alpha transparency.

TransIndex INT The transparent colour of the bitmap, represented as an index.

TransIndex stores the transparent colour as a packed pixel value or palette index. Pixels matching this value are skipped by drawing operations that honour colour-key transparency.

Use TransColour for most updates. Set TransIndex directly only when the caller has already calculated the target bitmap's native pixel value or palette index. Do not use colour-key transparency on bitmaps that use alpha transparency.

Type BMP Defines the data type of the bitmap.

Type defines the bitmap layout, either BMP::PLANAR for planar bitmaps or BMP::CHUNKY for interleaved pixel data. Chunky is the default.

Name	Description
BMP::CHUNKY	Chunky pixel mode (default).
BMP::PLANAR	Planar pixel mode separates pixel bits across multiple planes. Commonly used for single bit bitmap masks.

Width INT The width of the bitmap, in pixels.

Width must be set before Query() or Init() can derive the bitmap layout.

Actions

The following actions are currently supported:

Clear Clears the bitmap image to BkgdIndex.

ERR acClear(*Object)

Clear fills the full bitmap with the current background colour. The colour used by the operation is BkgdIndex, which is derived from Bkgd when the background colour is set through the RGB field.

To clear a bitmap to a different colour without changing the background fields, call DrawRectangle() with BAF::FILL. For alpha-capable bitmaps, setting BkgdIndex to zero is an efficient way to clear the image to transparent black.

Error Codes

Okay	Operation successful.
LockFailed	Failed to lock a required resource

CopyData Copies bitmap image data to other bitmaps with colour remapping enabled.

ERR acCopyData(*Object, OBJECTID Dest)

Parameter	Description
Dest	The unique ID of the destination object.

CopyData copies this bitmap into another initialised Bitmap object. Other destination classes are not supported.

The copy is clipped to the destination dimensions. If the destination is wider or taller than the source, the exposed area is cleared to the destination bitmap's background colour.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function
NullArgs	Function call missing argument value(s)

Draw Clears the bitmap image to BkgdIndex.

ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)

Parameter	Description
X	The X position of the region to be drawn.
Y	The Y position of the region to be drawn.
Width	The width of the region to be drawn.
Height	The height of the region to be drawn.

Draw fills the full bitmap with the current background colour. It is equivalent to drawing a filled rectangle over the entire bitmap with BkgdIndex.

Flush Flushes pending graphics operations and returns when the accelerator is idle.

ERR acFlush(*Object)

Flush synchronises pending graphics operations with the active graphics backend. Synchronisation is required before direct CPU access to accelerator-managed bitmap memory.

Clients do not need to call this function if solely using the graphics methods provided in the Bitmap class.

Init Initialises a bitmap.

ERR InitObject(*Object)

Init prepares a queried bitmap for use. It validates the calculated bitmap state, allocates Data when required, configures platform-specific backing resources and selects the pixel access routines used by drawing operations.

If Data has already been supplied, Init uses the caller-provided memory. Otherwise allocation is controlled by MemType and Flags. Width and Height must be set before this action is called.

Error Codes

Okay	Operation successful.
NoSupport	Operation not supported
Query	Attempt to Query() failed
FieldNotSet	A required field value is undefined
AllocMemory	Failed to create a new memory block
SystemCall	A call to the host system has failed

Lock Locks the bitmap surface for direct read/write access.

ERR acLock(*Object)

Lock makes bitmap memory available through Data for direct CPU access. It is mainly required for bitmaps backed by a video or platform drawable resource; data-backed bitmaps are already CPU-accessible.

Call Unlock() when direct access is complete so platform resources can be released or synchronised.

Error Codes

Okay	Operation successful.
NoData	No data is available for use
LockFailed	Failed to lock a required resource
NoSupport	Operation not supported
FieldNotSet	A required field value is undefined
AllocMemory	Failed to create a new memory block
SystemCall	A call to the host system has failed
CreateResource	Failed to create a new resource

Query Populates a bitmap with pre-initialised/default values prior to initialisation.

ERR acQuery(*Object)

Query calculates the bitmap's derived fields without allocating image memory. It resolves values such as Type, BytesPerPixel, BitsPerPixel, AmtColours, ByteWidth, LineWidth, PlaneMod and Size from the fields already set by the caller.

At minimum, Width and Height must be positive. If format fields are incomplete, Query derives a compatible format where possible; for example, BytesPerPixel set to 2 implies a 16-bit bitmap.

Error Codes

Okay	Operation successful.
InvalidDimension	A dimension specification is invalid

Read Reads raw image data from a bitmap object.

ERR acRead(*Object, std::span<int8_t> Buffer, INT *Result)

Parameter	Description
Buffer	A mutable buffer that will receive the data.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

Read copies bytes from Data into the supplied output buffer, starting at Position. Position is advanced by the number of bytes copied and the result count is returned in the action arguments.

If the requested length would pass the end of the bitmap data, Read truncates the transfer to the remaining byte count.

Error Codes

Okay	Operation successful.
NoData	No data is available for use
OutOfRange	A value is outside of the valid range
NullArgs	Function call missing argument value(s)

Resize Resizes a bitmap object's dimensions.

ERR acResize(*Object, DOUBLE Width, DOUBLE Height, DOUBLE Depth)

Parameter	Description
Width	The new width of the object.
Height	The new height of the object.
Depth	The new depth of the object.

Resize changes Width, Height and, unless BMF::FIXED_DEPTH is set, BitsPerPixel. Existing image content is not preserved.

If BMF::NEVER_SHRINK is set, requested dimensions smaller than the current bitmap are raised to the current size. If BMF::CLEAR is set, the resized bitmap is cleared to Bkgd.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function
NoSupport	Operation not supported
UndefinedField	A required field value is undefined
AllocMemory	Failed to create a new memory block
NullArgs	Function call missing argument value(s)
Notified	Unknown error code.

SaveImage Saves the bitmap image to a writable object in PCX format.

ERR acSaveImage(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded image data.
ClassID	The Image class to use for encoding the image data.

SaveImage writes the current clipping region to Dest as PCX image data. Paletted bitmaps are written with a palette; true-colour bitmaps are written as three colour planes. If ColourSpace is CS::LINEAR_RGB, RGB values are converted to sRGB while the image is written.

Errors returned by the destination object's Write action are propagated to the caller.

Error Codes

Okay	Operation successful.
NoSupport	The bitmap surface cannot be read by the CPU.
AllocMemory	The read buffer for a host drawable could not be allocated.
BufferOverflow	A buffer overflow has occurred
NullArgs	Function call missing argument value(s)

Seek Changes the current byte position for read/write operations.

ERR acSeek(*Object, DOUBLE Offset, INT Position)

Parameter	Description
Offset	The desired offset to seek to, relative to the Position parameter.
Position	The position that defines the starting point for Offset.

Seek sets Position from the supplied byte offset and origin. Positions before the start of the bitmap are clamped to zero, and positions beyond Size are clamped to Size.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function
NullArgs	Function call missing argument value(s)

Unlock Unlocks the bitmap surface once direct access is no longer required.

ERR acUnlock(*Object)

Unlock releases or synchronises any platform resources held for direct CPU access after Lock().

Error Codes

Okay	Operation successful.

Write Writes raw image data to a bitmap object.

ERR acWrite(*Object, std::span<const int8_t> Buffer, INT *Result)

Parameter	Description
Buffer	A buffer containing the data that will be written to the object.
Result	This parameter with be updated with the total number of bytes written from the Buffer.

Write copies bytes from the supplied input buffer into Data, starting at Position. Position is advanced by the number of bytes written and the result count is returned in the action arguments.

The write must fit within the bitmap's allocated Size. Use Seek() to change the target position before writing.

Error Codes

Okay	Operation successful.
NoData	No data is available for use
OutOfSpace	Out of space. There is no available room to complete the request
NullArgs	Function call missing argument value(s)

Methods

The following methods are currently supported:

ConvertToLinear Converts a bitmap's colour space to linear RGB.

ERR bmp::ConvertToLinear(OBJECTPTR Object)

ConvertToLinear() converts the bitmap's clipped region from sRGB to linear RGB. If BMF::ALPHA_CHANNEL is set, pixels with an alpha value of zero are left unchanged.

ColourSpace is set to CS::LINEAR_RGB on completion. The method returns ERR::NothingDone if the bitmap is already marked as linear RGB.

This method currently requires a 32-bit bitmap.

Error Codes

Okay	Operation successful.
NothingDone	The Bitmap's content is already in linear RGB format.
InvalidDimension	The clipping region is invalid.
InvalidState	The Bitmap is not in the expected state.

ConvertToRGB Converts a bitmap's colour space to standard RGB.

ERR bmp::ConvertToRGB(OBJECTPTR Object)

ConvertToRGB() converts the bitmap's clipped region from linear RGB to sRGB. If BMF::ALPHA_CHANNEL is set, pixels with an alpha value of zero are left unchanged.

ColourSpace is set to CS::SRGB on completion. The method returns ERR::NothingDone if the bitmap is already marked as sRGB.

This method currently requires a 32-bit bitmap.

Error Codes

Okay	Operation successful.
NothingDone	The bitmap's content is already in sRGB format.
InvalidDimension	The clipping region is invalid.
InvalidState	The bitmap is not in the expected state.

CopyArea Copies a rectangular area from one bitmap to another.

ERR bmp::CopyArea(OBJECTPTR Object, objBitmap * DestBitmap, BAF Flags, INT X, INT Y, INT Width, INT Height, INT XDest, INT YDest)

Parameter	Description
DestBitmap	The target bitmap.
Flags	Optional flags.
X	The horizontal position of the area to be copied.
Y	The vertical position of the area to be copied.
Width	The width of the area.
Height	The height of the area.
XDest	The horizontal position to copy the area to.
YDest	The vertical position to copy the area to.

CopyArea() copies a rectangular region from this bitmap to DestBitmap. The source rectangle starts at X, Y and has the supplied Width and Height; the destination position is XDest, YDest.

The operation is implemented by CopyArea() and supports the same BAF options.

Error Codes

Okay	Operation successful.
Mismatch	The target bitmap is not a close enough match to the source bitmap in order to perform the operation.
NullArgs	Function call missing argument value(s)

Demultiply Reverses the conversion process performed by Premultiply().

ERR bmp::Demultiply(OBJECTPTR Object)

Demultiply() restores straight RGB channel values after Premultiply() has converted them to premultiplied alpha. The method returns ERR::NothingDone if BMF::PREMUL is not set in Flags.

This method operates only on 32-bit bitmaps that have an alpha channel, and it processes only the current clipping region.

Error Codes

Okay	Operation successful.
NothingDone	The content is already normalised.
AllocMemory	Failed to create a new memory block
InvalidDimension	The clipping region is invalid.
InvalidState	The Bitmap is not in the expected state (32-bit with an alpha channel).

DrawRectangle Draws rectangles, both filled and unfilled.

ERR bmp::DrawRectangle(OBJECTPTR Object, INT X, INT Y, INT Width, INT Height, UINT Colour, BAF Flags)

Parameter	Description
X	The left-most coordinate of the rectangle.
Y	The top-most coordinate of the rectangle.
Width	The width of the rectangle.
Height	The height of the rectangle.
Colour	The colour index to use for the rectangle.
Flags	Supports `FILL` and `BLEND`.

This method draws both filled and unfilled rectangles. The rectangle is drawn to the target bitmap at position (X, Y) with dimensions determined by the specified Width and Height. If the Flags parameter sets the FILL flag then the rectangle will be filled, otherwise the rectangle's outline will be drawn. The colour of the rectangle is determined by the pixel value in the Colour parameter.

The draw operation is clipped to the bitmap's current clipping region.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

GetColour Converts Red, Green, Blue components into a single colour value.

ERR bmp::GetColour(OBJECTPTR Object, INT Red, INT Green, INT Blue, INT Alpha, UINT * Colour)

Parameter	Description
Red	Red component from 0 - 255.
Green	Green component from 0 - 255.
Blue	Blue component value from 0 - 255.
Alpha	Alpha component value from 0 - 255.
Colour	The resulting colour value will be returned here.

The GetColour() method is used to convert Red, Green, Blue and Alpha colour components into a single colour index that can be used for directly writing colours to the bitmap. The result is returned in the Colour parameter.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

Premultiply Premultiplies RGB channel values by the alpha channel.

ERR bmp::Premultiply(OBJECTPTR Object)

Premultiply() converts RGB values in the current clipping region to premultiplied-alpha form. The formula applied to each colour channel is (Colour * Alpha + 0xff)>>8. The alpha channel is not changed.

This method operates only on 32-bit bitmaps that have an alpha channel. If the bitmap is already marked as premultiplied, the method returns ERR::NothingDone.

The process can be reversed with a call to Demultiply().

Error Codes

Okay	Operation successful.
NothingDone	The content is already premultiplied.
InvalidDimension	The clipping region is invalid.
InvalidState	The Bitmap is not in the expected state (32-bit with an alpha channel)

SetClipRegion Sets a clipping region for a bitmap object.

ERR bmp::SetClipRegion(OBJECTPTR Object, INT Left, INT Top, INT Right, INT Bottom)

Parameter	Description
Left	The horizontal start of the clip region.
Top	The vertical start of the clip region.
Right	The exclusive right edge of the clip region.
Bottom	The exclusive bottom edge of the clip region.

SetClipRegion() updates the bitmap's clipping region. Drawing operations are restricted to the combined region.

This method is implemented by SetClipRegion().

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

BAF Type

Instructions for basic graphics operations.

Name	Description
BAF::BLEND	Enable alpha blending to the destination if the source supports an alpha channel.
BAF::COPY	Special CopyArea() option that avoids blending when the destination pixel is empty.
BAF::DITHER	Perform dithering if the colour formats differ between the source and destination.
BAF::FILL	For primitive operations such as DrawRectangle(), this will fill the shape with a solid colour or texture.
BAF::LINEAR	Use linear interpolation to improve the quality of alpha blending.

BLM Type

Defines the blending algorithm to use when transparent pixels are rendered to the bitmap.

Name	Description
BLM::AUTO	Use the most suitable of the available algorithms.
BLM::GAMMA	Use gamma correct blending. This algorithm is slow but produces a high quality result.
BLM::LINEAR	Use linear blending. Applicable if the bitmap is in linear colour space.
BLM::NONE	Never blend transparent pixels, just copy as-is.
BLM::SRGB	Use sRGB linear blending. This algorithm is extremely efficient but produces poor quality results.

BMF Type

Bitmap flags

Name	Description
BMF::ACCELERATED_2D	2D video acceleration is available.
BMF::ACCELERATED_3D	3D video acceleration is available.
BMF::ALPHA_CHANNEL	For 32-bit images, indicates that an alpha channel is present.
BMF::BLANK_PALETTE	Forces a blank/black palette on initialisation.
BMF::CLEAR	Clear graphics on initialisation and when resizing.
BMF::COMPRESSED	The bitmap data is compressed.
BMF::FIXED_DEPTH	Prevent changing of bitmap depth after initialisation (e.g. via `Resize()`).
BMF::INVERSE_ALPHA	Indicates reverse alpha blending, higher values are transparent.
BMF::MASK	Declare the Bitmap as a 1 or 8 bit mask. Must be set in conjunction with the Bitmap⇒BitsPerPixel field on initialisation.
BMF::NEVER_SHRINK	Ignore resize requests that would shrink the size of the bitmap.
BMF::NO_DATA	Do not allocate memory in the Data field on initialisation.
BMF::PREMUL	The RGB values are premultiplied (32-bit only).
BMF::QUERIED	Automatically set after a `Query()` on the bitmap.
BMF::TRANSPARENT	Indicates that the bitmap utilises a transparent colour. This is automatically set if the Bitmap⇒TransIndex or Bitmap⇒TransColour is defined, and support exists in functions such as CopyArea().
BMF::USER	This user flag can be used to tag bitmaps with special meaning. Not used internally.

BMP Type

Bitmap types

Name	Description
BMP::CHUNKY	Chunky pixel mode (default).
BMP::PLANAR	Planar pixel mode separates pixel bits across multiple planes. Commonly used for single bit bitmap masks.

BMT Type

Bitmap memory type.

Name	Description
BMT::DATA	The default type, indicates a standard memory allocation from system RAM.
BMT::TEXTURE	Identifies non-displayable video memory, e.g. texture graphics.
BMT::VIDEO	Identifies video memory, such as the frame buffer.

CS Type

Colour space options.

Name	Description
CS::CIE_LAB	Cartesian Lab* colour space defined by CIE 15.
CS::CIE_LCH	Polar L*CHab colour space defined by CIE 15.
CS::LINEAR_RGB	Linear RGB is used to improve colour balance in blending operations.
CS::SRGB	The default colour-space is sRGB.

ColourFormat Structure

Field	Type	Description
RedShift	UINT8	Right shift value for red (15/16 bit formats only)
GreenShift	UINT8	Right shift value for green
BlueShift	UINT8	Right shift value for blue
AlphaShift	UINT8	Right shift value for alpha
RedMask	UINT8	Unshifted mask value for red (ranges from 0x00 to 0xff)
GreenMask	UINT8	Unshifted mask value for green
BlueMask	UINT8	Unshifted mask value for blue
AlphaMask	UINT8	Unshifted mask value for alpha
RedPos	UINT8	Left shift/positional value for red
GreenPos	UINT8	Left shift/positional value for green
BluePos	UINT8	Left shift/positional value for blue
AlphaPos	UINT8	Left shift/positional value for alpha
BitsPerPixel	UINT8	Number of bits per pixel for this format.

Bitmap Class

Structure

Actions

Methods

BAF Type

BLM Type

BMF Type

BMP Type

BMT Type

CS Type

ColourFormat Structure