Class Documentation
Picture |
1.0 |
ID_PICTURE |
Unspecified |
Graphics |
May 2001 |
Rocklyte Systems |
Rocklyte Systems, 1996-2001. 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. 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 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. |
Query | Reads information from a Picture's file source and fills the object structure. |
Read | Reads raw image data from a Picture 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:
Bitmap | Represents a Picture's image data. |
Flags | Optional initialisation flags. |
Location | The location of the picture file. |
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.
|
|
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
function.
|
|
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: | Flags |
Short: | Optional initialisation flags. |
Type: | LONG |
Status: | Read/Init |
You can specify flags in this field that will affect the way that image
files are loaded. Valid flags are:
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 IMG_NOCOMPARE to stop palette comparisons. |
REMAP | This flag remaps the source image to fit the palette you have specified in the Bitmap Palette field. Keep in mind that this will be done automatically if the two palettes differ (refer to the NOCOMPARE flag). For this reason the flag is somewhat redundant for most programmers and really serves its purpose internally. |
RESIZEX RESIZEY | These flags resize the Picture so that it fits the given Bitmap->Width and Height. If the flags are not used then the picture borders will be clipped if they do not fit within the Bitmap borders. For a quick way to set both flags at once, use the IMG_RESIZE flag. |
|
|
Field: | Location |
Short: | The location of the picture file. |
Type: | STRING |
Status: | Read/Write |
This compulsory field must refer to a file that contains the image data
that you want to load.
|
|