OpenKODE Core extension: KD_ATX

OpenKODE Core extension: KD_ATX_imgdec

Name	ATX_imgdec
Name strings	KD_ATX_imgdec
Contributors	Russell Wood, Phil Huxley, Elizabeth Wootten, Tim Renouf
Contacts	Antix Labs Limited
Status	Implemented by Antix Labs
Version	Version 5, 2009-02-04
Number	10
Dependencies	Requires OpenKODE Core 1.0. This extension is written based on the wording of the OpenKODE Core 1.0 specification.

1. Overview

This OpenKODE Core extension provides functions for decoding an image that is stored in a file.

Functions are provided to decode enough of an image file to obtain information on the image, and to decode the whole image file. The result of both types of function is a KDImageATX handle to an image object. Other functions are then used to retrieve the image information, including a pointer to the decoded image buffer.

When decoding an image, the caller specifies an output format. This extension introduces the notion of compressed versus uncompressed output formats, however all the output formats defined in this extension are uncompressed.

This extension does not provide support for any particular input image formats, so by itself cannot actually decode an image. Further extensions define the support for particular input image formats. Some of these may also add further output formats. Not all combinations of input format and output format can be used.

2. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/ATX_imgdec.h>

3. New types

type	description
`KDImageATX`	The opaque representation of a decoded image or image information object, used as a handle in image decoder function calls.

4. New functions

4.1. kdGetImageInfoATX, kdGetImageInfoFromStreamATX

Construct an informational image object based on an image in a file or stream.

Synopsis

KDimageATX kdGetImageInfoATX( const KDchar * pathname);

KDimageATX kdGetImageInfoFromStreamATX( KDFile * file);

Description

These functions read and decode enough of an image file, to obtain information on the image without loading the image data itself. The functions return a KDImageATX object containing only information on the image; this is known as an informational image object.

For kdGetImageInfoATX, the function reads the image from a file whose name is pathname. The function opens the file as if by kdFopen with a mode of rb, and, before returning, closes it again as if by kdFclose.

For kdGetImageInfoFromStreamATX, the function uses an already-open file handle file, which must be open for reading and (if it makes any difference on the implementation) in binary mode, and must be positioned at the start of the image file. On return, the file handle will be positioned at the same point, with the file error indicator cleared.

The implementation supports a list of image file formats, each with an associated file extension. For kdGetImageInfoATX, where pathname has one of those extensions, the function tries the decoder for the format associated with that extension first, and then all other file formats (in an undefined order), until one succeeds. Otherwise, and in any case for kdGetImageInfoFromStreamATX, the function tries all file formats until one succeeds (in an undefined order).

This extension does not itself define any image file formats. They are defined by other extensions that depend on this one.

If pathname is not a readable null-terminated string, or file is not an open file, then undefined behavior results.

Return Value

On success, the functions return a handle to the informational image object, but with no image data attached to it. On failure they return KD_NULL and stores one of the error codes below into the error indicator returned by kdGetError.

Error codes

kdGetImageInfoATX can give any error that can be given by kdFopen and kdFclose, except KD_EINVAL and KD_ENOSPC. Both functions can give these errors:

KD_EILSEQ: The image file was invalid, or of an unsupported type.
KD_EIO: I/O error.
KD_ENOMEM: The operation failed due to insufficient memory.

4.2. kdGetImageATX, kdGetImageFromStreamATX,

Read and decode an image from a file or stream, returning a decoded image object.

Synopsis

`KDimageATX kdGetImageATX(`	const KDchar *	`pathname`,
	KDint	`format`,
	KDint	`flags)`;

`KDimageATX kdGetImageFromStreamATX(`	KDFile *	`file`,
	KDint	`format`,
	KDint	`flags)`;

Description

These functions read and decode an image from a file, creating a KDImageATX object with image data attached. This is known as a decoded image object.

For kdGetImageATX, the function reads the image from a file whose name is pathname. The function opens the file as if by kdFopen with a mode of rb, and, before returning, closes it again as if by kdFclose.

For kdGetImageFromStreamATX, the function uses an already-open file handle file, which must be open for reading and (if it makes any difference on the implementation) in binary mode, and must be positioned at the start of the image file. On return, the file handle will be positioned at the same point, with the file error indicator cleared.

The implementation supports a list of image file formats, each with an associated file extension. For kdGetImageATX, where pathname has one of those extensions, the function tries the decoder for the format associated with that extension first, and then all other file formats (in an undefined order), until one succeeds. Otherwise, and in any case for kdGetImageFromStreamATX, the function tries all file formats until one succeeds (in an undefined order).

