Class Documentation

Name:Bitmap
Version:1
ID:ID_BITMAP
Status:Unspecified
Include:graphics/bitmap.h
Date:July 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2001. All rights reserved.



Description

The Bitmap 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 behind all graphics functionality. Without it there would be no user interface, so expect to use this class regularly during your programming. It would be wise to read the majority of this document so that you can familiarise yourself with how the Bitmap class works.

The Bitmap class includes a number of methods that can be used to draw graphics to a Bitmap's image area. Please note that these methods are designed to be called under exclusive conditions and it is not possible to message a Bitmap with any of the methods that are available.

You can save a Bitmap's image to a data object by using the SaveImage action and raw data can be processed through the use of 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.
Init  Initialises a Bitmap.
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.
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.
DrawLine  Draws a line to a Bitmap.
DrawPixel  Draws a single pixel to a Bitmap.
DrawRGBPixel  Draws a 24 bit pixel to a Bitmap.
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.

Structure

The Bitmap object consists of the following public fields:

AmtColours  The amount of colours in a Bitmap.
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 edge of a Bitmap's clipping region.
ClipLeft  Defines the left edge of a Bitmap's clipping region.
ClipRight  Defines the right edge of a Bitmap's clipping region.
ClipTop  Defines the top 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.
MaskIndex  The colour index to use for masking.
MaskRGB  The colour to use for masking.
Palette  Points to a Bitmap's colour palette.
PixelMode  Used for reading raw image data from video and blitter based Bitmaps.
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: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 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.

 

Method:BlitArea()
Short:Blits a rectangular area from one Bitmap to another.
Arguments:
OBJECTPTR DestBitmap  Pointer to the destination Bitmap.
OBJECTPTR Mask  Reference to a mask object, or NULL if no masking should be used.
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. Both Bitmaps must have an identical number of colours - e.g. if the source is a 64k colour Bitmap then the destination must also be a 64k colour Bitmap.

If you want to use a mask in the blit operation, set the Mask argument so that it refers to a Mask object. The size of the Mask's dimensions must be greater or equal to the Width and Height arguments that have been specified. An error of ERR_SmallMask is returned if the Mask is not large enough.

Result
ERR_Okay  The area was drawn successfully.
ERR_Args  Invalid arguments were detected.
ERR_Mismatch  The destination Bitmap is not a close enough match to the source Bitmap in order to perform the blit.
ERR_SmallMask  The width and/or height of the Mask object is smaller than the width or height of the source Bitmap.

 

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 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 draws lines using 24 bit colour values. 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.

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: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: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 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: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 capable of flipping Bitmap images on their horizontal or vertical axis. This may or may not take some time, depending on the size of the Bitmap you are trying to flip over and its Type.

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.

 

Field:AmtColours
Short:The amount of colours in a Bitmap.
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

 

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 edge of a Bitmap's clipping region.
Type:LONG
Status:Read/Write

During the initialisation of a Bitmap a clipping region will be defined that matches the Bitmap's dimensions. By adjusting the clipping region you can clip graphics to a rectangular area that is smaller than the Bitmap's maximum dimensions.

This particular field is responsible for defining the clipping region's bottom edge. The specified value must be greater than zero and may not exceed the Bitmap's Height setting.

 

Field:ClipLeft
Short:Defines the left edge of a Bitmap's clipping region.
Type:LONG
Status:Read/Write

During the initialisation of a Bitmap a clipping region will be defined that matches the Bitmap's dimensions. By adjusting the clipping region you can clip graphics to a rectangular area that is smaller than the Bitmap's maximum dimensions.

This particular field is responsible for defining the clipping region's left edge. The specified value must be zero or greater and may not exceed the Bitmap's ClipRight setting.

 

Field:ClipRight
Short:Defines the right edge of a Bitmap's clipping region.
Type:LONG
Status:Read/Write

During the initialisation of a Bitmap a clipping region will be defined that matches the Bitmap's dimensions. By adjusting the clipping region you can clip graphics to a rectangular area that is smaller than the Bitmap's maximum dimensions.

This particular field is responsible for defining the clipping region's right edge. The specified value must be greater than zero and may not exceed the Bitmap's Width setting.

 

Field:ClipTop
Short:Defines the top edge of a Bitmap's clipping region.
Type:LONG
Status:Read/Write

During the initialisation of a Bitmap a clipping region will be defined that matches the Bitmap's dimensions. By adjusting the clipping region you can clip graphics to a rectangular area that is smaller than the Bitmap's maximum dimensions.

This particular field is responsible for defining the clipping region's top edge. The specified value must be zero or greater and may not exceed the Bitmap's ClipBottom setting.

 

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 may also affect the behaviour of foreign objects that make use of this field.

 

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

This field points directly to the start of the 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 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 PixelMode field 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
BLANKPALETTE  Setting this flag causes the Bitmap to drive all Palette colours to black on initialisation.
NODATATells the Bitmap not to allocate image data on initialisation.
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.

 

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. For the ILBM Type the value will be calculated from the formula "ByteWidth * BitsPerPixel".

 

Field:MaskIndex
Short:The colour index to use for masking.
Type:LONG
Status:Read/Init

You can set the MaskIndex field when initialising a Bitmap in order to aid blitter operations that support colour masks. Any pixel matching the MaskIndex value that you specify will be recognised as a clear pixel, and thus will not be copied during blitter operations that support masking.

Alternatively, you can set the MaskRGB field if it is more suitable for your purposes.

 

Field:MaskRGB
Short:The colour to use for masking.
Type:RGB
Status:Read/Set

You can set the MaskRGB field when initialising a Bitmap in order to aid blitter operations which support masking activity. Any pixel that matches the MaskRGB will be recognised as a clear pixel, and thus will not be copied during blitter operations that support masking. Alternatively, you can set the ColourMask field if it is more suitable for your purposes.

 

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:PixelMode
Short:Used for reading raw image data from video and blitter based Bitmaps.
Type:LONG
Status:Set

Normally it is only possible to read pixels from Bitmaps that are held in data (normal) memory. Because video and blitter based Bitmaps are often held in memory areas that are not directly readable, special functionality is required to get direct access to the data of these Bitmap types. The PixelMode field provides you with this functionality.

To enable read access, set this field to a value of PIXEL_READ. If successful, it will then be possible to access the Bitmap data through all of the pixel based methods, as well as through the Data field. If a problem occurs, an error other than ERR_Okay will be returned when you set this field.

Please note that after you have finished reading information from a Bitmap, you should set this field with a value of PIXEL_WRITE so that you can write to it again. This is also vital for destroying any memory that was created when you were given read access. If you do not set the PIXEL_WRITE value, any open resources will be deallocated when you free the Bitmap or use the FreeExclusive() function to unlock the Bitmap.

 

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 find out how big the Bitmap is in bytes. The size is calculated using the following formula:

   Size = Width * Height * BytesPerPixel

 

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.