Platform-Independent Images

Most people would argue that this has no business in the main kernel library, and they may very well be right. However, I wanted this to be a standard part of KOS on any platform it got ported to so that you're guaranteed some platform-independet, device-dependent representation of images. This way, any image loader library that is ported to KOS can convert to this data format and it can be used by anything in the kernel that understands it (drivers, etc).

KOS doesn't try to put any limitations on what format the image may take; instead it tries to encapsulate most of the common formats you'd want to use in writing a game or demo and then provides an ``out'' for platform-specific things that are just too strange to be used elsewhere. A good example of this (though one which isn't actually used currently) would be the PVR2's ``twiddled'' textures. Some somewhat strange things that it does cover are inverted axis textures (e.g., for GL) and YUV formats for MPEG (tm) .

The majority of the PII system is just format specifications so that pieces have a common language to talk about the images. This includes a structure (kos_img_t) that contains a pointer to the raw data, width and height in pixels, and a format descriptor. The first three pieces are pretty self-explanatory, so I won't waste any time on those. However, the format descriptor deserves some attention.

The format descriptor is composed of two parts: the platform independent part, and the platform dependent part. Each of these parts is 16 bits wide. The platform independent part is further divided into a format specifier and standard flags. The format specifier may be one of:

• KOS_IMG_FMT_NONE - Undefined / Unknown
• KOS_IMG_FMT_RGB888 - Interleaved r/g/b/ bytes (24-bit)
• KOS_IMG_FMT_ARGB8888 - Interleaved a/r/g/b bytes (32-bit)
• KOS_IMG_FMT_RGB565 - r/g/b 5/6/5 (16-bit)
• KOS_IMG_FMT_ARGB4444 - a/r/g/b 4/4/4/4 (16-bit)
• KOS_IMG_FMT_ARGB1555 - a/r/g/b 1/5/5/5 (16-bit)
• KOS_IMG_FMT_PAL4BPP - Paletted (4-bits per pixel)
• KOS_IMG_FMT_PAL8BPP - Paletted (8-bits per pixel)
• KOS_IMG_FMT_YUV422 - y/u/v 4/2/2 (8-bit)
• KOS_IMG_FMT_BGR565 - b/g/r 5/6/5 (16-bit)
• KOS_IMG_FMT_RGBA8888 - r/g/b/a bytes (32-bit)

The attributes will be a bitmask with the following:

• KOS_IMG_INVERTED_X - The image is flipped along the X axis
• KOS_IMG_INVERTED_Y - The image is flipped along the Y axis (usually used with GL)

There is one function associated with the PII system currently:

• void kos_img_free(kos_img_t * img, int struct_also)

  Frees the image pointed to by img. If struct_also is non-zero, then the kos_img_t struct itself will also be freed. This function is to ensure future compatibility in code that calls libraries to allocate images and then needs to free them later itself.

Several macros are also available for tearing apart and putting together the format descriptor:

• KOS_IMG_FMT_I(x) - given a format descriptor x, return the platform independent part
• KOS_IMG_FMT_D(x) - given x, return the platform dependent part
• KOS_IMG_FMT(i,d) - given an independent part i and a dependent part d, return a full format descriptor

Note that KOS_IMG_FMT(KOS_IMG_FMT_I(x), KOS_IMG_FMT_D(x)) === x.

In the future, the PII system may also include functions to convert between image formats, but this hasn't been done yet.