This extension does not itself define any image file formats. They are defined by other extensions that depend on this one.

On entry, format gives the image format that the image is to be decoded to, one of the following values. An output format is either compressed or uncompressed. Note that not all input format and output format combinations are supported; the specification of an input format details what output formats are allowed with it.

KD_IMAGE_FORMAT_RGBA8888_ATX

#define KD_IMAGE_FORMAT_RGBA8888_ATX 121

This uncompressed format stores 4 components in increasing addresses in the order: 8-bit red, 8-bit green, 8-bit blue, and 8-bit alpha.

Alignment of buffers for all levels is 4 byte.

KD_IMAGE_FORMAT_RGB888_ATX

#define KD_IMAGE_FORMAT_RGB888_ATX 128

This uncompressed format stores 3 components in increasing addresses in the order: 8-bit red, 8-bit green, and 8-bit blue.

Alignment of buffers for all levels is 1 byte.

KD_IMAGE_FORMAT_RGB565_ATX

#define KD_IMAGE_FORMAT_RGB565_ATX 129

This uncompressed format specifies KDuint16 pixels, starting from the most significant bits consists of the following components: 5-bit red, 6-bit green, and 5-bit blue.

Alignment of buffers for all levels is 2 byte.

KD_IMAGE_FORMAT_RGBA5551_ATX

#define KD_IMAGE_FORMAT_RGB5551_ATX 130

This uncompressed format specifies KDuint16 pixels, starting from the most significant bits consists of the following components: 5-bit red, 5-bit green, 5-bit blue, and 1-bit alpha.

Alignment of buffers for all levels is 2 byte.

KD_IMAGE_FORMAT_RGBA4444_ATX

#define KD_IMAGE_FORMAT_RGBA4444_ATX 131

This uncompressed format specifies KDuint16 pixels, starting from the most significant bits consists of the following components: 4-bit red, 4-bit green, 4-bit blue, and 4-bit alpha.

Alignment of buffers for all levels is 2 byte.

KD_IMAGE_FORMAT_BGRA8888_ATX

#define KD_IMAGE_FORMAT_BGRA8888_ATX 132

This uncompressed format stores 4 components in increasing addresses in the order: 8-bit blue, 8-bit green, 8-bit red, and 8-bit alpha.

Alignment of buffers for all levels is 4 byte.

KD_IMAGE_FORMAT_ALPHA8_ATX

#define KD_IMAGE_FORMAT_ALPHA8_ATX 133

This uncompressed format consists of the following components: 8-bit alpha.

Alignment of buffers for all levels is 1 byte.

KD_IMAGE_FORMAT_LUM8_ATX

#define KD_IMAGE_FORMAT_LUM8_ATX 134

This uncompressed format consists of the following components: 8-bit luminance.

Alignment of buffers for all levels is 1 byte.

KD_IMAGE_FORMAT_LUMALPHA88_ATX

#define KD_IMAGE_FORMAT_LUMALPHA88_ATX 135

This uncompressed format stores 2 components in increasing addresses in the order: 8-bit luminance, 8-bit alpha.

Alignment of buffers for all levels is 2 byte.

KD_IMAGE_FORMAT_COMPRESSED_ATX

#define KD_IMAGE_FORMAT_COMPRESSED_ATX 122

This value of format instructs the function to use the appropriate compressed output format that matches the input format, as defined for the input format.

Alignment of buffers and whether the KD_IMAGE_FLAG_FLIP_X_ATX and KD_IMAGE_FLAG_FLIP_Y_ATX flags are ignored are as defined by the particular compressed output format that is used. The value of the resulting image’s KD_IMAGE_FORMAT_ATX attribute (as retrieved by kdGetImageIntATX) reflects the (compressed) output format actually used.

On entry, flags is a combination of zero or more of the following:

KD_IMAGE_FLAG_FLIP_X_ATX

#define KD_IMAGE_FLAG_FLIP_X_ATX 1

Indicates that the order of image pixels in each line should be reversed. This flag has the stated effect for an uncompressed output format; for a compressed output format, whether this flag has an effect is defined with the output format.

KD_IMAGE_FLAG_FLIP_Y_ATX

#define KD_IMAGE_FLAG_FLIP_Y_ATX 2

Indicates that the order of image lines should be reversed top to bottom. This flag has the stated effect for an uncompressed output format; for a compressed output format, whether this flag has an effect is defined with the output format.

