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. |
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.
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.
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.
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. | |
|
Action: | Flush | |
Short: | Flushes pending graphics operations and returns when the accelerator is idle. | |
|
Action: | Init | |
Short: | Initialises a bitmap. | |
|
Action: | Query | |
Short: | Fills a bitmap with pre-initialised/default values prior to initialisation. | |
|
Method: | BlitArea() | ||||||||||||||||
Short: | Blits a rectangular area from one bitmap to another. | ||||||||||||||||
Arguments: |
| ||||||||||||||||
|
Method: | BlitStretch() | ||||||||||||||||||||
Short: | Blits a rectangular area from one bitmap to another with stretching. | ||||||||||||||||||||
Arguments: |
| ||||||||||||||||||||
|
Method: | DrawLine() | ||||||||||
Short: | Draws a line to a bitmap. | ||||||||||
Arguments: |
| ||||||||||
|
Method: | DrawPixel() | |||||||||
Short: | Draws a single pixel to a bitmap. | |||||||||
Arguments: |
| |||||||||
|
Method: | DrawRGBLine() | ||||||||||||||
Short: | Draws a line to a bitmap. | ||||||||||||||
Arguments: |
| ||||||||||||||
|
Method: | DrawRGBPixel() | ||||||||||
Short: | Draws a 24 bit pixel to a bitmap. | ||||||||||
Synopsis: | LONG XCoord, LONG YCoord, LONG Red, LONG Green, LONG Blue | ||||||||||
Arguments: |
| ||||||||||
|
Method: | DrawRGBRectangle() | ||||||||||||||||
Short: | Draws rectangles, both filled and unfilled. | ||||||||||||||||
Arguments: |
| ||||||||||||||||
|
Method: | DrawRectangle() | ||||||||||||
Short: | Draws rectangles, both filled and unfilled. | ||||||||||||
Arguments: |
| ||||||||||||
|
Method: | FlipBitmap() | |||||||
Short: | Flips a bitmap around the horizontal or vertical axis. | |||||||
Arguments: |
| |||||||
|
Method: | Flood() | ||||||||||
Short: | Fills a bitmap area with a specific colour. | ||||||||||
Arguments: |
| ||||||||||
|
Method: | ReadPixel() | |||||||
Short: | Reads a pixel's colour from the target bitmap. | |||||||
Arguments: |
| |||||||
|
Method: | ReadRGBPixel() | ||||||||||
Short: | Reads a pixel's RGB colour from the target bitmap. | ||||||||||
Arguments: |
| ||||||||||
|
Method: | SetClipRegion() | ||||||||||||
Short: | Sets a clipping region for a bitmap object. | ||||||||||||
Arguments: |
| ||||||||||||
|
Field: | AmtColours | |
Short: | The amount of colours in a bitmap object. | |
Type: | LONG | |
Status: | Read/Init | |
|
Field: | BitsPerPixel | |
Short: | The amount of bits per pixel | |
Type: | LONG | |
Status: | Read/Init | |
|
Field: | ByteWidth | |
Short: | The width of a bitmap in bytes. | |
Type: | LONG | |
Status: | Read | |
|
Field: | BytesPerPixel | |
Short: | The amount of bytes per pixel. | |
Type: | LONG | |
Status: | Read | |
|
Field: | ClipBottom | |
Short: | Defines the bottom-most edge of a bitmap's clipping region. | |
Type: | LONG | |
Status: | Read | |
|
Field: | ClipLeft | |
Short: | Defines the left-most edge of a bitmap's clipping region. | |
Type: | LONG | |
Status: | Read | |
|
Field: | ClipRight | |
Short: | Defines the right-most edge of a bitmap's clipping region. | |
Type: | LONG | |
Status: | Read | |
|
Field: | ClipTop | |
Short: | Defines the top-most edge of a bitmap's clipping region. | |
Type: | LONG | |
Status: | Read | |
|
Field: | ColourRGB | |
Short: | The background colour of a bitmap. | |
Type: | RGB | |
Status: | Read/Set | |
|
Field: | Data | |
Short: | Pointer to a bitmap's data area. | |
Type: | APTR | |
Status: | Read/Set | |
|
Field: | DataFlags | |
Short: | Defines the memory flags to use in allocating a bitmap's data area. | |
Type: | LONG | |
Prefix: | MEM | |
Status: | Read/Init | |
|
Field: | Flags | |||||||||||||||||||||||||||||
Short: | Optional flags. | |||||||||||||||||||||||||||||
Type: | LONG | |||||||||||||||||||||||||||||
Prefix: | BMF | |||||||||||||||||||||||||||||
Status: | Read/Init | |||||||||||||||||||||||||||||
|
Field: | Height | |
Short: | The height of a bitmap in pixels. | |
Type: | LONG | |
Status: | Read/Init | |
|
Field: | LineMod | |
Short: | The differential between each line in a bitmap. | |
Type: | LONG | |
Status: | Read | |
|
Field: | Opacity | |
Short: | Determines the translucency setting to use in drawing operations. | |
Type: | LONG | |
Status: | Read/Write | |
|
Field: | Palette | |
Short: | Points to a bitmap's colour palette. | |
Type: | struct RGBPalette * | |
Status: | Read/Set | |
|
Field: | PlaneMod | |
Short: | The differential between each bitmap plane. | |
Type: | LONG | |
Status: | Read | |
|
Field: | Position | |
Short: | The current read/write data position. | |
Type: | LONG | |
Status: | Read | |
|
Field: | Size | |
Short: | The total size of a bitmap in bytes. | |
Type: | LONG | |
Status: | Read | |
|
Field: | Type | |
Short: | Defines the data type of a bitmap. | |
Type: | LONG | |
Status: | Read/Init | |
|
Field: | Width | |
Short: | The width of a bitmap in pixels. | |
Type: | LONG | |
Status: | Read/Init | |
|