VIPER REFERENCE MANUAL


NAME
iflFile - abstraction for image file access

HEADER FILE
#include <ifl/iflFile.h>

PUBLIC METHOD SUMMARY

   Open/create/close methods
static iflFile* open ( iflFileDesc& fileDesc, int mode=O_RDONLY, iflStatus* status=NULL);
static iflFile* open ( int fd, const char* filename, int mode=O_RDONLY, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* open ( const char* filename, int mode=O_RDONLY, iflStatus* status=NULL);
static iflFile* create ( const char* filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* create ( int fd, const char* filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* create ( iflFileDesc& fileDesc, iflFile* source, const iflFileConfig* cfg=NULL, iflStatus* status=NULL);
iflStatus close ( int flags=0);
virtual iflStatus flush (  );
static char* parseFileName ( const char* fullname, char** formatName=NULL, int* index=NULL, char** formatArgs=NULL);

   Image data access
iflStatus getTile ( int x, int y, int z, int nx, int ny, int nz, void* data, const iflConfig* config=NULL);
iflStatus setTile ( int x, int y, int z, int nx, int ny, int nz, const void* data, const iflConfig* config=NULL);
virtual iflStatus getPage ( void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc);
virtual iflStatus setPage ( const void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc);

   Manipulating the current image index
virtual int getNumImgs (  );
virtual int getCurrentImg (  );
virtual iflStatus setCurrentImg ( int idx);

   Adding images
virtual iflStatus appendImg ( iflFile* source, iflFileConfig* fc=NULL);

   Attribute query and set
const char* getFileName (  );
int getFileDesc (  );
int getFileMode (  );
iflFormat* getFormat (  );
iflColorModel getColorModel (  );
int* getChannelPermutation (  );
void getDimensions ( iflSize& dimensions);
void getSize ( iflSize& sz, iflOrientation toOrientation);
int getZsize (  );
int getCsize (  );
iflDataType getDataType (  );
iflOrder getOrder (  );
void getPageDimensions ( iflSize& pageDims);
void getPageSize ( iflSize& sz, iflOrientation toOrientation);
iflOrientation getOrientation (  );
iflCompression getCompression (  );
virtual iflStatus getColormap ( const iflColormap*& cmap);
virtual iflStatus getStatMinMax ( double& min, double& max);
virtual iflStatus getScaleMinMax ( double& min, double& max);
virtual iflStatus setColormap ( const iflColormap* cmap);
virtual iflStatus setStatMinMax ( double min, double max);
virtual iflStatus setScaleMinMax ( double min, double max);

   Format specific attributes
iflStatus getTag ( int tag, ...);
iflStatus getTagV ( int tag, va_list ap);
iflStatus setTag ( int tag, ...);
iflStatus setTagV ( int tag, va_list ap);
int haveAttributesChanged (  );

   Deprecated versions
iflStatus getItem ( int tag, ...);
virtual iflStatus getItem ( int tag, va_list ap);
iflStatus setItem ( int tag, ...);
virtual iflStatus setItem ( int tag, va_list ap);

   ICC profile access
iflStatus getICCProfile ( int& size, void*& profile);
iflStatus freeICCProfile ( void* profile);
iflStatus setICCProfile ( int size, const void* profile);

   Direct I/O support
iflStatus enableDirectIO ( int enable=TRUE);
iflStatus getDirectIOMemAlignment ( size_t& memAlign);

   Multiprocessing support
void setBeginFileIO_CB ( iflStatus(* cb)(void*), void* arg);
void setEndFileIO_CB ( iflStatus(* cb)(void*), void* arg);

PROTECTED METHOD SUMMARY

   Creating and destroying
iflFile (  );
virtual ~iflFile (  );
void markAttributesChanged (  );

   File argument parsing
int parseArguments ( iflParameterDesc* params, int maxParams);
static int lookupName ( const char* name, const iflNameDesc* names);

   Multiprocessing support
iflStatus beginFileIO (  );
iflStatus endFileIO (  );

   Implementing opening, closing and creating
virtual iflStatus openFile (  );
virtual iflStatus createFile (  );
virtual iflStatus closeFile (  );

   Implementing ICC public methods
virtual iflStatus _getICCProfile ( int& size, void*& profile);
virtual iflStatus _freeICCProfile ( void* profile);
virtual iflStatus _setICCProfile ( int size, const void* profile);

   Implementing direct I/O public methods
virtual iflStatus _enableDirectIO ( int enable=TRUE);
virtual iflStatus _getDirectIOMemAlignment ( size_t& memAlign);

PROTECTED MEMBER SUMMARY

   Attributes that never change after open or create
char* filename;
int fd;
int accessmode;
iflFormat* format;
char* formatArgs;

   Attributes that may change when sub-image changes
iflSize size;
iflDataType dtype;
iflOrder order;
iflSize pageSize;
iflColorModel cm;
iflOrientation orientation;
iflCompression compression;

CLASS DESCRIPTION
iflFile is an abstraction of a handle to an image file. It is an abstract base class; every iflFile object is actually an object of a file-format-specific subclass such as iflTIFFFile.

   Creating and destroying
An IFL application opens a file by calling iflFile::open() (to open an existing image file) or iflFile::create() (to create a new image file). The returned value is an iflFile* pointing to a newly created object of the appropriate subclass (one of iflTIFFFile, etc.). The file can be manipulated by calling the object's member functions. The object can be destroyed by calling the close() member function. Buffered data is automatically flushed during the close(), but the application may elect to explicitly flush at any time by calling flush().

This is the only public interface to construction and destruction of iflFile objects. There is no public constructor or destructor for this class or any of its subclasses. It is illegal to create an iflFile on the stack.

   Accessing image data
Several member functions are used by an IFL application to read image data from an image file into memory, or to write image data from memory to an image file.

The most general and usual interface is to use getTile() and setTile(), which allow reading and writing of arbitrary rectangular regions (tiles), with an arbitrary data type, dimension ordering, and orientation.

Optimized applications may want to use the lower-level getPage() and setPage() interface, which does no conversion and requires the specified region to be one of the file's natural pages.

The IFL library implements getTile() and setTile() in terms of getPage() and setPage(), which are defined by the format-specific subclasses of iflFile.

   Accessing sub-images
An image file can contain more than one image, depending on the file format. For example, the TIFF and GIF formats allow a file to contain any number of unrelated images, and the Kodak Photo CD Image Pac (PCD) and JFIF formats allow access to multiple resolutions of the same image. Both of these situations are handled by the notion of an iflFile object's "current image index". Image operations and queries applied to an iflFile object refer to the image at the current index.

The application can change the index by calling the object's setCurrentImg() method. The current index and total number of images in the file can be queried by calling the getCurrentImg() or getNumImgs() method, respectively. The initial index may also be set by specifying an index with the filename argument to iflFile::open() (see the description of that function above).

Note that these operations are meaningful even if the file format does not support multiple images per file. In that case, getNumImgs() returns 1, getCurrentImg() returns 0, and setCurrentImg(idx) will succeed if and only if idx == 0.

If an image file is open for write access and the file format and format-specific implementation supports it, the application can append an image to an image file by calling the appendImg() member function.

   ICC profiles
An ICC (International Color Consortium) profile can be used for color management; see http://www.color.org for more details on the specifics of how such profiles are used. To access the profile for those formats that support it, call getICCProfile(). When you are done with the profile call freeICCProfile() to release any allocated memory. You can update the profile of an image by calling setICCProfile().

The GIF, TIFF, JFIF and SGI formats included with IFL all support ICC profiles. New formats must implement the virtual methods listed above in order to provide ICC profile support.

   Format-specific operations
The member functions getTag() and setTag() deal with "tagged items"; that is, format-dependent name-value pairs associated with an image within an image file.

Usage of these functions requires format-specific knowledge of the meaning of the tags for the specific file format; e.g. for iflTIFFFile, the meaning of the tags is given in the TIFF spec.

In previous releases of IFL these methods were named getItem() and setItem(). Those versions are now deprecated. A problem was discovered in the use of overloading for the two forms of each method; for example, calling:
    tiffFile->setItem(TIFFTAG_IMAGEDESCRIPTION, "Some string");
would actually resolve to the form that expects a 'va_list' as the second argmument (va_list is a synonym for char*).

The old methods are retained to ensure backwards source and binary compatibility, and in fact classes that derive from iflFile must still define the virtuals setItem()/getItem() to provide the getTag/setTag functionality.

   Dealing with concurrent accesses
If an IFL application is going to make concurrent calls to an iflFile's getPage() and/or setPage() methods, it must provide the iflFile object with a semaphore mechanism. The application does this by supplying a beginFileIO callback with setBeginFileIO_CB() (which should acquire a semaphore) and an endFileIO callback with setEndFileIO_CB() (which should release the semaphore). These callbacks will be called by getPage() and setPage() surrounding thread-unsafe code.

See the next section for the DSO implementor's interface to this mechanism.

DERIVING SUBCLASSES
iflFile subclass implementors must surround code that needs to be executed atomically with calls to the protected beginFileIO() and endFileIO() member functions (which call the application's beginFileIO and endFileIO callbacks, respectively, if they exist).

The most common and unavoidable case is when getPage or setPage contain an lseek() and a subsequent read() or write(); this code must be surrounded by beginFileIO() and endFileIO() to insure that concurrent calls don't change the I/O pointer between the seek and the read or write.

If the underlying setPage() and getPage() code is completely non-MP-safe, the implementor may choose to surround the entire function bodies with beginFileIO() and endFileIO().

   Creating and destroying
The IFL library's functions open(), create() and close() methods call the openFile(), createFile() and closeFile() protected virtual functions to perform the subclass-specific initialization and destruction of an iflFile object. These functions are not accessible to the application.

If you install ifl_dev.sw.gifts then you can check out the source code provided in /usr/share/src/ifl for more examples of deriving from iflFile.

METHOD DESCRIPTIONS

   iflFile()
iflFile (  );

The protected default constructor, called implicitly in derived-class constructors, initializes itself to an empty state.

   ~iflFile()
virtual ~iflFile (  );

The destructor is never called directly, use close() instead.

   _enableDirectIO()
virtual iflStatus _enableDirectIO ( int enable=TRUE);

Enables direct I/O reads/writes for the underlying file. The return value is iflOKAY if successful or an appropriate iflStatus error value on failure. Image files with a page size that do not correspond to the required direct I/O transfer size will revert to using the file system's buffer cache.

   _freeICCProfile()
virtual iflStatus _freeICCProfile ( void* profile);

Frees the value returned by getICCProfile()

   _getDirectIOMemAlignment()
virtual iflStatus _getDirectIOMemAlignment ( size_t& memAlign);

Returns the memory alignment requirements for pages read using direct I/O read/writes. Pages that are not properly aligned will revert to using the buffer cache for their file operations. The return value is iflOKAY if successful or an appropriate iflStatus error value on failure.

   _getICCProfile()
virtual iflStatus _getICCProfile ( int& size, void*& profile);

Returns the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   _setICCProfile()
virtual iflStatus _setICCProfile ( int size, const void* profile);

Sets the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   appendImg()
virtual iflStatus appendImg ( iflFile* source, iflFileConfig* fc=NULL);

This virtual member function appends an image to the image file, and sets the current image index to the index of the new (last) image.

The source and fc parameters are treated the same as in the create() static member function.

On success, the function returns iflOKAY. If the operation fails for some reason, an IFL error will be thrown via the iflError mechanism, and the file's contents and the object's current index will be in an unknown state.

   beginFileIO()
iflStatus beginFileIO (  );

Calls the beginFileIO callback that was set by the application by a previous call to setBeginFileIO_CB(), and returns the returned value. If no callback was set, just returns iflOKAY.

   close()
iflStatus close ( int flags=0);

This member function flushes any buffered data to the file referred to by the object (unless IFL_CLOSE_DISCARD is specified in the flags argument), closes the file, and destroys the object. This is the only way for the application to destroy an iflFile object (there is no public destructor).

Note that the file descriptor will be closed even if it was opened prior to the original iflFile::open() or iflFile::create(). If the caller wants to keep the file descriptor open, it must dup() the file descriptor beforehand and use the resulting file descriptor as the argument to the original iflFile::open() or iflFile::create().

Then flags parameter is the bitwise "or" of zero or more of the following:

IFL_CLOSE_DISCARD
The default behavior is to call the flush() member function before closing the file. This flag suppresses that call.

All three operations (flushing, closing, destroying the object) are performed regardless of whether any of them returns failure. If an error is returned from any of them, the first such error value will be returned up the caller; otherwise iflOKAY will be returned.

   closeFile()
virtual iflStatus closeFile (  );

This virtual function is called by iflFile::close() after flushing (if appropriate). It is never called unless an openFile() or createFile() succeeded.

Its responsibility is to free any resources that were allocated by openFile() or createFile(), and to close the file descriptor (whether or not it was opened by openFile() or createFile()).

On success, closeFile() should return iflOKAY. If any part of the cleanup fails, it should continue and clean up as much else as possible, and return an iflStatus indicating what went wrong.

Warning: when calling the system function close(), be sure to invoke it as ::close() to avoid mistakenly calling iflFile::close().

   create()
static iflFile* create ( const char* filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* create ( int fd, const char* filename, iflFile* source, const iflFileConfig* cfg=NULL, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* create ( iflFileDesc& fileDesc, iflFile* source, const iflFileConfig* cfg=NULL, iflStatus* status=NULL);

This static class member function creates a new image file with the specified name and attributes.

The filename argument specifies the file name of the file to be created. An existing file descriptor may be given additionally or instead using the fd parameter, exactly as for open().

The format argument specifies the desired output format. If this argument is NULL, a format is selected by the file typing rules using the filename's extension. If no match is found, the format iflFormat::findByFormatName("TIFF") is used by default.

The alternate form taking a fileDesc argument, encapsulates the fd, filename and format arguments in this single argument. See iflFileDesc for more details.

The new image file's dimensions, data type, dimension order, color model, orientation, compression, and page dimensions may be specified using the cfg parameter; if not, they are copied from the source iflFile* if one was given (as described below) or defaulted to the format's "preferred" value for the respective parameter.

When an existing source iflFile* is specified; any parameters not specified in the cfg parameter will be copied from this source iflFile (if the value is supported by the destination format) or heuristically selected to be a supported value most suitable for copying data from the source iflFile*.

On successful completion, the function returns a pointer to a newly-created object of the appropriate subclass of iflFile, which the application should eventually destroy using its close() method.

On failure, the function returns NULL and, if the status argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value.

   createFile()
virtual iflStatus createFile (  );

This virtual function is called by iflFile::create() after all the read-only attributes have been set to non-zero values (zero means "don't care") that are supported according to the appropriate iflFormat subclass's is...Supported() functions. (Note that, even though the individual attributes are guaranteed to be supported values already, this function may need to check the values to make sure that the aggregate is supported.)

Its responsibility is to create the file and set fd (if fd is -1).

On success, createFile() should return iflOKAY. On failure, createFile() should return an appropriate error value and free any resources it allocated (including closing the file descriptor if it opened it) since closeFile() will not be called on an object for which openFile() failed.

Warning: when calling the system function open(), be sure to invoke it as ::open() to avoid mistakenly calling iflFile::open().

   enableDirectIO()
iflStatus enableDirectIO ( int enable=TRUE);

Enables direct I/O reads/writes for the underlying file. The return value is iflOKAY if successful or an appropriate iflStatus error value on failure. Image files with a page size that do not correspond to the required direct I/O transfer size will revert to using the file system's buffer cache.

   endFileIO()
iflStatus endFileIO (  );

Calls the endFileIO callback that was set by the application by a previous call to setEndFileIO_CB(), and returns the returned value. If no callback was set, just returns iflOKAY.

   flush()
virtual iflStatus flush (  );

This virtual member function is used to write out any data that is buffered in the iflFile object. It is called automatically by the close() member function (but this can be overridden, see description of close() above).

It should return iflOKAY on success, or an appropriate iflStatus error value on failure.

   freeICCProfile()
iflStatus freeICCProfile ( void* profile);

This method frees the profile returned by getICCProfile().

   getChannelPermutation()
int* getChannelPermutation (  );

This member function returns an array representing the channel permutation of the current image in the image file, or NULL (meaning the identity permutation). It is an array, indexed by memory channel, into the channels stored in the file (as accessed by getPage() and setPage()). This should be used by callers of getPage() and setPage() to re-order the data.

   getColorModel()
iflColorModel getColorModel (  );

This member function returns the color model of the current image in the image file.

   getColormap()
virtual iflStatus getColormap ( const iflColormap*& cmap);

Returns the color map associated with the current image in the image file.

On successful completion, iflOKAY will be returned and cmap will be set to point to a colormap stored in the iflFile object. Note that this colormap cannot be assumed to remain valid across calls to setColormap(), setCurrentImg(), appendImg(), close(), or calls to setTag() that report modification of the image's attributes.

On failure, the return value is an iflStatus encoding the reason for the failure, and the argument cmap is undefined.

   getCompression()
iflCompression getCompression (  );

Returns the compression method used for the current image in the image file.

   getCsize()
int getCsize (  );

Returns the number of components (channels) in the current image in the image file.

   getCurrentImg()
virtual int getCurrentImg (  );

This virtual member function returns the iflFile's current image index, i.e. the index into the list of images or resolutions in the image file, starting at 0.

   getDataType()
iflDataType getDataType (  );

This member function returns the data type of the current image in the image file.

   getDimensions()
void getDimensions ( iflSize& dimensions);

Returns the dimensions (width,height,z,c) of the current image in the image file, expressed with in conventional (x == width, y == height) orientation.

   getDirectIOMemAlignment()
iflStatus getDirectIOMemAlignment ( size_t& memAlign);

Returns the memory alignment requirements for pages read using direct I/O read and writes. Pages that are not properly aligned will revert to using the buffer cache for their file operations. The return value is iflOKAY if successful or an appropriate iflStatus error value on failure.

   getFileDesc()
int getFileDesc (  );

This member function returns the file descriptor used to access the image file.

   getFileMode()
int getFileMode (  );

This member function returns the access mode by which the file can be accessed. It is O_RDONLY, O_WRONLY, or O_RDWR.

   getFileName()
const char* getFileName (  );

This member function returns the file name of the image file, or NULL if the name is unknown (e.g. if the file was opened with a file descriptor only). The returned string points to data within the object, and will become invalid when the object is destroyed.

   getFormat()
iflFormat* getFormat (  );

Returns a pointer to the file format associated with the file. The pointed-to object is static and valid forever.

   getICCProfile()
iflStatus getICCProfile ( int& size, void*& profile);

This method returns the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   getItem()
iflStatus getItem ( int tag, ...);
virtual iflStatus getItem ( int tag, va_list ap);

The first form is a variation on the getTag() method and is now deprecated; please use getTag() instead.

The second form is a virtual method that actually implements the getTag() and getTagV() methods in derived subclasses that implement specific file formats. The naming is forced by the need to retain binary and source compatibility with older versions of IFL.

Treat this virtual as if it were protected. Directly calling this method is now deprecated; please use getTagV() instead.

   getNumImgs()
virtual int getNumImgs (  );

This virtual member function returns the number of images contained in the image file.

   getOrder()
iflOrder getOrder (  );

Returns the dimension order of the current image in the image file.

   getOrientation()
iflOrientation getOrientation (  );

Returns the orientation of the current image in the image file.

   getPage()
virtual iflStatus getPage ( void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc);

This virtual member function reads a page of image data from the image file.

The data argument specifies the address of the memory buffer into which the data should be placed.

The arguments x,y,z,nx,ny and nz specify the origin and size of the desired page within the source image file. The caller must guarantee that nx, ny, nz and nc are the image's page size and that x, y, z and c are a multiple of the page size; no checking is done by the function.

A successful call to getPage() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the buffer's contents are undefined.

If the caller is going to make multiple concurrent calls to getPage() and/or setPage(), it needs to set I/O callbacks (see the description of setBeginFileIO_CB(), setEndFileIO_CB() for how to do this).

The implementation of this method is required to surround code that must be executed atomically by calls to beginFileIO() and endFileIO() (see the descriptions of these functions for more details and common cases where this is necessary).

   getPageDimensions()
void getPageDimensions ( iflSize& pageDims);

Returns the natural page dimensions of the current image in the image file, expressed as x == width, y == height.

   getPageSize()
void getPageSize ( iflSize& sz, iflOrientation toOrientation);

Returns the natural page size of the current image in the image file, expressed with respect to the given orientation.

   getScaleMinMax()
virtual iflStatus getScaleMinMax ( double& min, double& max);

Returns the minimum and maximum value to be used for scaling during color conversion on the current image in the image file.

On successful completion, iflOKAY will be returned and the min and max arguments will be set to the appropriate values.

On failure, the return value is an iflStatus encoding the reason for the failure, and the arguments are left unmolested.

   getSize()
void getSize ( iflSize& sz, iflOrientation toOrientation);

Returns the size (x,y,z,c) of the current image in the image file, expressed with respect to the given orientation.

Note that the Z and C dimensions (which do not depend on the orientation) can be obtained separately by calling getZSize() and getCSize() respectively.

   getStatMinMax()
virtual iflStatus getStatMinMax ( double& min, double& max);

Returns the statistical min/max, i.e. the range of values that occur in the current image in the image file.

On successful completion, iflOKAY will be returned and the min and max arguments will be set to the appropriate values.

On failure, the return value is an iflStatus encoding the reason for the failure, and the arguments are left unmolested.

   getTag()
iflStatus getTag ( int tag, ...);

Gets the value of a tagged item associated with the current image in the image file.

The tag argument specifies the tag of the item to be set; it is interpreted by the specific iflFile subclass. The number and types of the remaining arguments are determined the particular subclass of iflFile and the tag value.

The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   getTagV()
iflStatus getTagV ( int tag, va_list ap);

This variation on the getTag() method is used by libraries that are passing along a variable calling sequence in ap through some wrapper layer.

   getTile()
iflStatus getTile ( int x, int y, int z, int nx, int ny, int nz, void* data, const iflConfig* config=NULL);

This member function reads an arbitrary rectangular region from the image file into memory. The portions of the memory buffer corresponding to area outside the boundaries of the source file image are left undisturbed.

The arguments x, y, z, nx, ny and nz specify the origin and size of the desired tile within the source image file, in the coordinate space indicated in the config parameter.

The data argument specifies the address of the memory buffer into which the data should be placed.

The config argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of x, y, z, nx, ny and nz, as described above. If defaulted, attributes of the buffer are assumed to match those of the image.

A successful call to getTile() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the buffer's contents are undefined.

   getZsize()
int getZsize (  );

Returns the Z component of the size of the current image in the image file.

   haveAttributesChanged()
int haveAttributesChanged (  );

Returns TRUE if any image attributes have changed due to a call to setTag() since last call to this method.

   lookupName()
static int lookupName ( const char* name, const iflNameDesc* names);

This method can be used to lookup parameter names/values in a list of name/id pairs. The id associated with the first match is returned (abbreviated names are allowed as matches). The names array is terminated with an entry whose associated id is returned if no match is found.

   markAttributesChanged()
void markAttributesChanged (  );

The method is used by a setItem() implementation to indicate that some of the core attributes were changed as a side effect. This flag is tested and cleared by calling haveAttributesChanged().

   open()
static iflFile* open ( iflFileDesc& fileDesc, int mode=O_RDONLY, iflStatus* status=NULL);
static iflFile* open ( int fd, const char* filename, int mode=O_RDONLY, iflFormat* format=NULL, iflStatus* status=NULL);
static iflFile* open ( const char* filename, int mode=O_RDONLY, iflStatus* status=NULL);

This static class member function opens an existing image file. The file is specified via the filename and fd arguments. At least one of these two arguments must be specified; they are interpreted as follows.

if filename != NULL and fd == -1:
opens the file with the given file name.

if filename == NULL and fd != -1:
uses the existing open file descriptor.

if filename != NULL and fd != -1:
uses the existing open file descriptor; the file name is stored solely for the getFileName() method and error messages.

The file name may be followed by an optional sub-image index using the syntax "filename:index" (see setCurrentImg() for how to change the sub-image index after the file is opened).

The mode argument specifies the desired access mode; it should be either O_RDONLY or O_RDWR.

The format argument specifies the desired file format. The usual usage is to use NULL in which case the file format is deduced by the file typing rules using the file's contents ("magic number"); this mechanism can be bypassed by specifying the format explicitly.

The alternate form taking a fileDesc argument, encapsulates the fd, filename and format arguments in this single argument. See iflFileDesc for more details.

On successful completion, the function returns a pointer to a newly-created object of the appropriate subclass if iflFile, which the application should eventually destroy using its close() method.

On failure, the function returns NULL and, if the status argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value.

   openFile()
virtual iflStatus openFile (  );

This virtual function is called by iflFile::open() after the member variables filename, fd, accessmode and format are all set and legal (though fd may be -1).

Its responsibility is to open the file and set fd (if fd is -1) and initialize the read-only member variables of iflFile (size, dtype, order, pageSize, cm, orientation, compression).

The subclass may insist on opening the file itself; if so, when openFile() is given an open fd, it should return iflStatusEncode(iflUNSUPPORTEDBYLIBRARY). iflFile::open() will respond by closing the file descriptor, setting fd to -1, and (assuming a file name was given) calling openFile() again using only the filename.

On success, openFile() should return iflOKAY. On failure, openFile() should return an appropriate error value and free any resources it allocated (including closing the file descriptor if it opened it), since closeFile() will not be called on an object for which openFile() failed.

Warning: when calling the system function open(), be sure to invoke it as ::open() to avoid mistakenly calling iflFile::open().

   parseArguments()
int parseArguments ( iflParameterDesc* params, int maxParams);

This method can be used to parse the format specific argument string using a standard <parameter-name>=<parameter-value> syntax where multiple parameters are separated by spaces or '%'. The iflParameterDesc array pointed to by params with maximum size maxParams will be filled in. The returned value is the number of parameters found. The lookupName() method can be used to assist in decoding parameter names.

   parseFileName()
static char* parseFileName ( const char* fullname, char** formatName=NULL, int* index=NULL, char** formatArgs=NULL);

This static class member function is used to parse a file name for IFL. IFL file names have the following syntax:
    <file-name>[#<format-name>][:<image-index>][%<format-specific>]
The return value is the actual file name and must be delete'd by the user. The format name can be returned via formatName if it is non-NULL; if no format name is present in the filename then NULL will be returned. The sub-image index can be returned via index if it is non-NULL; if no index is present in the filename then -1 will be returned. The format specific argument string can be returned via formatArgs if it is non-NULL; if no format specific arguments are present in the filename then NULL will be returned. See parseArguments() for optional support in parsing format specific arguments (recommended for consistency).

This function is called automatically by the open() member function.

   setBeginFileIO_CB()
void setBeginFileIO_CB ( iflStatus(* cb)(void*), void* arg);

Sets the callback and argument that will be called by beginFileIO() during calls to getPage() and setPage(). To disable this callback, use NULL for the cb argument.

   setColormap()
virtual iflStatus setColormap ( const iflColormap* cmap);

Sets the color map associated with the current image to be a copy of the colormap pointed to by the argument cmap.

On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure.

Whether or not the function succeeds, the value returned from previous calls to getColormap() becomes invalid.

   setCurrentImg()
virtual iflStatus setCurrentImg ( int idx);

This virtual member function sets the current image index (i.e. the index into the list of images or resolutions in the image file, starting at 0) to idx.

If the operation is successful, the value iflOKAY is returned and the image index is changed (which may mean the dimensions and attributes subsequently returned by the get...() methods may be changed).

If the argument given is out of bounds of the images in the file, the value iflStatusEncode(iflFILEFINDEXOOB) is returned and the image index is left unchanged.

If the operation fails for some other reason, an ifl error will be thrown via the iflError mechanism; if the program continues, and the file's image index may be the old or the new index.

   setEndFileIO_CB()
void setEndFileIO_CB ( iflStatus(* cb)(void*), void* arg);

Sets the callback and argument that will be called by endFileIO() during calls to getPage() and setPage(). To disable this callback, use NULL for the cb argument.

   setICCProfile()
iflStatus setICCProfile ( int size, const void* profile);

This method sets the value of the ICC profile associated with the image. The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   setItem()
iflStatus setItem ( int tag, ...);
virtual iflStatus setItem ( int tag, va_list ap);

The first form is a variation on the setTag() method and is now deprecated; please use setTag() instead.

The second form is a virtual method that actually implements the setTag() and setTagV() methods in derived subclasses that implement specific file formats. The naming is forced by the need to retain binary and source compatibility with older versions of IFL.

Treat this virtual as if it were protected. Directly calling this method is now deprecated; please use setTagV() instead.

   setPage()
virtual iflStatus setPage ( const void* data, int x, int y, int z, int c, int nx, int ny, int nz, int nc);

This virtual member function writes a page of image data from the image file.

The data argument specifies the address of the memory buffer containing the data to be written.

The arguments x, y, z, nx, ny and nz specify the origin and size of the desired page within the source image file. The caller must guarantee that nx, ny, nz and nc are the image's page size and that x, y, z and c are a multiple of the page size; no checking is done by the function.

A successful call to setPage() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the contents of the file are undefined.

The same multiprocessing safety issues apply here as for getPage().

   setScaleMinMax()
virtual iflStatus setScaleMinMax ( double min, double max);

Sets the minimum and maximum value to be used for scaling during color conversion on the current image in the image file.

On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure.

   setStatMinMax()
virtual iflStatus setStatMinMax ( double min, double max);

Sets the file's notion of the range of values that occur in the current image in the image file.

On successful completion, the function returns iflOKAY. On failure, the function returns an iflStatus indicating the reason for failure.

   setTag()
iflStatus setTag ( int tag, ...);

Sets the value of a tagged item associated with the current image in the image file.

Calling setTag() may change some image attributes. This can be check by calling haveAttributesChanged() after calling setTag().

The tag argument specifies the name of the item to be set; it is interpreted by the specific iflFile subclass. The number and types of the remaining arguments are determined the particular subclass of iflFile and the tag value.

The return value is iflOKAY on success, or an appropriate iflStatus error value on failure.

   setTagV()
iflStatus setTagV ( int tag, va_list ap);

This variation on the setTag() method is used by libraries that are passing along a variable calling sequence in ap through some wrapper layer.

   setTile()
iflStatus setTile ( int x, int y, int z, int nx, int ny, int nz, const void* data, const iflConfig* config=NULL);

This member function writes an arbitrary rectangular region from a memory buffer into the image file. The portions of the memory buffer corresponding to area outside the boundaries of the source file image are ignored.

The arguments x, y, z, nx, ny and nz specify the origin and size of the target tile within the destination image file, in the coordinate space indicated in the config parameter.

The data argument specifies the address of the memory buffer containing the data to be written.

The config argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of x, y, z, nx, ny and nz, as described above. If defaulted, attributes of the buffer are assumed to match those of the image.

A successful call to setTile() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the contents of the file are undefined.

Note that setTile() may need to make calls to the subclass's getPage() as well as setPage() in order to write a tile that is not aligned with the file's pages.

MEMBER DESCRIPTIONS

   accessmode
int accessmode;

The access mode for this file: O_RDONLY, O_WRONLY, or O_RDWR. This is filled in by the open() and create() static methods.

   cm
iflColorModel cm;

The color model of the current sub-image. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   compression
iflCompression compression;

The compression scheme used by the current sub-image. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   dtype
iflDataType dtype;

The data type of the current sub-image. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   fd
int fd;

The unix file descriptor of the file being accessed. This is filled in by the open() and create() static methods. If no file descriptor was supplied then the value will be -1, and the openFile() or createFile() methods are expected to do the open() and remember the file descriptor in this member. The closeFile() method should always close() this descriptor.

   filename
char* filename;

The name of the file being opened or created. This is filled in by the open() and create() static methods. If no filename was given then the value will be NULL.

   format
iflFormat* format;

The file format of the file. This is filled in by the open() and create() static methods.

   formatArgs
char* formatArgs;

The format specific arguments portion of the file name. This is filled in by the open() and create() static methods using parseFileName(). Typically it is further decoded in openFile() or createFile() using parseArguments().

   order
iflOrder order;

The dimension order of the current sub-image. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   orientation
iflOrientation orientation;

The orientation of the current sub-image. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   pageSize
iflSize pageSize;

The natural access size for the current sub-image, in its native orientation. This is the quantum that getPage() and setPage() operate on.

This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

   size
iflSize size;

The size of the current sub-image, in pixels, in its native orientation. This member is filled in by the create() static method before calling createFile() and must be filled in by the file format's implementations of openFile(), setCurrentImg() and appendImg().

SEE ALSO
dup, iflError, iflFileDesc, lseek, read, write