The created KDImageATX object has a KD_IMAGE_FORMAT_ATX attribute whose value (retrievable using kdGetImageIntATX) is the requested format, unless specified otherwise for the particular image format decoder used.

If pathname is not a readable null-terminated string, or file is not an open file, then undefined behavior results.

Return Value

On success, the functions return a handle to the decoded image object. On failure they return KD_NULL and store one of the error codes below into the error indicator returned by kdGetError.

Error codes

kdGetImageATX can give any error that can be given by kdFopen and kdFclose, except KD_EINVAL and KD_ENOSPC. Both functions can give these errors:

KD_EILSEQ: The image file was invalid, or of an unsupported type.
KD_EINVAL: format is not a recognized output format.
KD_EIO: I/O error.
KD_ENOMEM: The operation failed due to insufficient memory.

Rationale: uncompressed output formats

The uncompressed output formats specified above correspond to formats used in OpenGL ES and in the EGL_KHR_lock_surface extension as follows:

KD_ATX_imgdec format	OpenGL ES format	OpenGL ES type	EGL_KHR_lock_surface format
KD_IMAGE_FORMAT_RGBA8888_ATX	GL_RGBA	GL_UNSIGNED_BYTE
KD_IMAGE_FORMAT_BGRA8888_ATX	GL_BGRA_EXT	GL_UNSIGNED_BYTE	EGL_FORMAT_RGBA_8888_EXACT_KHR
KD_IMAGE_FORMAT_RGBA4444_ATX	GL_RGBA	GL_UNSIGNED_SHORT_4_4_4_4
KD_IMAGE_FORMAT_RGBA5551_ATX	GL_RGBA	GL_UNSIGNED_SHORT_5_5_5_1
KD_IMAGE_FORMAT_RGB888_ATX	GL_RGB	GL_UNSIGNED_BYTE
KD_IMAGE_FORMAT_RGB565_ATX	GL_RGB	GL_UNSIGNED_SHORT_5_6_5	EGL_FORMAT_RGB_565_EXACT_KHR
KD_IMAGE_FORMAT_LUM8_ATX	GL_LUMINANCE	GL_UNSIGNED_BYTE
KD_IMAGE_FORMAT_LUMALPHA88_ATX	GL_LUMINANCE_ALPHA	GL_UNSIGNED_BYTE
KD_IMAGE_FORMAT_ALPHA8_ATX	GL_ALPHA	GL_UNSIGNED_BYTE

4.3. kdFreeImageATX

Free image object.

Synopsis

void kdFreeImageATX( KDImageATX image);

Description

This function releases all resources associated with the image whose handle is image. The image object is no longer valid and cannot be used in any other function calls after this function call has started. Users should endeavor to free up the image as soon as it is no longer required.

If image is not a valid image object handle, then undefined behavior results.

4.4. kdGetImagePointerATX

Get the value of an image pointer attribute.

Synopsis

`void *kdGetImagePointerATX(`	KDImageATX	`image`,
	KDint	`attr)`;

Description

This function retrieves a pointer attribute for the image object whose handle is image. attr identifies the attribute to retrieve, one of:

KD_IMAGE_POINTER_BUFFER_ATX

#define KD_IMAGE_POINTER_BUFFER_ATX 112

For a decoded image object, the returned value is a pointer to the first byte of the buffer containing the image, which remains valid until the image object is destroyed.

For an informational image object, the returned value is KD_NULL. This is not an error.

If image is not a valid image object handle, then undefined behavior results.

Return Value

On success, the function returns the value of the attribute. On failure it returns KD_NULL and stores one of the error codes below into the error indicator returned by kdGetError.

Error codes

KD_EINVAL: attr is not a valid pointer attribute.

4.5. kdGetImageIntATX, kdGetImageLevelIntATX

Get the value of an image integer attribute.

Synopsis

`KDint kdGetImageIntATX(`	KDImageATX	`image`,
	KDint	`attr)`;

`KDint kdGetImageLevelIntATX(`	KDImageATX	`image`,
	KDint	`attr`,
	KDint	`level)`;

Description

These functions retrieve an integer attribute for the image object whose handle is image.

kdGetImageIntATX retrieves the value of an attribute associated with the whole image file.

kdGetImageLevelIntATX retrieves the value of an attribute associated with a particular mipmap level. The level parameter specifies which mipmap level: 0 indicates the top-level image, and n indicates the nth following mipmap.

