Image Library
From OpenAlchemy.org
Image Library
The image library provides APIs to load and display images of various formats. Amida simputer applications can use this library in conjunction with Xlib or picowidget libraries.
Description
The image library presently supports the following image formats:
- JPEG
- GIF and animated GIF
- Windows BMP
- PNG
- XPM
In the library an image is represented with the following structure:
struct Image {
// Image information and data
unsigned short width, height; // Dimension of image
XImage *img, *mimg; // Image and its mask(if available)
unsigned char info; // Miscellaneous information about image
// The following attributes are only valid for animated GIFs
unsigned short delay; // 1/100 sec delay. Only for GIF imgs
unsigned short x, y; // Image anchor point within screen
unsigned char disposal; // Image disposal method for GIF imgs
// If not NULL, points to next image, in animated GIFs
struct Image *next;
};
- The image width and height are obtained from "width" and "height" fields of the structure respectively.
- The image and its mask(useful to display transparent images) are obtained from "img" and "mimg" fields respectively.
- Miscellaneous information about the image is stored in info.
Other structure members give information to display animated GIFs.
- The "delay" field gives the amount of time to wait between displaying images.
- In case of animated GIFs the image is a linked list. The "next" field points to the next image in the list. If this is NULL, then the image is not animated. Animated GIFs can have any number of images with various dimensions within it.
- Image disposal method for GIF images as described in the GIF89a specification available at http://www.w3.org/Graphics/GIF/spec-gif89a.txt
- These images should be shown at some offset, from the anchor point of the image.
The "x" and "y" give the offset. For images which are not animated, these fields will have a value of 0.
APIs
The image library provides the following three APIs:
- int pimg_load(char *filename, Display *disp, struct Image **simg, unsigned short iattr);
- int pimg_save(char *filename, Display *disp, struct Image **simg, int image format, unsigned quality);
- void pimg_free(struct Image **simg);
- int pimg_zoom(Display *disp, struct Image **input, struct Image **output, float xfact, float yfact);
The pimg_load function takes the image filename, the screen display, image structure and the desired attributes for the image returned.
The iattr argument takes SHAPE_MASK and returns the mask of the image in "mimg" field. If image mask is not required, 0 should be used.
This function returns 0 on success and the following codes on error. The error codes and the associated reasons are listed in the following table.
The pimg_save function takes the Image structure and saves it in a file "filename".
The "image_format" takes the following values: FORMAT_JPEG FORMAT_PNM. FORMAT_PNM is used for printing purposes. It is just a collection of RGB values. Quality is only valid for FORMAT_JPEG and takes a value between 1-100. This quality value is ignored for FORMAT_PNM.
The pimg_free function frees the memory used by the image structure.
The pimg_zoom function scales the image to the given xfact and yfact.
The scaled image is stored in output. xfact and yfact are the scale factor for width and height respectively.
| Error Code | Reason |
|---|---|
| ENOFILE | File passed is not present |
| ENOTIMG | File passed is not an image |
| EBIGIMG | Image file passed has dimension more than the limit |
| EBADIMG | Image is corrupted |
| ENOMEMR | Enough memory is not available to display image |
| ENOSUPP | Image format is not supported |
