Class Documentation

Name:Bitmap
Version:1.0
ID:ID_BITMAP
Status:Stable
Include:graphics/bitmap.h
Date:August 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2003. All rights reserved.



Description

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 Screen and Picture objects, and form the backbone of Pandora'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 BLIT 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, you may need to use the Pen class. The Pen class provides more advanced drawing features for bitmap objects while still being able to use hardware acceleration if it is available.

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

Actions

The Bitmap class supports the following actions:

Clear  Clears a bitmap's image to a colour of black.
CopyData  Copies bitmap image data to other bitmaps with colour remapping enabled.
Draw  Clears a bitmap's image to its assigned background colour.
Flush  Flushes pending graphics operations and returns when the accelerator is idle.
Init  Initialises a bitmap.
Lock  Locks the bitmap surface so that you can manipulate the graphics directly.
Query  Fills a bitmap with pre-initialised/default values prior to initialisation.
Read  Reads raw image data from a bitmap object.
Resize  Resizes a bitmap object's dimensions.
SaveImage  Saves a bitmap's image to a data object of your choosing in PCX format.
Seek  Changes the current byte position for read/write operations.
Unlock  Unlocks the bitmap surface once direct access is no longer required.
Write  Writes raw image data to a bitmap object.

Methods

The Bitmap class implements the following methods:

BlitArea  Blits a rectangular area from one bitmap to another.
BlitStretch  Blits a rectangular area from one bitmap to another with stretching.
DrawLine  Draws a line to a bitmap.
DrawPixel  Draws a single pixel to a bitmap.
DrawRGBLine  Draws a line to a bitmap.
DrawRGBPixel  Draws a 24 bit pixel to a bitmap.
DrawRGBRectangle  Draws rectangles, both filled and unfilled.
DrawRectangle  Draws rectangles, both filled and unfilled.
FlipBitmap  Flips a bitmap around the horizontal or vertical axis.
Flood  Fills a bitmap area with a specific colour.
ReadPixel  Reads a pixel's colour from the target bitmap.
ReadRGBPixel  Reads a pixel's RGB colour from the target bitmap.
SetClipRegion  Sets a clipping region for a bitmap object.

Structure

The Bitmap object consists of the following public fields:

AmtColours  The amount of colours in a bitmap object.
BitsPerPixel  The amount of bits per pixel
ByteWidth  The width of a bitmap in bytes.
BytesPerPixel  The amount of bytes per pixel.
ClipBottom  Defines the bottom-most edge of a bitmap's clipping region.
ClipLeft  Defines the left-most edge of a bitmap's clipping region.
ClipRight  Defines the right-most edge of a bitmap's clipping region.
ClipTop  Defines the top-most edge of a bitmap's clipping region.
ColourRGB  The background colour of a bitmap.
Data  Pointer to a bitmap's data area.
DataFlags  Defines the memory flags to use in allocating a bitmap's data area.
Flags  Optional flags.
Height  The height of a bitmap in pixels.
LineMod  The differential between each line in a bitmap.
Opacity  Determines the translucency setting to use in drawing operations.
Palette  Points to a bitmap's colour palette.
PlaneMod  The differential between each bitmap plane.
Position  The current read/write data position.
Size  The total size of a bitmap in bytes.
Type  Defines the data type of a bitmap.
Width  The width of a bitmap in pixels.
Action:Clear
Short:Clears a bitmap's image to a colour of black.

Clearing a bitmap wipes away its graphical contents by drawing a black area over its existing graphics. If you need to clear a bitmap to a specific colour, use the DrawRectangle() method instead.


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

This action will copy the image of a 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.


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

The Flush action is provided for you to ensure that your 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.

You do not have to use this function if you stick to using the graphics functions that are provided in the Bitmap class.


Action:Init
Short:Initialises a bitmap.

This action will initialise a bitmap object so that it is ready for use. If the bitmap Data field has not been specified, a memory block will be allocated and placed in this field. The type of memory that is allocated is dependent on the bitmap DataFlags field. If you have not specified a memory type, you will get a default of MEM_DATA. For a display compatible bitmap use MEM_VIDEO. If you just want to store a bitmap in fast writeable memory, use MEM_BLIT.

This action will not work unless you have defined the Width and Height fields of the bitmap at a minimum.


Action:Query
Short:Fills a bitmap with pre-initialised/default values prior to initialisation.

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

For this action to work properly you must have defined the Width and Height fields of the bitmap before making the Query. This function is intelligent enough to fill out the fields based on the information you have given it, e.g. if you set the BytesPerPixel field to 2 then it will determine that the bitmap is a 16 bit, 64k colour bitmap.