attr identifies the attribute to retrieve, one of:

KD_IMAGE_WIDTH_ATX

#define KD_IMAGE_WIDTH_ATX 113

Width of image, in pixels.

KD_IMAGE_HEIGHT_ATX

#define KD_IMAGE_HEIGHT_ATX 114

Height of image, in pixels.

KD_IMAGE_FORMAT_ATX

#define KD_IMAGE_FORMAT_ATX 115

Pixel format of the image.

For a decoded image object, the value of this attribute is the requested format, except as otherwise noted where the output format is defined.

For an informational image object, the value of this attribute is one of:

KD_IMAGE_FORMAT_RGB_ATX

#define KD_IMAGE_FORMAT_RGB_ATX 136

Undecoded image contains only red, green and blue information. Such an image file can be decoded by kdGetImageATX or kdGetImageFromStreamATX to any uncompressed output format.

KD_IMAGE_FORMAT_RGBA_ATX

#define KD_IMAGE_FORMAT_RGBA_ATX 137

Undecoded image contains red, green, blue and alpha information. Such an image file can be decoded by kdGetImageATX or kdGetImageFromStreamATX to any uncompressed output format.

KD_IMAGE_FORMAT_PALETTED_ATX

#define KD_IMAGE_FORMAT_PALETTED_ATX 138

Undecoded image contains indexed palette pixels. Such an image file can be decoded by kdGetImageATX or kdGetImageFromStreamATX to any uncompressed output format.

KD_IMAGE_FORMAT_LUMINANCE_ATX

#define KD_IMAGE_FORMAT_LUMINANCE_ATX 139

Undecoded image contains grayscale pixels. Such an image file can be decoded by kdGetImageATX or kdGetImageFromStreamATX to any uncompressed output format.

KD_IMAGE_FORMAT_LUMALPHA_ATX

#define KD_IMAGE_FORMAT_LUMALPHA_ATX 140

Undecoded image contains grayscale and alpha pixels. Such an image file can be decoded by kdGetImageATX or kdGetImageFromStreamATX to any uncompressed output format.

KD_IMAGE_STRIDE_ATX

#define KD_IMAGE_STRIDE_ATX 116

Stride of image, in bytes. Zero is returned for a compressed output format or for an informational image object.

KD_IMAGE_BITSPERPIXEL_ATX

#define KD_IMAGE_BITSPERPIXEL_ATX 117

Size of one pixel of image, in bits. Zero is returned for a compressed output format.

KD_IMAGE_LEVELS_ATX

#define KD_IMAGE_LEVELS_ATX 118

This number is zero if only the top-level image is stored. If n mipmaps follow the top-level image then the value of this attribute is n.

KD_IMAGE_DATASIZE_ATX

#define KD_IMAGE_DATASIZE_ATX 119

For a decoded image object, the value of this attribute is the size in bytes of the entire image buffer including any mipmaps.

For an informational image object, the value of this attribute is the size in bytes of the undecoded file or stream.

KD_IMAGE_BUFFEROFFSET_ATX

#define KD_IMAGE_BUFFEROFFSET_ATX 120

For a decoded image object, the value of this attribute is the offset in bytes of the image data for mipmap level level in the image buffer. This is zero if level is zero or if kdGetImageInt is used.

For an informational image object, the value of this attribute is zero.

KD_IMAGE_ALPHA_ATX

#define KD_IMAGE_ALPHA_ATX 141

For a decoded image object, the value of this attribute is non-zero if and only if the output format contains an alpha channel.

For an informational image object, the value is non-zero if and only if the undecoded image has alpha information.

If image is not a valid image object handle, then undefined behavior results.

Return Value

On success, the functions return the value of the attribute. On failure they return 0 and stores one of the error codes below into the error indicator returned by kdGetError.

Error codes

KD_EINVAL: attr is not a valid integer attribute, or level is not a valid mipmap level number for the image.

5. New image file formats

This extension adds a new section Image file formats to the OpenKODE Core specification, but leaves it empty for further extensions to add to, other than the following text:

There follows a list of image file formats supported by kdGetImageATX, kdGetImageFromStreamATX, kdGetImageInfoATX and kdGetImageInfoFromStreamATX.

6. Revision history

6.1. Version 5, 2009-02-04

Allocated extension number 10.

6.2. Version 4, 2008-09-16

Allocated extension number 8.

6.3. Version 3, 2008-06-20

Draft of version prepared to release to OpenKODE WG.