impOpen(3)
impOpen, impOpenFd, impOpenBuf, impOpenExt, impOpenFdExt, impOpenBufExt, impClose, impCloseFd - open/close SGI Image Format files
Showing IRIX 6.5.30 (default release). Last changed in IRIX 6.5.5.
NAME impOpen, impOpenFd, impOpenBuf, impOpenExt, impOpenFdExt, impOpenBufExt, impClose, impCloseFd - open/close SGI Image Format files SYNOPSIS #include <imp.h> IMPImage* impOpen(const char *fname, const char *mode, ...); IMPImage* impOpenFd(int fd, const char *mode, ...); IMPImage* impOpenBuf(void *buf, const char *mode, ...); IMPImage* impOpenExt(const char *fname, const char *mode, off_t offset, IMPCacheMode cache, ...); IMPImage* impOpenFdExt(int fd, const char *mode, off_t offset, IMPCacheMode cache, ...); IMPImage* impOpenBufExt(void *buf, const char *mode, off_t offset, ...); int impClose(IMPImage *image); int impCloseFd(IMPImage *image, int *fdp); In write mode impOpen, impOpenFd, impOpenExt and impOpenFdExt require that these additional parameters be specified: uint_t rasterType, uint_t dimension, uint_t xSize, uint_t ySize, uint_t numChannels, uint_t imageType, char *name where uint_t stands for unsigned int. DESCRIPTION The libimp library provides a number of different functions to open an SGI Image Format file. The impOpen, impOpenFd, impOpenExt and impOpenFdExt functions each open an SGI Image Format file for reading or writing. impOpen opens the image file specified by fname. If mode is "r", the file is opened for reading. If mode is "w" the file is opened for writing and created if it does not exist or truncated to zero length if it does exist. IMPImage* impOpen(const char *fname, "r"); IMPImage* impOpen(const char *fname, "w", uint_t rasterType, uint_t dimension, uint_t xSize, uint_t ySize, uint_t numChannels, uint_t imageType, char *name); Excess arguments to impOpen over the above are ignored. impOpenFd opens the image file pointed to by the file descriptor fd. The descriptor's permissions must permit the operations specified by mode. That is, if mode is "w", the descriptor must have write permission. In addition, it must be possible to seek on the specified descriptor. At this time read/write mode is not supported for SGI Image files. Upon successful execution both functions return a pointer to an SGI Image file structure. If impOpen or impOpenFd open an image file for writing, a number of additional parameters must be specified. rasterType Specifies both the raster encoding method and the number of bytes per pixel per channel. SGI Image Format files can be written either uncompressed or with run length encoding compression and with one or two bytes per pixel per channel. Refer to imp.h for the supported raster types. dimension Specifies the number of dimensions in the image. A colormap file will have dimension one. A black and white image will have dimension two and an RGB image will have dimension three. xSize, ySize Specifies the image size in pixels. numChannels Specifies the number of image color channels. A black and white image has one channel while an RGB image has three channels. imageType Specifies how the image data is to be interpreted. Image data is either actual color values (normal), screen colormap indices (screen) or a colormap (colormap). Refer to imp.h for the supported image types. name Specifies a descriptive string for the image. Strings longer than IMP_NAME_MAX characters will be truncated. Refer to imp.h for the value of IMP_NAME_MAX. If this parameter is specified as NULL, the string "no name" will be written into the file. Use the empty string "" to write an empty name string into the image. The impOpenExt and impOpenFdExt functions also open an image file but in addition allow an offset and image cache mode to be specified. The offset is the number of bytes into the file where the image is to be read or written. The cache mode is used only during image reading and specifies how the image data is to be accessed for subsequent reads. The value of the cache mode is ignored when in writing mode (the mode is implicitly IMPNoCache). The cache mode may be one of: IMPNoCache Do not cache the image data. All subsequent image reads will be done from the disk file or descriptor. IMPHeapCache Cache the image data in storage allocated from the heap. All subsequent image reads will be done from the data stored in the heap cache. IMPMapCache Memory map the image file. All subsequent image reads will use the memory mapping facility to reference the image data. The impOpenBuf and impOpenBufExt functions allow reading an SGI Image that is already in memory. Writing of the image is not currently supported by these two functions. The buffer specified in the call to impOpenBuf and impOpenBufExt must not be deallocated until impClose has been called. impClose closes an SGI Image Format file previously opened by impOpen or impOpenFd. Among other tasks, impClose closes the file descriptor associates with image file if appropriate. If the image was opened using impOpenFd or impOpenFdExt, the file descriptor specified in that function call will be closed by impClose. impCloseFd performs the same function as impClose but it leaves open the file descriptor associated with the image and returns it in the parameter fdp. It then becomes the responsibility of the caller to close the file descriptor when it is no longer needed. It is essential that either impClose or impCloseFd be called at the completion of writing an SGI Image file so that all buffered data can be written and the image header can be updated. When an image has been opened using impOpenBuf or impOpenBufExt either close function may be used. If impCloseFd is used, -1 is returned as the file descriptor. The IMPImage structure contains public and private information about an SGI Image file. This structure is identical both in size and field naming to the IMAGE structure defined in the header file image.h included by application that use the libimage library. While it has been common practice to directly modify the public fields of the image structure, this is not recommended. Macros are defined in imp.h for manipulating the structure fields. It is strongly recommended that these macros be used to set and get values from the image structure. The IMPImage structure is defined as follows. typedef struct _impImage { /******* Public image header information (archived) */ ushort_t imagic; /* SGI Image file magic number */ ushort_t type; /* Raster type (e.g. verbatim, rle) */ ushort_t dim; /* Image dimension */ ushort_t xsize; /* X size (pixels) */ ushort_t ysize; /* Y size (pixels) */ ushort_t zsize; /* Number of channels (e.g. rgb = 3) */ __int32_t min; /* Minimum intensity in image */ __int32_t max; /* Maximum intensity in image */ __uint32_t wastebytes; /* Padding */ char name[IMP_NAME_MAX+1]; /* Image name */ __uint32_t colormap; /* Image type (e.g. colormap, normal) */ /******* Private image header information (core use only) */ __int32_t file; ushort_t flags; short dorev; short x; short y; short z; short cnt; short *ptr; short *base; short *tmpbuf; __uint32_t offset; __uint32_t rleend; __uint32_t *rowstart; __int32_t *rowsize; off_t start; IMPCacheMode cache; void* cachebuf; __uint32_t cachesize; off_t cacheoffset; } IMPImage; where ushort_t is unsigned short, __int32_t is a 32-bit integer and __uint32_t is a 32-bit unsigned integer. magic Magic number identifying this file as an SGI Image Format file. type Bitwise OR combined code indicating the raster encoding method and the number of bytes per pixel per channel. Currently, SGI Image files support either a verbatim, uncompressed, raster encoding or a run length, compressed, encoding. Both of these encodings are available at one or two bytes per pixel per channel. The header file imp.h defines codes for all supported combinations of encoding methods and pixel widths. dim Number of dimensions to the image. A colormap file has dimension one (i.e. length). A black and white image has dimension two (i.e. height and width) and an RGB image has dimension three (i.e. height, width and depth). xsize, ysize Image size in pixels. zsize Number of color channels or depth. A black and white image has one channel while an RGB image has three channels. min, max The minimum and maximum intensity values in the image. These values are the minimum and maximum for all channels combined. name A descriptive name string for the image. colormap The image type. Refer to imp.h for the supported image type codes. The field is named colormap for compatibility with the IMAGE structure used by the libimage library. RETURN VALUE All image open function return a pointer to an image structure if execution was successful. NULL is returned and IMPerrno is set if an execution error has occurred. impClose and impCloseFd return 0 if execution was successful. -1 is returned and IMPerrno is set if an execution error has occurred. EXECUTION ERROR CODES In addition to the system error codes defined in errno.h, the following libimp specific error codes may be returned. All image open functions will fail under the following circumstances. IMP_ERR_READWRITE Read/write mode is not supported. IMP_ERR_MEMALLOC Dynamic memory allocation failed. This indicates an out-of-memory condition. IMP_ERR_BADMAGIC Bad magic number in image file header. The file may not be and SGI Image Format file. IMP_ERR_BADRASTER Unrecognized raster encoding method. Refer to imp.h for supported raster encodings. IMP_ERR_BADIMAGE Unrecognized image type. Refer to imp.h for supported image types. In addition, impOpenFd and impOpenFdExt will fail under the following circumstances. IMP_ERR_BADFD The specified file descriptor is invalid. IMP_ERR_SEEK A seek cannot be performed on the specified file descriptor. impOpenBuf and impOpenBufExt may also return the following error code. IMP_ERR_NOWRITE Writing mode not allowed by the function. impClose and impCloseFd will fail under the following circumstances. IMP_ERR_WRITEFLAG Attempt to write to an image file not opened for writing. IMP_ERR_BADBPP Unsupported bytes per pixel value. Refer to imp.h for supported BPP values. IMP_ERR_BADIMAGE Unrecognized image type. Refer to imp.h for supported image types. NOTE The storage for the IMPImage structure is allocated by the image open function. This storage is deallocated by the impClose and impCloseFd functions. The caller should not explicitly reallocate or deallocate any storage related to the image structure. SEE ALSO libimp(3), impReadRow(3), impReadRowB(3), mmap(2)