Loads and saves picture files in a variety of different data formats.
The Picture class provides a standard API for programs to load picture files of any supported data type. It is future proof in that future data formats can be supported by installing class drivers on the user's system.
The default file format for loading and saving pictures is PNG. Other formats such as JPEG are supported via sub-classes, which can be loaded into the system at boot time or on demand. Some rare formats such as TIFF are also supported, but user preference may dictate whether or not the necessary driver is installed.
To find out general information about a picture before initialising it, 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.
Dynamically sized image formats like SVG will use the DisplayWidth and DisplayHeight values to determine the rendered image size.
The Picture class consists of the following fields:
Access | Name | Type | Comment | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Author | STRING | The name of the person or company that created the image. | |||||||||||||||||
| Bitmap | *Bitmap | Represents a picture's image data. | |||||||||||||||||
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. The Bitmap⇒Palette can 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 bitmap objects. | |||||||||||||||||||
| Copyright | STRING | Copyright details of an image. | |||||||||||||||||
Copyright details related to an image may be specified here. The copyright should be short and to the point, for example | |||||||||||||||||||
| Description | STRING | Long description for an image. | |||||||||||||||||
A long description for an image may be entered in this field. There is no strict limit on the length of the description. | |||||||||||||||||||
| Disclaimer | STRING | The disclaimer associated with an image. | |||||||||||||||||
If it is necessary to associate a disclaimer with an image, the legal text may be entered in this field. | |||||||||||||||||||
| DisplayHeight | INT | The preferred height to use when displaying the image. | |||||||||||||||||
The DisplayWidth and DisplayHeight fields define the preferred pixel dimensions to use for the display when viewing the image in a 96DPI environment. Both fields will be set automatically when the picture source is loaded. If the source does not specify a suitable value for these fields, they may be initialised to a value based on the picture's Bitmap⇒Width and Bitmap⇒Height. In the case of a scalable image source such as SVG, the DisplayWidth and DisplayHeight can be pre-configured by the client, and the loader will scale the source image to the preferred dimensions on load. | |||||||||||||||||||
| DisplayWidth | INT | The preferred width to use when displaying the image. | |||||||||||||||||
The DisplayWidth and DisplayHeight fields define the preferred pixel dimensions to use for the display when viewing the image in a 96DPI environment. Both fields will be set automatically when the picture source is loaded. If the source does not specify a suitable value for these fields, they may be initialised to a value based on the picture's Bitmap⇒Width and Bitmap⇒Height. In the case of a scalable image source such as SVG, the DisplayWidth and DisplayHeight can be pre-configured by the client, and the loader will scale the source image to the preferred dimensions on load. | |||||||||||||||||||
| Flags | PCF | Optional initialisation flags. | |||||||||||||||||
| |||||||||||||||||||
| Header | APTR | Contains the first 32 bytes of data in a picture's file header. | |||||||||||||||||
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. | |||||||||||||||||||
| Mask | *Bitmap | Refers to a Bitmap that imposes a mask on the image. | |||||||||||||||||
If a source picture includes a mask, the Mask field will refer to a Bitmap object that contains the mask image once the picture source has been loaded. The mask will be expressed as either a 256 colour alpha bitmap, or a 1-bit mask with 8 pixels per byte. If creating a picture from scratch that needs to support a mask, set the | |||||||||||||||||||
| Path | STRING | The location of source image data. | |||||||||||||||||
| Quality | INT | Defines the quality level to use when saving the image. | |||||||||||||||||
The quality level to use when saving the image is defined here. The value is expressed as a percentage between 0 and 100%, with 100% being of the highest quality. If the picture format is loss-less, such as PNG, then the quality level may be used to determine the compression factor. In all cases, the impact of selecting a high level of quality will increase the time it takes to save the image. | |||||||||||||||||||
| Software | STRING | The name of the application that was used to draw the image. | |||||||||||||||||
| Title | STRING | The title of the image. | |||||||||||||||||
The following actions are currently supported:
| Name | Comment | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Activate | Loads image data into a picture object. | |||||||||
ERR acActivate(*Object) Loading an image file requires a call to Activate() after initialisation. The Path field will be used to source the image file. Pre-setting picture field values will place restrictions on the image file that is to be loaded. For example, if the source image is wider than a preset 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. Manipulating the Bitmap object is permitted. | ||||||||||
| Init | Prepares the object for use. | |||||||||
ERR InitObject(*Object) Objects that belong to the Picture class can be initialised in two possible ways. If you have not set the Path field or have chosen to use the If you have set the Path field and avoided the | ||||||||||
| Query | Retrieves the latest information from an object. | |||||||||
| Read | Reads raw image data from a Picture object. | |||||||||
ERR acRead(*Object, APTR Buffer, LONG Length, LONG *Result)
| ||||||||||
| Refresh | Refreshes a loaded picture - draws the next frame. | |||||||||
| SaveImage | Saves the picture image to a data object. | |||||||||
ERR acSaveImage(*Object, OBJECTID Dest, CLASSID ClassID)
If no destination is specified then the image will be saved as a new file targeting Path. | ||||||||||
| SaveToObject | Saves the picture image to a data object. | |||||||||
ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)
| ||||||||||
| Seek | Seeks to a new read/write position within a Picture object. | |||||||||
ERR acSeek(*Object, DOUBLE Offset, LONG Position)
| ||||||||||
| Write | Writes raw image data to a picture object. | |||||||||
ERR acWrite(*Object, APTR Buffer, LONG Length, LONG Result)
| ||||||||||
Flags for the Picture class.
| Name | Description |
|---|---|
| PCF::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). |
| PCF::FORCE_ALPHA_32 | 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 FORCE_ALPHA_32 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. |
| PCF::LAZY | Prevents automatic loading of the picture image. Use the Query action to process the picture header or Activate to load the image data. |
| PCF::MASK | A mask has been generated for the image. |
| PCF::NEW | Indicates that the picture image will be created from scratch. |
| PCF::NO_PALETTE | Automatically upgrade palette based images to 32 bit colour. |
| PCF::SCALABLE | This read-only flag is automatically set if the image source is scalable (such as SVG). |
Class Info | |
|---|---|
| ID | ID_PICTURE |
| Category | Graphics |
| Include | modules/picture.h |
| Version | 1 |