Parasol Framework Manual

Manages bitmap graphics and provides drawing functionality.

The Bitmap class provides a way of describing an area of memory that an application can draw to, and/or display if the data is held in video memory. Bitmaps are used in the handling of Display and Picture objects, and form the backbone of Parasol's graphics functionality. The Bitmap class supports everything from basic graphics primitives to masking and alpha blending features.

To create a new bitmap object, you need to specify its Width and Height at a minimum. Preferably, you should also know how many colours you want to use and whether the bitmap data should be held in standard memory (for CPU based reading and writing) or video memory (for hardware based drawing). After creating a bitmap you can use a number of available drawing methods for the purpose of image management. Please note that these methods are designed to be called under exclusive conditions, and it is not recommended that you call methods on a bitmap using the message system.

By default, the CPU can only be used to read and write data directly to or from a bitmap when it is held in standard memory (this is the default type). If the TEXTURE or VIDEO flags are specified in the DataFlags field then the CPU cannot access this memory, unless you specifically request it. To do this, use the Lock() and Unlock() actions to temporarily gain read/write access to a bitmap.

If you require complex drawing functionality that is not available in the Bitmap class, consider using the functionality provided by the Vector module.

To save the image of a bitmap, either copy its image to a Picture object, or use the SaveImage() action to save the data in PNG format. Raw data can also be processed through a bitmap by using the Read and Write actions.

Structure

The Bitmap class consists of the following fields:

Access

Name

Type

Comment

AmtColours INT The maximum number of displayable colours.

BitsPerPixel INT The number of bits per pixel

The BitsPerPixel field clarifies exactly how many bits are being used to manage each pixel on the display. This includes any 'special' bits that are in use, e.g. alpha-channel bits.

Bkgd RGB8 The bitmap's background colour is defined here in RGB format.

The default background colour for a bitmap is black. To change it, set this field with the new RGB colour. The background colour is used in operations that require a default colour, such as when clearing the bitmap.

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

BkgdIndex INT The bitmap's background colour is defined here as a colour index.

The bitmap's background colour is defined in this field as a colour index. It is recommended that the Bkgd field is used for altering the bitmap background unless efficiency requires that the colour index is calculated and set directly.

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

The BlendMode field defines the blending algorithm to use when rendering transparent pixels. The default value is AUTO which will use the best blending algorithm available for the current graphics context.

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.

The ByteWidth of the bitmap is calculated directly from the bitmap's Width and Type settings. Under no circumstances should you attempt to calculate this value in advance, as it is heavily dependent on the bitmap's Type.

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 number of bytes used to construct one pixel. The maximum number of bytes a client can typically expect is 4 and the minimum is 1. If the graphics type is planar then refer to the BitsPerPixel field, which should yield more useful information.

Clip struct ClipRectangle Defines the bitmap's clipping region.

The Clip field is a short-hand reference for the ClipLeft, ClipTop, ClipRight and ClipBottom fields, returning all four values as a single ClipRectangle structure.

ClipBottom INT The bottom-most edge of bitmap's clipping region.

During the initialisation of a bitmap, a default clipping region will be created that matches the bitmap's dimensions. Clipping regions define the area under which graphics can be drawn to a bitmap. This particular field reflects the bottom-most edge of all clipping regions that have been set or altered through the SetClipRegion() method.

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

During the initialisation of a bitmap, a default clipping region will be created that matches the bitmap's dimensions. Clipping regions define the area under which graphics can be drawn to a bitmap. This particular field reflects the left-most edge of all clipping regions that have been set or altered through the SetClipRegion() method.

ClipRight INT The right-most edge of a bitmap's clipping region.

During the initialisation of a bitmap, a default clipping region will be created that matches the bitmap's dimensions. Clipping regions define the area under which graphics can be drawn to a bitmap. This particular field reflects the right-most edge of all clipping regions that have been set or altered through the SetClipRegion() method.

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