Method:BlitArea()
Short:Blits a rectangular area from one bitmap to another.
Arguments:
OBJECTPTR DestBitmap  Pointer to the destination bitmap.
LONG Flags  Special flags (currently reserved - set to NULL).
LONG XCoord  The horizontal position of the area to be copied.
LONG YCoord  The vertical position of the area to be copied.
LONG Width  The width of the area.
LONG Height  The height of the area.
LONG XDest  The horizontal position to copy the area to.
LONG YDest  The vertical position to copy the area to.

This method allows you to blit rectangular images between bitmaps. It performs a straight region-copy only, using the fastest method available. Bitmaps may be of a different type, however this will result in a much slower copy operation. The copy will honour the clip region set in both the source and destination bitmap objects.

If the TRANSPARENT flag is set in the source object, all colours that match the ColourIndex field will be ignored in the copy operation.

Result
ERR_Okay  The area was drawn successfully.
ERR_Args  The DestBitmap argument was not specified.
ERR_Mismatch  The destination bitmap is not a close enough match to the source bitmap in order to perform the blit.

Method:BlitStretch()
Short:Blits a rectangular area from one bitmap to another with stretching.
Arguments:
OBJECTPTR DestBitmap  Pointer to the destination bitmap.
LONG Flags  Special flags.
LONG XCoord  The horizontal position of the area to be copied.
LONG YCoord  The vertical position of the area to be copied.
LONG Width  The width of the source area.
LONG Height  The height of the source area.
LONG XDest  The horizontal position to copy the area to.
LONG YDest  The vertical position to copy the area to.
LONG DestWidth  The width to use for the destination area.
LONG DestHeight  The height to use for the destination area.

This method allows you to blit rectangular images between bitmaps. It performs a straight region-copy with the added capability of stretching the source to match the destination area. The source and destination bitmaps may be of a different type, however this will result in a much slower copy operation. The copy will honour the clip region set in both the source and destination bitmap objects.

Special flags affecting the stretch operation are accepted by this routine. The following table illustrates the available options.

FlagDescription
BILINEAR  Enables bilinear resampling of the source image. This increases the quality of the resize at a cost of speed.
FILTERSOURCEIf the source bitmap is temporary and will not be required after the stretch operation, you have the option of setting this flag. By doing so, the stretch routine will pass the source image through a simple filter so that it can improve the resulting image. This option is realised at an extra speed cost and is best used in conjunction with bilinear resizing.

Special operations like transparency and alpha blending are not currently supported by this routine.

Result
ERR_Okay  The area was drawn successfully.
ERR_Args  The DestBitmap argument was not specified.
ERR_Mismatch  The destination bitmap is not a close enough match to the source bitmap in order to perform the blit.

Method:DrawLine()
Short:Draws a line to a bitmap.
Arguments:
LONG XCoord  Horizontal start coordinate.
LONG YCoord  Vertical start coordinate.
LONG XEnd  Horizontal end coordinate.
LONG YEnd  Vertical end coordinate.
LONG Colour  The pixel colour to use for drawing the line.

This method will draw a line using a 24 bit colour value. The line will start from the position determined by (XCoord, YCoord) and end at (XEnd, YEnd) inclusive. Hardware acceleration will be used to draw the line if available.

The opacity of the line is determined by the value in the Opacity field of the target bitmap.

Result
ERR_Okay  The method executed successfully.
ERR_Args  No arguments were specified.

Method:DrawPixel()
Short:Draws a single pixel to a bitmap.
Arguments:
LONG X  The horizontal coordinate of the pixel.
LONG Y  The vertical coordinate of the pixel.
LONG Colour  The colour value to use for the pixel.

This method draws a pixel to coordinates (XCoord, YCoord) on a bitmap with a colour determined by the Colour index. The method will check the given coordinates to make sure that the pixel is inside the bitmap's clipping area. An error code of ERR_OutOfBounds is returned if the pixel cannot be drawn.

Result
ERR_Okay  The pixel was drawn successfully.
ERR_OutOfBounds  The pixel coordinates lie outside of the bitmap's clipping area.
ERR_Args  No arguments were specified.

Method:DrawRGBLine()
Short:Draws a line to a bitmap.
Arguments:
LONG XCoord  Horizontal start coordinate.
LONG YCoord  Vertical start coordinate.
LONG XEnd  Horizontal end coordinate.
LONG YEnd  Vertical end coordinate.
LONG Red  The red component of the line colour.
LONG Green  The green component of the line colour.
LONG Blue  The blue component of the line colour.

This method will draw a line using a 24 bit colour value. The line will start from the position determined by (XCoord, YCoord) and end at (XEnd, YEnd) inclusive. Hardware acceleration will be used to draw the line if available.

