Kōtuku Manual

Loads and saves image files in a variety of different data formats.

The Image class provides a standard API for programs to load image 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 images is PNG. Other formats such as JPEG are supported via derived 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 an image before initialising it, Query() it first so that the image 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 Image 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 image data.

The image graphics data is 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 image 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 image'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 an image supports an alpha channel, this field will be set (if you will be saving a Image 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 image 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 image. Use the Query action to process the image header or Activate to load the image data.
PCF::MASK	A mask has been generated for the image.
PCF::NEW	Indicates that the 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 INT8 [] Contains the first 32 bytes of data in an image's file header.

The Header field is a pointer to a 32 byte buffer that contains the first 32 bytes of information read from an image file on initialisation. This special field is considered to be helpful only to developers writing add on components for the image class.

The buffer that is referred to by the Header field is not populated until the Init action is called on the image object.

Mask *Bitmap Refers to a Bitmap that imposes a mask on the image.

If a source image includes a mask, the Mask field will refer to a Bitmap object that contains the mask image once the image 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 an image from scratch that needs to support a mask, set the MASK flag prior to initialisation and the image 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 image 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 an image 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 image 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 image is loaded, the image data will be held in the image's Bitmap object. Manipulating the Bitmap object is permitted.

Init Prepares the object for use.

ERR InitObject(*Object)

Objects that belong to the Image 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 image 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 an Image object.

ERR acRead(*Object, std::span<int8_t> Buffer, INT *Result)

Parameter	Description
Buffer	A mutable buffer that will receive the data.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

Refresh Refreshes a loaded image - draws the next frame.

SaveImage Saves the 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 Image 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 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 derived class that should be used when encoding the data.

Seek Seeks to a new read/write position within an Image 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 an image object.

ERR acWrite(*Object, std::span<const int8_t> Buffer, INT *Result)

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

Image Class

Technical Notes

Structure

Actions

PCF Type