During the initialisation of a bitmap, a default clipping region will be created that matches the bitmap's dimensions. Clipping regions define the area under which graphics can be drawn to a bitmap. This particular field reflects the top-most edge of all clipping regions that have been set or altered through the SetClipRegion() method.

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

The ColourFormat field points to a structure that defines the colour format used to construct each bitmap pixel. It only applies to bitmaps that use 2-bytes per colour value or better. The structure consists of the following fields:

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

The following C++ methods can called on any bitmap in order to build colour values from individual RGB components:

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

The following C macros are optimised versions of the above that are limited to 24 and 32-bit bitmaps:

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

The following C++ methods can be used to unpack individual colour components from any colour value read from the bitmap:

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 UBYTE * Pointer to a bitmap's data area.

This field points directly to the start of a bitmap's data area. Allocating your own bitmap memory is acceptable if creating a bitmap that is not based on video memory. However, it is usually a better idea for the initialisation process to allocate the correct amount of memory for you by not interfering with this field.

DataFlags MEM Defines the memory flags to use in allocating a bitmap's data area.

This field determines the type of memory that will be allocated for the Data field during the initialisation process. This field accepts the MEM::DATA, MEM::VIDEO and MEM::TEXTURE memory flags.

Please note that video based bitmaps may be faster than data bitmaps for certain applications, but the content is typically read-only. Under normal circumstances it is not possible to use the pixel reading functions, or read from the bitmap Data field directly with these bitmap types. To circumvent this problem use the Lock() action to enable read access when you require it.

Name	Description

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

This field points to an internal C function that can be used for drawing pixels to the bitmap. It is intended that the function is only ever called by C programs and that caution is exercised by the programmer, as no clipping checks will be performed (meaning it is possible to supply invalid coordinates that would result in a segfault).

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

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

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

This field points to an internal C function that can be used for drawing pixels to the bitmap. It is intended that the function is only ever called by C programs and that caution is exercised by the programmer, as no clipping checks will be performed (meaning it is possible to supply an invalid address that would result in a segfault).