The opacity of the line is determined by the value in the Opacity field of the target bitmap.

Result
ERR_Okay  The method executed successfully.
ERR_Args  No arguments were specified.

Method:DrawRGBPixel()
Short:Draws a 24 bit pixel to a bitmap.
Synopsis:LONG XCoord, LONG YCoord, LONG Red, LONG Green, LONG Blue
Arguments:
LONG XCoord  Horizontal coordinate of the pixel.
LONG YCoord  Vertical coordinate of the pixel.
LONG Red  The red component of the pixel colour.
LONG Green  The green component of the pixel colour.
LONG Blue  The blue component of the pixel colour.

This method draws a 24-bit pixel to the (XCoord, YCoord) position of a target bitmap. The method will check the given coordinates to make sure that the pixel is inside the bitmap's clipping area. An error code of ERR_OutOfBounds is returned if the pixel cannot be drawn.

Result
ERR_Okay  The method executed successfully.
ERR_OutOfBounds  The pixel coordinates lie outside of the bitmap's clipping area.
ERR_Args  No arguments were specified.

Method:DrawRGBRectangle()
Short:Draws rectangles, both filled and unfilled.
Arguments:
LONG XCoord  The left-most coordinate of the rectangle.
LONG YCoord  The top-most coordinate of the rectangle.
LONG Width  The width of the rectangle.
LONG Height  The height of the rectangle.
LONG Red  The red component of the rectangle's colour.
LONG Green  The green component of the rectangle's colour.
LONG Blue  The blue component of the rectangle's colour.
LONG Fill  Set to TRUE to fill the rectangle, otherwise use FALSE to draw the outline.

This method draws both filled and unfilled rectangles. The rectangle is drawn to the target bitmap at position (XCoord, YCoord) with dimensions determined by the specified Width and Height. If the Fill argument is set to TRUE then the rectangle will be filled, otherwise the rectangle's outline will be drawn. The colour of the rectangle is determined by the Red, Green and Blue settings.

Result
ERR_Okay  The rectangle was drawn successfully.
ERR_Args  Invalid arguments were detected.

Method:DrawRectangle()
Short:Draws rectangles, both filled and unfilled.
Arguments:
LONG XCoord  The left-most coordinate of the rectangle.
LONG YCoord  The top-most coordinate of the rectangle.
LONG Width  The width of the rectangle.
LONG Height  The height of the rectangle.
LONG Colour  The colour index to use for the rectangle.
LONG Fill  Set to TRUE to fill the rectangle, otherwise use FALSE to draw the outline.

This method draws both filled and unfilled rectangles. The rectangle is drawn to the target bitmap at position (XCoord, YCoord) with dimensions determined by the specified Width and Height. If the Fill argument is set to TRUE 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 argument.

If you would like the rectangle to be translucent, you will need to set the bitmap's Opacity field before calling this method.

Result
ERR_Okay  The rectangle was drawn successfully.
ERR_Args  Invalid arguments were detected.

Method:FlipBitmap()
Short:Flips a bitmap around the horizontal or vertical axis.
Arguments:
LONG Orientation  Set to either FLIP_HORIZONTAL or FLIP_VERTICAL. If you do not set this argument correctly then the function will do nothing.

This method is used to flip bitmap images on their horizontal or vertical axis. The amount of time required to flip a bitmap is dependent on the area of the bitmap you are trying to flip over and its total number of colours.

Result
ERR_Okay  The method executed successfully.
ERR_Args  Invalid arguments were specified.

Method:Flood()
Short:Fills a bitmap area with a specific colour.
Arguments:
LONG XCoord  The horizontal point to start the flood fill.
LONG YCoord  The vertical point to start the flood fill.
LONG Red  The red component of the fill colour.
LONG Green  The green component of the fill colour.
LONG Blue  The blue component of the fill colour.

The Flood method allows you to fill the graphics of a bitmap area with a specific colour. The extent of the fill is determined by the colour being replaced (which is picked up from the coordinate that the fill is to start from). This means that the fill only stops when pixels within the immediate vicinity do not match the colour that is being replaced. The fill is also restricted by the target bitmap's clipping area.

The speed of the algorithm is wholly dependent on the amount of pixels that need to be filled, although hardware support may be used for filling if it is available.

Result
ERR_Okay  The flood fill executed successfully.
ERR_Args  Invalid arguments were detected.

Method:ReadPixel()
Short:Reads a pixel's colour from the target bitmap.
Arguments:
LONG XCoord  The horizontal coordinate of the pixel.
LONG YCoord  The vertical coordinate of the pixel.
LONG Colour  The colour value of the pixel will be returned in this parameter.

