impOpen(3) Impressario impOpen(3)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);
Page 1
impOpen(3) Impressario impOpen(3)
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:
Page 2
impOpen(3) Impressario impOpen(3)
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) */
Page 3
impOpen(3) Impressario impOpen(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).
Page 4
impOpen(3) Impressario impOpen(3)
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.
Page 5
impOpen(3) Impressario impOpen(3)
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 ALSOlibimp(3), impReadRow(3), impReadRowB(3), mmap(2)
Page 6
