IMAGEFILE(2)

NAME

imagefile: readgif, readjpg, readpicfile, readxbitmap, remap − processing external image file formats

SYNOPSIS

include "imagefile.m";
gifreader := load RImagefile RImagefile->READGIFPATH;
jpgreader := load RImagefile RImagefile->READJPGPATH;
xbmreader := load RImagefile RImagefile->READXBMPATH;
picreader := load RImagefile RImagefile->READPICPATH;
imageremap := load Imageremap Imageremap->PATH;
Rawimage: adt
{
    r:         Draw->Rect;
    cmap:      array of byte;
    nchans:    int;
    chans:     array of array of byte;
    chandesc: int;
     init:      fn(bufio: Bufio);
    read:      fn(fd: ref Bufio->Iobuf): (ref Rawimage, string);
    readmulti: fn(fd: ref Bufio->Iobuf):
                (array of ref Rawimage, string);
};
init:          fn(bufio: Bufio);
writeimage:    fn(fd: ref Bufio->Iobuf, image: ref Draw->Image)
                                : string;
remap:         fn(i: ref RImagefile->Rawimage, d: ref Draw->Display,
                errdiff: int): (ref Draw->Image, string);

DESCRIPTION

The Rawimage adt of module RImagefile defines an internal representation and routines for reading images such as GIF and JPEG files. To read a set of files of a given format, load the appropriate module, pass its init function an implementation of the Bufio module, and pass read an Bufio->Iobuf for each file. Read returns a tuple: a ref Rawimage that holds the image and an error string. If the Rawimage is nil, the error string will report the reason. Files (particularly GIF files) are often incorrectly encoded but yield usable pictures, so even if a Rawimage is returned, the error string may still report problems.

Some image file types (eg, GIF) support having several images in a single file. They can be read in all at once using readmulti, which returns a tuple with the array of images, and an error string as above.

The Rawimage is always defined as one or more bytes per pixel, with nchans channels of data stored in the array chans. The chandesc field, described below, specifies the contents of chans. The rectangle r describes the shape of the picture.

The Rawimage type can be converted to a regular Image (see draw-image(2)) by calling module Imageremap’s function remap. Remap is passed the Rawimage, a Display on which to create the image, and a flag that specifies whether to apply Floyd-Steinberg error diffusion code to the result, for smoother rendering of colours at the cost of some noise in the image.

How to remap is defined by the RImagefile itself: the field chandesc specifies the type of the various chans of data: RImagefile->CRGB specifies a 3-colour RGB image with no colour map; RImagefile->CY a monotone (luminance-only, grey-scale) image with no colour map; and RImagefile->CRGB1 a single-channel image with RGB colour map in cmap. The file readers set chandesc as appropriate for the format of the file.

The writing of image files is defined by the module WImagefile. To initialize the module, call its init function with an instance of the Bufio module and pass its writeimage function a Bufio->Iobuf representing the output stream and an image of type Draw->Image.

These functions are split into separate modules to give applications control over the memory they need to process images.

SOURCE

/appl/lib/readgif.b
/appl/lib/readjpg.b
/appl/lib/readxbitmap.b
/appl/lib/readpicfile.b

NOTES

The JPEG reader handles only the Baseline sequential format as defined by the JFIF 1.02 file exchange format.

Functions to write these formats are as yet unimplemented.