While a file is open, its information is stored in an miImg_file structure, similar to the FILE structure used in stdio. This is the primary data structure of the image module, in addition to the image data itself. Unlike stdio, the caller of IMG has to allocate this structure, it is not allocated by the open and create routines. This permits storage of error information after the file has been closed, and in case the open or create failed. The following file information is available in the miImg_file struct, after mi_img_open or mi_img_create succeeded:
typedef struct miImg_file {
int null; /* bomb out if someone forgets & */
/* --------------- public --------- */
int width, height; /* width and height in pixels */
int bits; /* requested bits per component, 8/16*/
int comp; /* requested components/pixel, 1..4 */
miBoolean filter; /* caller wants filtered lookups */
miBoolean topdown; /* read file top-down */
int filesize; /* if reading, size of file in bytes */
float gamma; /* gamma correction value (read only)*/
float aspect; /* aspect/xres*yres (for .pic output)*/
float parms[8]; /* additional undefined parameters, */
/* [0] is .jpg quality: 0..100
* or .exr compression type:
* 0=default, 1=none, 2=piz,
* 3=zip, 4=rle, 5=pxr24, 6=b44 */
/* [1] is .pic field: 1=even, 2=odd */
/* [2] scaling factor for filters */
/* - For multi-buffer formats (EXR)
* store buffertag. */
/* [3] whether IFF has extra Z. */
/* [4] DOD tag for IFF */
/* [5] typemap for EXR */
/* [6] DPI for IFF, TIF, JPG */
miImg_type type; /* requested miIMG_TYPE_* */
miImg_format format; /* if reading, file format */
miImg_error error; /* one of miIMG_ERR_*, or 0 */
int os_error; /* copy of Unix's errno, or 0 */
/* --------------- private --------- */
int magic; /* magic number while file is open */
int lineno; /* current line# to be read/written */
miBoolean writing; /* if nz, file is open for writing */
miCBoolean swap_map; /* swap if memory-mapping */
miUint1 ftype; /* actual file data type, should */
/* be cast to miImg_type. this is */
/* set internally in mi_img_create */
/* from miImg_file.type */
miCBoolean writable; /* writable texture (eg. light map) */
miUint1 pyr_level; /* open map file, level to rd, 0=std */
miPointer fp; /* open file descriptor, 0 if closed */
miPointer real_name; /* complete path (for unlink/local) */
miPointer convline; /* converted line if type != format */
miPointer data; /* more format-dependent file info*/
/* or map address for .map files */
char name[64]; /* file name (for error messages) */
miTag colorprofile; /* color space of image data */
miCBoolean win_error; /* os_error is GetLastError code */
miCBoolean is_texture; /* image is a texture */
miCBoolean spare2[2];
int spare[12]; /* makes sizeof(miImg_file) 256 bytes */
} miImg_file;
The actual definition of miImg_file contains more internal information that should not be accessed by other modules. gamma is available only when reading from RLA or RLB files. When writing or reading from other types, gamma will always be 1.0. format is one of miIMG_FORMAT_*, it can be used for determining the file format when a file is opened with type miIMG_TYPE_ANY. type is a copy of the internal data type specified as an argument to mi_img_open or mi_img_create. ftype is used when the current type differs from best_type of current format. This is usually the case for formats which support more than one data type. This value normally isn't used outside IMG. The writable flag is set for writable textures, typically used for light mapping.
parms provides place to supply additional parameters to mi_img_create. The actual meaning of these values is not predefined. Currently, the miIMG_FORMAT_JPEG format interprets the first parameter as compression quality value. os_error fields are provided in case the application does its own error reporting; normally, the mi_img_err_msg call should be used for error reporting. Pyramidal filtering is activated if the filter field is set to miTRUE.
A scanline is stored in a scanline data structure. It consists of a header with four indices, followed by one, two, three, or four component scanlines. A component scanline is a sequence of unsigned chars, unsigned shorts, unsigned longs, or floats (depending on the data type) describing one component (red, green, blue, alpha, or whatever else the data type demands) for the entire scanline. Shorts are in network byte order, MSB first. The indices in the header give the offset to the first byte of the respective component scanline, relative to the first byte of the header.
typedef struct {
int c[4];
} miImg_line;
The application chooses an index with one of the following constants:
| miIMG_R | red channel, 8, 16, or 32 bits |
| miIMG_G | green channel, 8, 16, or 32 bits |
| miIMG_B | blue channel, 8, 16, or 32 bits |
| miIMG_A | alpha (matte) channel, 8, 16, or 32 bits |
| miIMG_S | scalar, 8, 16, or 32 bits |
| miIMG_U | U vector, 16 bits |
| miIMG_V | V vector, 16 bits |
| miIMG_Z | Z coordinate, float |
| miIMG_T | tag channel, unsigned long |
| miIMG_NX | normal vector X component, float |
| miIMG_NY | normal vector Y component, float |
| miIMG_NZ | normal vector Z component, float |
There is no data type for which more than four of the above are valid at any time, which is why four indices suffice. If an index is 0, there is no corresponding component scanline; a valid index must always be at least equal to the size of the header (16 bytes). For example, to assign a pointer to the Y component of a scanline of normal vectors and then accessing the xth pixel, use
float *normal_y = (float *)((char *)line + line->c[miIMG_NY); float ny = normal_y[x];
In most cases, the image module is used to access entire images. There is a data structure that can be allocated by the image module that contains all scanlines of the file in one block of memory. This data structure consists of a global header, one scanline header for each scanline, and a list of component scanlines:
#define miIMG_DIRSIZE 20 /* image filters have max 20 levels */
typedef struct miImg_image {
miScalar filter; /* filtered lookups if > 0 */
int dirsize; /* valid # of filter levels */
int dir[miIMG_DIRSIZE]; /* offs from this to other imgs */
int width, height; /* width and height in pixels */
int bits; /* requested bits per comp, 8/16/32 */
int comp; /* requested components/pixel, 1..4 */
miCBoolean local; /* local texture, use image/mmap/path*/
miCBoolean writable; /* writable texture (eg. light map) */
miCBoolean cacheable; /* cache in parts */
miCBoolean spare; /* unused */
int type; /* requested miIMG_TYPE_* */
miTag real_name; /* (local) file name to open */
int null[1]; /* unused */
int c[4]; /* scanline directory */
} miImg_image;
The header contains copies of the respective fields from the
corresponding ifp file handle. Local textures do not use
the scanline index array c; instead, information about the
actual file is stored. When the image is later accesses, this
information is used to read or map the file and set up the
image pointer to point to the actual image structure that
contains the image data. The component scanline index array is
actually allocated larger; it 4*width indices
for height scanlines, not just for one scanline as shown.
Again, the indices contain offsets from the beginning of the data
structure to the first byte of the component scanline.
Deprecated There are convenience macros to access a component scanline. For example, to access the green component of the xth pixel of scanline y, use one of the following:
miUchar *line_g = (miUchar *)((char *)image + image->c[4*y + miIMG_G]); miUchar pix_g = line_g[x]; miUchar pix_g = (miUchar *)((char *)image + image->c[4*y + miIMG_G])[x]; miUchar *line_g = miIMG_ACCESS(image, y, miIMG_G); miUchar pix_g = line_g[x]; miUchar pix_g = miIMG_ACCESS(image, y, miIMG_G)[x];The access macro interprets local textures, does all the necessary indirection and accepts a coordinate and a component. It must always be cast to the proper pointer type if a component other than an 8-bit color component is accessed; by default it returns an miUchar pointer. image is assumed to be a pointer to miImg_image. (For a description of miImg_image, see the SCENE chapter.) miIMG_ACCESS does not work on single scanlines (type miImg_line); a separate macro miIMG_LINEACCESS that has no middle (line number) argument is provided for that purpose. The macros are no longer recommended because they don't work with texture tiling.
The fields filter, dirsize, and dir are used internally for pyramidal texture filtering and should not be accessed by other modules. With filter the magnification/minification calculation can be scaled if necessary. A pyramidal image structure contains a hierarchy of down-scaled images, each level stored in the dir field. The number of levels depends on the size of the image in the finest resolution. There is no restriction on the image resolutions.
The writable flag is set for writable textures. The cacheable flag is used by mental ray internally to manage the texture cache, and should not be manipulated.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.