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:
- read a file into memory;
- decode raw picture data and compose an image;
- 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 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
- 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.
- One of the Image.bppN constants from libimg.inc. Defines bit depth / internal representation of image.
- Pointer to the decoded data. If you apply any filters / modifications on picture, this is where to go.
- Pointer to the palette / 0. It makes sense only for indexed images (Image.bpp*i types).
- 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.
- Some hints to display an image. There is only Is.Animated flag for now. It distinguishes animated and multipage pictures.
- 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.
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.