Image Module (IMG)

The image module provides functions that read and write image files. Several different file formats, such as Softimage PIC, Wavefront RLA, and mental ray's color, scalar, and vector textures are supported. When creating a file, the file format is specified and a file with that type is created. When opening or creating a file, a subset of types (the mental ray texture types) can be specified. If the file format differs, it is converted to and from that data type automatically. When reading, the file format is recognized automatically from the header (not from the file name extension).

When reading or writing scanlines, the caller has to deal with only a small number of scanline data types. A scanline is stored in one to four arrays of components (R, G, B, A, U, V, Z, N, T). All components have the same depth, either 8, 16, or 32 bits. The number of components and the number of bits per component depends on the image type specified when opening or creating the file.

The open, create, close, read, and write routines return miTRUE if the operation succeeded, and miFALSE if the operation failed. mi_img_err_msg returns nothing, it prints a message using the standard mi_error function.

Some image files are scanned top-down, others bottom-up. When reading from a file scanline-by-scanline, the lines will be presented in that order; when writing, the lines must be provided in that order. Lines are always read and written sequentially, there is no way to seek to a particular line (the run-length encoding of most file formats does not allow seeking). If an entire file is written at once, using the mi_img_file_read or mi_img_file_write routines, IMG takes care of the scanline order. Either way, reading and writing is always a three-step process: first, the image file is opened or created; second, the image data is read or written, respectively; and third, the image file is closed. Reading and writing entire files is the recommended method, there is usually nothing to be gained by line-by-line access.

Note that Quantel/Abekas YUV files can have only two resolutions, either 720x576 or 720x486. If a Quantel/Abekas file is written, it is either clipped or centered and padded with black margins. YUV means the file is stored with reduced chroma resolution; this results in image quality loss. IMG has no functions to resize or aspect-correct images.