Parasol Framework Manual

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.

Technical Notes

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.

Structure

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.

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.

Flags PCF Optional initialisation flags.

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).

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 MASK flag prior to initialisation and the picture class will allocate the mask bitmap automatically.

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.

Actions

The following actions are currently supported:

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 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⇒Width, Bitmap⇒Height and colour specifications at a minimum, or the initialisation process will fail.

If you have set the Path 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 Retrieves the latest information from an object.

Read Reads raw image data from a Picture object.

ERR acRead(*Object, APTR Buffer, INT Length, INT *Result)

Parameter	Description
Buffer	Points a buffer that will receive the data.
Length	The total number of bytes to read from the object. This value cannot exceed the size of the Buffer.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

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)

Parameter	Description
Dest	Refers to an object that will receive the encoded image data.
ClassID	The Picture class to use for encoding the image data.

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)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

Seek Seeks to a new read/write position within a Picture object.

ERR acSeek(*Object, DOUBLE Offset, INT Position)

Parameter	Description
Offset	The desired offset to seek to, relative to the Position parameter.
Position	The position that defines the starting point for Offset.

Write Writes raw image data to a picture object.

ERR acWrite(*Object, APTR Buffer, INT Length, INT Result)

Parameter	Description
Buffer	A buffer containing the data that will be written to the object.
Length	The total number of bytes to write to the object.
Result	This parameter with be updated with the total number of bytes written from the Buffer.

Picture Class

Technical Notes

Structure

Actions

PCF Type