Class Documentation

Name:Picture
Version:1.0
ID:ID_PICTURE
Status:Stable
Category:Graphics
Include:pandora/graphics/picture.h
Date:October 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2003. All rights reserved.
Short:  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.
Action:Activate
Short: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.


Action:Init
Short: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.


Action:Query
Short: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:

FlagDescription
ALPHAIf 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).
NEWIf 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.
CACHEUse 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.
32BITALPHAIf 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.
QUERYThis 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.
BACKGROUNDThis 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.