This method reads a pixel from a bitmap area and returns its closest matching colour index in the bitmap's Palette. If you give this method coordinates that lie outside of the bitmap's clipping area, it will return an error code of ERR_OutOfBounds.

Result
ERR_Okay  The colour value has been read and placed in the Colour parameter.
ERR_OutOfBounds  The pixel coordinates are outside of the bitmap's clipping area.

Method:ReadRGBPixel()
Short:Reads a pixel's RGB colour from the target bitmap.
Arguments:
LONG XCoord  The horizontal coordinate of the pixel.
LONG YCoord  The vertical coordinate of the pixel.
LONG Red  This parameter will be updated with the red value of the pixel.
LONG Green  This parameter will be updated with the green value of the pixel.
LONG Blue  This parameter will be updated with the blue value of the pixel.

This method reads a pixel from a bitmap area and sets its RGB colour value in the Red, Green and Blue parameters. If the coordinates fall outside of the Bitmap border, the function will return a colour setting of black (0, 0, 0) and an error code of ERR_OutOfBounds.

Result
ERR_Okay  The RGB colour value of the pixel was read and placed in the Red, Green and Blue parameters.
ERR_OutOfBounds  The target pixel is outside of the bitmap's clipping area.

Method:SetClipRegion()
Short:Sets a clipping region for a bitmap object.
Arguments:
LONG Number  The number of the clip region to set.
LONG Left  The horizontal start of the clip region.
LONG Top  The vertical start of the clip region.
LONG Right  The right-most edge of the clip region.
LONG Bottom  The bottom-most edge of the clip region.
LONG Terminate  Set to TRUE if this is the last clip region in the list, otherwise FALSE.

The SetClipRegion() method is used to manage the clipping regions assigned to a bitmap object. Each new bitmap that is created has at least one clip region assigned to it, but by using SetClipRegion() you can also define multiple clipping areas, which is useful for complex graphics management.

Each clipping region that you set is assigned a Number, starting from zero which is the default. Each time that you set a new clip region you must specify the number of the region that you wish to set. If you attempt to 'skip' regions, for instance, if you set regions 0, 1, 2 and 3, then skip 4 and set 5, the routine will set region 4 instead. If you have specified multiple clip regions and want to lower the count or reset the list, set the number of the last region that you want in your list and set the Terminate argument to TRUE to kill the regions specified beyond it.

Every time you use the SetClipRegion() method, the ClipLeft, ClipTop, ClipRight and ClipBottom fields will be updated to reflect the total area covered by the clipping regions that you have set.

Result
ERR_Okay  The clipping region was set successfully.
ERR_Args  Invalid arguments were detected.

Field:AmtColours
Short:The amount of colours in a bitmap object.
Type:LONG
Status:Read/Init

This field specifies the total amount of colours available in the bitmap. If you set this value to NULL then the initialisation process will determine the amount of colours for you. Common values for this field are:

   2, 4, 8, 16, 32, 64, 128, 256, 32767, 65535, 16777215

Field:BitsPerPixel
Short:The amount of bits per pixel
Type:LONG
Status:Read/Init

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.


Field:ByteWidth
Short:The width of a bitmap in bytes.
Type:LONG
Status:Read

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

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

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

If you would like to know the total byte width per line including any padded bytes that may lie at the end of each line, please refer to the LineMod field.


Field:BytesPerPixel
Short:The amount of bytes per pixel.
Type:LONG
Status:Read

If you need to find out how many bytes are involved in the makeup of each pixel you will need to read this field. The maximum number of bytes you can typically expect is 4 and the minimum is 1. If a planar bitmap is being used then you should refer to the BitsPerPixel field, which should yield more useful information.


Field:ClipBottom
Short:Defines the bottom-most edge of a bitmap's clipping region.
Type:LONG
Status:Read

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.


Field:ClipLeft
Short:Defines the left-most edge of a bitmap's clipping region.
Type:LONG
Status:Read

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.


Field:ClipRight
Short:Defines the right-most edge of a bitmap's clipping region.
Type:LONG
Status:Read

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.


Field:ClipTop
Short:Defines the top-most edge of a bitmap's clipping region.
Type:LONG
Status:Read

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.


Field:ColourRGB
Short:The background colour of a bitmap.
Type:RGB
Status:Read/Set

The background colour of the bitmap can be specified with this field. Initialising a bitmap with a colour other than black will cause it to be painted to the requested colour value. The colour setting also determines the transparency value of an image when masking is being used.


Field:Data
Short:Pointer to a bitmap's data area.
Type:APTR
Status:Read/Set