The prototype of the DrawUCRIndex function is Function(*Bitmap, uint8_t *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.

Note that a colour indexing equivalent of this function is not available in the Bitmap class - this is because it is more efficient to index the Bitmap's Data field directly.

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

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.

Height INT The height of the bitmap, in pixels.

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

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

Some drawing operations support the concept of applying an opacity rating to create translucent graphics. By adjusting the opacity rating, you can affect the level of translucency that is applied when executing certain graphics operations.

Methods that support opacity should document the fact that they support the feature. By default the opacity rating is set to 255 to turn off translucency effects. Lowering the value will increase the level of translucency when drawing graphics.

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

A palette is an array of containing colour values in standard RGB format 0xRRGGBB. The first value must have a header ID of ID_PALETTE, followed by the amount of values in the array. Following this is the actual list itself - colour 0, then colour 1 and so on. There is no termination signal at the end of the list.

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 based bitmaps above 8-bit colour. This is because a number of drawing functions require a palette table for conversion between the bitmap types.

Although the array is dynamic, parent objects such as the Display need to be notified if you want a palette's colours to be propagated to the video display.

PlaneMod INT The differential between each bitmap plane.

This field specifies the distance (in bytes) between each bitplane. For non-planar types like CHUNKY, this field will reflect the total size of the bitmap. The calculation used for PLANAR types is ByteWidth * Height.

Position INT The current read/write data position.

This field reflects the current byte position for reading and writing raw data to and from a bitmap object. If you need to change the current byte position, use the Seek action.

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

This field points to an internal C function that can be used for reading pixels from the bitmap. It is intended that the function is only ever called by C programs and that caution is exercised by the programmer, as no clipping checks will be performed (meaning it is possible to supply invalid X/Y coordinates that would result in a segfault).

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.

This field points to an internal C function that can be used for reading pixels from the bitmap. It is intended that the function is only ever called by C programs and that caution is exercised by the programmer, as no clipping checks will be performed (meaning it is possible to supply an invalid address that would result in a segfault).

The prototype of the ReadUCRIndex function is Function(*Bitmap, uint8_t *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.

Note that a colour indexing equivalent of this function is not available in the Bitmap class - this is because it is more efficient to index the Bitmap's Data field directly.

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

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

The pixel value will be returned in the RGB parameter. It should be noted that as this function converts the pixel value into RGB format, ReadUCPixel or ReadUCRIndex should be used as faster alternatives if the pixel value does not need to be de-constructed into its RGB components.

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

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

The transparent colour of the bitmap is defined here. Colours in the bitmap that match this value will not be copied during drawing operations.

NOTE: This field should never be set if the bitmap utilises alpha transparency.

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

The transparent colour of the bitmap is defined here. Colours in the bitmap that match this value will not be copied during graphics operations. It is recommended that the TransColour field is used for altering the bitmap transparency unless efficiency requires that the transparency is set directly.

NOTE: This field should never be set if the bitmap utilises alpha transparency.

Type BMP Defines the data type of the bitmap.

This field defines the graphics data type - either PLANAR (required for 1-bit bitmaps) or CHUNKY (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.

Actions

The following actions are currently supported:

Clear Clears a bitmap's image to BkgdIndex.

ERR acClear(*Object)

Clearing a bitmap wipes away its graphical contents by drawing a blank area over its existing graphics. The colour of the blank area is determined by the BkgdIndex field. To clear a bitmap to a different colour, use the DrawRectangle() method instead.

If the bitmap supports alpha blending and a transparent result is desired, setting BkgdIndex to zero is an efficient way to achieve this outcome.

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.

This action will copy the image of the bitmap to any other initialised bitmap that you specify. Support for copying the image data to other object class types is not provided.

This action features automatic clipping and remapping, for occasions where the bitmaps do not match up in size or colour.

Draw Clears a bitmap's 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.

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

ERR acFlush(*Object)

The Flush() action ensures that client graphics operations are synchronised with the graphics accelerator. Synchronisation is essential prior to drawing to the bitmap with the CPU. Failure to synchronise may result in corruption in the bitmap's graphics display.

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)

This action will initialise a bitmap object so that it is ready for use, which primarily means that a suitable area of memory is reserved for drawing. If the Data field has not already been defined, a new memory block will be allocated for the bitmap region. The type of memory that is allocated is dependent on the DataFlags field, which defaults to MEM::DATA. To request video RAM, use MEM::VIDEO. To store graphics data in fast write-able memory, use MEM::TEXTURE.

The Init() action requires that the Width and Height fields are defined at minimum.

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

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

ERR acQuery(*Object)

This action will pre-initialise a bitmap object so that its fields are populated with default values. It stops short of allocating the bitmap's memory.

This action requires that the Width and Height fields of the bitmap are defined at minimum. Populating the bitmap fields is done on a best efforts basis, e.g. if the BytesPerPixel is set to 2 then it will be determined that the bitmap is a 16 bit, 64k colour bitmap.

Read Reads raw image data from a bitmap object.

ERR acRead(*Object, APTR Buffer, INT Length, INT *Result)

Parameter	Description
Buffer	Points a buffer that will receive the data.
Length	The total number of bytes to read from the object. This value cannot exceed the size of the Buffer.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

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.

Resizing a bitmap will change its Width, Height and optionally BitsPerPixel. Existing image data is not retained by this process.

The image data is cleared with Bkgd if the CLEAR flag is defined in Flags.

Error Codes

Okay	Operation successful.
FieldNotSet	A required field value is undefined.
AllocMemory	A call to AllocMemory() failed to create a new memory block.
NullArgs	Function call missing argument value(s)

SaveImage Saves a bitmap's image to a data object of your choosing 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 Picture class to use for encoding the image data.

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.

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

Write Writes raw image data to a bitmap object.

ERR acWrite(*Object, APTR Buffer, INT Length, INT Result)

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

Methods

The following methods are currently supported:

Compress Compresses bitmap data to save memory.

ERR bmp::Compress(OBJECTPTR Object, INT Level)

Parameter	Description
Level	Level of compression. Zero uses a default setting (recommended), the maximum is 10.

A bitmap can be compressed with the CompressBitmap() method to save memory when the bitmap is not in use. This is useful if a large bitmap needs to be stored in memory and it is anticipated that the bitmap will be used infrequently.

Once a bitmap is compressed, its image data is invalid. Any attempt to access the bitmap's image data will likely result in a memory access fault. The image data will remain invalid until the Decompress() method is called to restore the bitmap to its original state.

The BMF::COMPRESSED bit will be set in the Flags field after a successful call to this function to indicate that the bitmap is compressed.

Error Codes

Okay	Operation successful.
AllocMemory	A call to AllocMemory() failed to create a new memory block.
ReallocMemory	The reallocation of a memory block failed.
CreateObject	A Compression object could not be created.
NullArgs	Function call missing argument value(s)

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

ERR bmp::ConvertToLinear(OBJECTPTR Object)

Use ConvertToLinear to convert the colour space of a bitmap from sRGB to linear RGB. If the BMF::ALPHA_CHANNEL flag is enabled on the bitmap, pixels with an alpha value of 0 are ignored.

The ColourSpace will be set to LINEAR_RGB on completion. This method returns immediately if the ColourSpace is already set to LINEAR_RGB.

For the sake of efficiency, lookup tables are used to quickly perform the conversion process.

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 Convert a bitmap's colour space to standard RGB.

ERR bmp::ConvertToRGB(OBJECTPTR Object)

Use ConvertToRGB() to convert the colour space of a bitmap from linear RGB to sRGB. If the BMF::ALPHA_CHANNEL flag is enabled on the bitmap, pixels with an alpha value of 0 are ignored.

The ColourSpace will be set to SRGB on completion. This method returns immediately if the ColourSpace is already set to SRGB.

For the sake of efficiency, lookup tables are used to quickly perform the conversion process.

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.

This method is a proxy for CopyArea().

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)

Decompress Decompresses a compressed bitmap.

ERR bmp::Decompress(OBJECTPTR Object, INT RetainData)

Parameter	Description
RetainData	Retains the compression data if `true`.

The Decompress() method is used to restore a compressed bitmap to its original state. If the bitmap is not compressed, the method does nothing.

The compressed data will be terminated unless RetainData is true. Retaining the data will allow the client to repeatedly restore the content of the most recent Compress() call.

Error Codes

Okay	Operation successful.
AllocMemory	Insufficient memory in recreating the bitmap data buffer.

Demultiply Reverses the conversion process performed by Premultiply().

ERR bmp::Demultiply(OBJECTPTR Object)

Use Demultiply() to normalise RGB values that have previously been converted by Premultiply(). This method will return immediately if the bitmap values are already normalised, as determined by the presence of the PREMUL value in Flags.

Error Codes

Okay	Operation successful.
NothingDone	The content is already normalised.
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.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.

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)

Use Premultiply() to convert all RGB values in the bitmap's clipping region to pre-multiplied values. The exact formula applied per channel is (Colour * Alpha + 0xff)>>8. The alpha channel is not affected.

This method will only operate on 32 bit bitmaps, and an alpha channel must be present. If the RGB values are already pre-multiplied, the method returns immediately.

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 Number, INT Left, INT Top, INT Right, INT Bottom, INT Terminate)

Parameter	Description
Number	The number of the clip region to set.
Left	The horizontal start of the clip region.
Top	The vertical start of the clip region.
Right	The right-most edge of the clip region.
Bottom	The bottom-most edge of the clip region.
Terminate	Set to `true` if this is the last clip region in the list, otherwise `false`.

This method is a proxy for SetClipRegion().

Error Codes

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

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.

Bitmap Class

Structure

Actions

Methods

BAF Type

BLM Type

BMF Type

BMP Type

CS Type

ColourFormat Structure