Libs-dev/libimg

Libimg is a system library that provides functions to decode, encode, transform and display raster images. It handles bmp, png, jpeg, gif, ico/cur, tga, pcx, xcf, wbmp, tiff (baseline + some extentions), pnm (pbm, pgm, ppm) and xbm formats in 1/2/4/8/15/16/24/32 bpp modes. Bilevel (monochrome), grayscale, indexed and (A)RGB (full color) images are supported.

This article covers basic libimg structure and logic, which are worth to know both for its developers and users.

The central thing in libimg understanding is 'Image' structure located in libimg.inc. All the time you are writing libimg related code you should keep an eye on this structure, because what the library means by image is not a picture file or decoded and ready-to-display data, it is always 'Image' structure. In what follows, the word image is always used in this sense.

Let's take a closer look at how raw on-disk data becomes lighting pixels. There are three main stages in this proccess:

1. read a file into memory;
2. decode raw picture data and compose an image;
3. display image.

To be clear, libimg cares only about two last phases. This means your program should allocate memory block for raw data itself. Free that memory is also for you to do.

Loading a file into memory is usually done using 70th kernel function or file.read function of libio. Read corresponding board thread / manual article / source file / wiki page / whatever for more information. You can also find a very simple and useful example of how to load and display a graphic file (libio + libimg) on our svn repo.

Since you have raw data in memory, libimg functions are at your service. They could be logically divided into three groups:

• main/core functions: img.decode, img.encode, img.draw, img.destroy

these are, probably, all you should know to use libimg in most trivial way

• transforms: img.rotate, img.flip, img.scale, img.convert

functions to rotate, flip and scale pictures obviously; img.convert changes internal image representation (say, bit depth)

• private/service functions: img._.*

they are not exported and so make any sense for libimg developers only

More detailed description of libimg API can be found in Libs-dev/libimg_api.

Ok then. Do you still remember that 'Image' structure? You can always find its up-to-date version in libimg.inc file, but here it is.

struct Image
  Checksum dd ? ; ((Width ROL 16) OR Height) XOR Data[0]
  Width    dd ?
  Height   dd ?
  Next     dd ?
  Previous dd ?
  Type     dd ? ; one of Image.bppN
  Data     dd ?
  Palette  dd ? ; only for Image.bpp*i image types
  Extended dd ?
  Flags    dd ? ; bitfield
  Delay    dd ? ; used iff Image.IsAnimated is set in Flags
ends

Checksum

Never mind. Nobody uses it. It was meant to mean something, but never happened.

Width, Height

In pixels.

Next, Previous

These fields are used for multiframe images, i.e. animations (gif) and icon sets (cur/ico). The values allowed are 0 / pointer to image.

Type

One of the Image.bppN constants from libimg.inc. Defines bit depth / internal representation of image.

Data

Pointer to the decoded data. If you apply any filters / modifications on picture, this is where to go.

Palette

Pointer to the palette / 0. It makes sense only for indexed images (Image.bpp*i types).

Extended

Pointer to any-you-want structure. This may be used to store some application / format specific information, i.e. layer shift or blending mode for multilayer images and so on. Extended field is initialized to zero, but the memory it points to (if any) is freed by img.destroy.

Flags

Some hints to display an image. There is only Is.Animated flag for now. It distinguishes animated and multipage pictures.

Delay

How long to wait before the next frame. Ignored if Is.Animated flag is reset.

If you just want to call some libimg functions from your application, look at Libs-dev/libimg_using page.

The library has module structure, so it is easy to add support of your favorite image format to libimg (if not yet) or make any other improvements. For more details see Libs-dev/libimg_developing.

Since you are familiar now with libimg ideas, pay more attention to examples on svn. Program code will always be the most concise and up-to-date information source on any programming subject.