Class Documentation
Picture |
1.0 |
ID_PICTURE |
Stable |
Graphics |
pandora/graphics/picture.h |
October 2003 |
Rocklyte Systems |
Rocklyte Systems, 1996-2003. All rights reserved. |
Loads and saves picture files in a variety of different data formats. |
Description
The purpose of the Picture class is to provide a standard interface that
any program can use to load picture files. The main advantage in using this
class is that the source picture can be in any file format recognised by the
user's system, so effectively your program will be able to support file
formats that it does not understand.
The default file format for loading and saving pictures is IFF, the other
formats (such as JPEG) are supported via sub-classes, which can be loaded into
the system at boot time or on demand. All Picture sub-classes are available
from the Rocklyte FTP file repository, which you can check if you need to know
what file formats are currently supported.
Technical Overview
The Picture class will clip any loaded picture so that it fits the size
given in the Bitmap's Width and Height. If you
specify the RESIZE flag, the
picture will be shrunk or enlarged to fit the given dimensions. If you
leave the Width and Height at NULL, then the picture will be loaded at its
default dimensions. If you need to find out general information about a
picture before initialising it, you may Query it first so that the picture
object can load initial details on the file format.
Images are also remapped automatically if the source palette and
destination palettes do not match, or if there are significant differences
between the source and destination bitmap types.
Actions
The Picture class supports the following actions:
Activate | Loads image data into a picture object. |
Init | Prepares picture objects for usage. |
Query | Reads information from a picture's file source and fills the object structure. |
Read | Reads raw image data from a Picture object. |
SaveImage | Saves a Picture image to a data object. |
SaveToObject | Saves a Picture image to a data object. |
Seek | Seeks to a new read/write position within a Picture object. |
Write | Writes raw image data to a Picture object. |
Structure
The Picture object consists of the following public fields:
Author | The name of the person or company that created the image. |
Bitmap | Represents a Picture's image data. |
Copyright | Copyright details of an image. |
Description | Long description for an image. |
Disclaimer | The disclaimer associated with an image. |
Flags | Optional initialisation flags. |
Header | Contains the first 32 bytes of data in a picture's file header. |
Location | The location of a Picture's image data. |
Software | The name of the application that was used to draw the image. |
Title | The title of the image. |
Activate |
Loads image data into a picture object. |
In order to load an image file into a picture object you will need to
Activate it after initialisation. So long as the Location
field refers to a recognised image file, it will be loaded into the picture
object and the fields will be filled out to reflect the image content.
If you have preset the values of certain fields prior to activation, you
will be placing restrictions on the image file that is to be loaded. For
example, if the source image is wider than a restricted Bitmap Width, the
image will have its right edge clipped. The same is true for the Bitmap
Height and other restrictions apply to fields such as the Bitmap Palette.
Once the picture is loaded, the image data will be held in the picture's
Bitmap object. You can draw to and from the Bitmap using its available
drawing methods.
|
|
Init |
Prepares picture objects for usage. |
Objects that belong to the Picture class can be initialised in two
possible ways. If you have not set the Location
field or have chosen to use the NEW Flag, the
initialisation routine will create a Bitmap area that
contains no image data. This allows you to fill the picture with your own
image data and save it using the SaveImage or SaveToObject actions. You must
set the Bitmap's Width, Height and colour specifications at a minimum, or
the initialisation process will fail.
If you have set the Location field and avoided
the NEW flag, the initialisation process will analyse the file location to
determine whether or not the data is in fact a valid image file. If the file
does not match up with a registered data format, an error code of
ERR_NoSupport is returned. You will need to use the Activate or Query
actions to load or find out more information about the image format.
|
|
Query |
Reads information from a picture's file source and fills the object structure. |
Calling this action will fill out the fields of a picture object according
to the image referred to in the Location field. This
includes information on the width, height, palette values, screen dimensions
and so on.
Fields that contain preset values will not be over-written by this
action.
|
|
Field: | Author |
Short: | The name of the person or company that created the image. |
Type: | STRING |
Status: | Get/Set |
The name of the person or organisation that created a Picture's image is
normally specified here. This provides a means for the original author to
claim credit for the image.
|
|
Field: | Bitmap |
Short: | Represents a Picture's image data. |
Type: | struct Bitmap * |
Status: | Read |
The details of a Picture's graphical image and data are defined in its
associated Bitmap object. It contains information on the image dimensions
and palette for example. When loading a Picture, you can place certain
constraints on the image by presetting Bitmap fields such as the Width and
Height (this will have the effect of clipping or resizing the source image).
The Palette can also be preset if you want to remap the source image to a
specific set of colour values.
Please refer to the Bitmap class for more
details on the structure of the Bitmap object.
|
|
Field: | Copyright |
Short: | Copyright details of an image. |
Type: | STRING |
Status: | Get/Set |
Copyright details related to an image may be specified here. The
copyright should be short and to the point, for example "Copyright H.R.
Giger (c) 1992. All rights reserved."
|
|
Field: | Description |
Short: | Long description for an image. |
Type: | STRING |
Status: | Get/Set |
A long description for an image may be entered in this field. There is
no strict limit on the length of the description. It is recommended that
this field be used to describe what the image is of.
|
|
Field: | Disclaimer |
Short: | The disclaimer associated with an image. |
Type: | STRING |
Status: | Get/Set |
If it is necessary to associate a disclaimer with an image, the legal
text may be entered in this field.
|
|
Field: | Flags |
Short: | Optional initialisation flags. |
Type: | LONG |
Prefix: | PCF |
Status: | Read/Init |
You can specify flags in this field that will affect the way that image
files are loaded. Valid flags are:
ALPHA | If a picture supports an alpha channel, this field will be set (if you will be saving a Picture with an alpha channel, set this flag prior to initialisation and build the channel using the object provided in the Mask field). |
NEW | If a picture is being created from scratch (i.e. you will not be loading any image data), set the NEW flag so that the initialisation process will not attempt to load any picture data. |
NOCOMPARE | When loading images of 256 colours or less, the picture code will automatically compare the image palette to the Picture's Bitmap Palette. If differences are found then the code will remap the picture by default. However, you may want to allow for differences in the palette, in which case you can set PCF_NOCOMPARE to stop palette comparisons. Please note that if you want to acquire the source palette prior to loading a picture, use the Query action prior to Activate. |
CACHE | Use the CACHE option to put the loaded bitmap image into a global cache. Any further picture objects that load the referenced image file will use the cached bitmap rather than re-loading the image data. |
32BITALPHA | If the picture source includes an alpha channel mask, it will normally be separated out and stored in the Mask field. If you set the 32BITALPHA option before loading, the image will be forced into 32-bit graphics mode with alpha channel. The mask information will be stored in the alpha byte and the Mask field will not be set. |
QUERY | This option may be set prior to loading an image in order to prevent the loading and decompression of the image data. Only the picture's information header will be processed. |
BACKGROUND | This flag is set automatically if a loaded image carries a background colour. The colour is indicated in the bitmap's ColourRGB field. |
|
|
Field: | Header |
Short: | Contains the first 32 bytes of data in a picture's file header. |
Type: | POINTER |
Status: | Get |
The Header field is a pointer to a 32 byte buffer that contains the first
32 bytes of information read from a picture file on initialisation. This
special field is considered to be helpful only to developers writing add on
components for the picture class.
The buffer that is referred to by the Header field is not populated until
the Init action is called on the picture object.
|
|
Field: | Location |
Short: | The location of a Picture's image data. |
Type: | STRING |
Status: | Get/Set |
This compulsory field must refer to a file that contains the image data
that you want to load.
|
|
Field: | Software |
Short: | The name of the application that was used to draw the image. |
Type: | STRING |
Status: | Get/Set |
The Software field declares the name of the application that was used to
draw or render the original image.
|
|
Field: | Title |
Short: | The title of the image. |
Type: | STRING |
Status: | Get/Set |
If the author of a picture has assigned a title to it, then it must be
declared through the Title field.
|
|