This field points directly to the start of a bitmap's data area. Allocating your own bitmap memory is acceptable if you are 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.


Field:DataFlags
Short:Defines the memory flags to use in allocating a bitmap's data area.
Type:LONG
Prefix:MEM
Status:Read/Init

This field determines what type of memory will be allocated for the Data field during the initialisation process. This field accepts the MEM_DATA, MEM_VIDEO and MEM_BLIT memory flags.

Please note that video and blitter based bitmaps are faster than data bitmaps, but they are considered to consist of read-only memory. 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, please use the Lock action to enable read access when you require it.


Field:Flags
Short:Optional flags.
Type:LONG
Prefix:BMF
Status:Read/Init

This field contains flags that affect bitmap behaviour. Currently available flags are:

FlagDescription
2DACCELERATED2D video acceleration is available.
3DACCELERATED3D video acceleration is available.
ALPHAFor 32-bit images, indicates that an alpha channel is present.
ALPHABLENDFor 32-bit images, this flag can be set to enable alpha blending when performing a blit. Can be set either in the source or destination.
BLANKPALETTE  Setting this flag causes the bitmap to drive all Palette colours to black on initialisation.
CLEARClear graphics on initialisation and when resizing.
CLIPPINGSet by default, this flag ensures that the drawing routines adhere to the clipping boundaries. Turning off the flag causes some routines to skip clipping checks for speed, but be warned that this can be very dangerous when used incorrectly.
INVERSEALPHAIndicates reverse alpha blending, which means that higher values are transparent.
MASKUse this flag to declare that the bitmap will be used as a 1 bit mask or an 8 bit alpha channel. It is recommended that you set the BitsPerPixel field in conjunction with this flag, or you will get the default of a 1-bit bitmap type. The MASK flag can only be set prior to initialisation.
NEVERSHRINKIgnore resize requests that would shrink the size of the bitmap.
NODATATells the bitmap not to allocate image data on initialisation.
TRANSPARENTIndicates that the bitmap utilises a transparent colour. This is automatically set if you write the ColourRGB field and is supported by functions such as BlitArea().
USERYou may set this user flag to tag bitmaps that have a special meaning to you. This flag serves no purpose to the Bitmap class.

Field:Height
Short:The height of a bitmap in pixels.
Type:LONG
Status:Read/Init

The pixel height of a bitmap is defined in this field. A bitmap must have a minimum height of 1. This field must be set prior to the initialisation of a bitmap, or the initialisation process will fail.


Field:LineMod
Short:The differential between each line in a bitmap.
Type:LONG
Status:Read

This field is a calculation of the distance between each line on the bitmap (the line differential). For PLANAR and CHUNKY based bitmaps the value will match the ByteWidth field, plus any extra bytes used to pad out each line. For the ILBM Type the value will be calculated from the formula "ByteWidth * BitsPerPixel".


Field:Opacity
Short:Determines the translucency setting to use in drawing operations.
Type:LONG
Status:Read/Write

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 the translucency effect. Lowering the value will increase the level of translucency when drawing graphics.


Field:Palette
Short:Points to a bitmap's colour palette.
Type:struct RGBPalette *
Status:Read/Set

A palette is an array of containing colour values in standard RGB format ($RRGGBB). The first longword 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:

  struct 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 Screen need to be notified if you want a palette's colours to be propagated to the video display.


Field:PlaneMod
Short:The differential between each bitmap plane.
Type:LONG
Status:Read

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

   ILBM:   ByteWidth
   PLANAR: ByteWidth * Height

Field:Position
Short:The current read/write data position.
Type:LONG
Status:Read

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.


Field:Size
Short:The total size of a bitmap in bytes.
Type:LONG
Status:Read

You can read this field to determine the total amount of bytes that have been allocated for a bitmap's data area.


Field:Type
Short:Defines the data type of a bitmap.
Type:LONG
Status:Read/Init

This field defines the display data type - either PLANAR, ILBM, or CHUNKY. Note that for planar bitmaps, the bitplanes are stored sequentially, one after the other. There is no scattering of planar bitplane memory.

If you set this field to NULL then the initialisation process will select the preferred user screen type. This can be useful if you want to accommodate the user's preferred display type. Remember that if you specify a Type that is unsupported in hardware, then it will have to be emulated (slowing things down considerably). Type independence is strongly encouraged because of this reason.


Field:Width
Short:The width of a bitmap in pixels.
Type:LONG
Status:Read/Init

The pixel width of a bitmap is defined in this field. A bitmap must have a minimum width of 1. This field must be set prior to the initialisation of a bitmap, or the initialisation process will fail.