Parasol Framework
  • Gallery
  • API
  • Wiki
  • GitHub
    • Audio
    • Core
    • Display
    • Fluid
    • Font
    • Network
    • Vector
    • Audio
    • Sound
    • File
    • MetaClass
    • Module
    • StorageDevice
    • Task
    • Thread
    • Time
    • Compression
    • Config
    • Script
    • XML
    • Controller
    • BlurFX
    • ColourFX
    • CompositeFX
    • ConvolveFX
    • DisplacementFX
    • FilterEffect
    • FloodFX
    • ImageFX
    • LightingFX
    • MergeFX
    • MorphologyFX
    • OffsetFX
    • RemapFX
    • SourceFX
    • TurbulenceFX
    • WaveFunctionFX
    • Scintilla
    • ScintillaSearch
    • Bitmap
    • Clipboard
    • Display
    • Document
    • Font
    • Picture
    • Pointer
    • Surface
    • SVG
    • ClientSocket
    • HTTP
    • NetSocket
    • Proxy
    • Vector
    • VectorClip
    • VectorColour
    • VectorEllipse
    • VectorFilter
    • VectorGradient
    • VectorGroup
    • VectorImage
    • VectorPath
    • VectorPattern
    • VectorPolygon
    • VectorRectangle
    • VectorScene
    • VectorShape
    • VectorSpiral
    • VectorText
    • VectorTransition
    • VectorViewport
    • VectorWave

Picture Class

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
NameTypeComment
  AuthorSTRINGThe name of the person or company that created the image.
  Bitmap*BitmapRepresents 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.

  CopyrightSTRINGCopyright 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 Copyright J. Bloggs (c) 1992.

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

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

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

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

  FlagsPCFOptional initialisation flags.
NameDescription
PCF::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).
PCF::FORCE_ALPHA_32If 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::LAZYPrevents automatic loading of the picture image. Use the Query action to process the picture header or Activate to load the image data.
PCF::MASKA mask has been generated for the image.
PCF::NEWIndicates that the picture image will be created from scratch.
PCF::NO_PALETTEAutomatically upgrade palette based images to 32 bit colour.
PCF::SCALABLEThis read-only flag is automatically set if the image source is scalable (such as SVG).
  HeaderAPTRContains 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*BitmapRefers 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.

  PathSTRINGThe location of source image data.
  QualityINTDefines 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.

  SoftwareSTRINGThe name of the application that was used to draw the image.
  TitleSTRINGThe title of the image.

Actions

The following actions are currently supported:

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

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

QueryRetrieves the latest information from an object.
ReadReads raw image data from a Picture object.
ERR acRead(*Object, APTR Buffer, INT Length, INT *Result)
ParameterDescription
BufferPoints a buffer that will receive the data.
LengthThe total number of bytes to read from the object. This value cannot exceed the size of the Buffer.
ResultThe Read action will write this parameter with the total number of bytes read into the Buffer.
RefreshRefreshes a loaded picture - draws the next frame.
SaveImageSaves the picture image to a data object.
ERR acSaveImage(*Object, OBJECTID Dest, CLASSID ClassID)
ParameterDescription
DestRefers to an object that will receive the encoded image data.
ClassIDThe 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.

SaveToObjectSaves the picture image to a data object.
ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)
ParameterDescription
DestRefers to an object that will receive the encoded data.
ClassIDCan refer to a sub-class that should be used when encoding the data.
SeekSeeks to a new read/write position within a Picture object.
ERR acSeek(*Object, DOUBLE Offset, INT Position)
ParameterDescription
OffsetThe desired offset to seek to, relative to the Position parameter.
PositionThe position that defines the starting point for Offset.
WriteWrites raw image data to a picture object.
ERR acWrite(*Object, APTR Buffer, INT Length, INT Result)
ParameterDescription
BufferA buffer containing the data that will be written to the object.
LengthThe total number of bytes to write to the object.
ResultThis parameter with be updated with the total number of bytes written from the Buffer.
Picture class documentation © Paul Manias © 2001-2025

PCF Type

Flags for the Picture class.

NameDescription
PCF::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).
PCF::FORCE_ALPHA_32If 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::LAZYPrevents automatic loading of the picture image. Use the Query action to process the picture header or Activate to load the image data.
PCF::MASKA mask has been generated for the image.
PCF::NEWIndicates that the picture image will be created from scratch.
PCF::NO_PALETTEAutomatically upgrade palette based images to 32 bit colour.
PCF::SCALABLEThis read-only flag is automatically set if the image source is scalable (such as SVG).
Picture module documentation © Paul Manias © 2001-2025