VIPER REFERENCE MANUAL


NAME
iflFormat - abstraction of an image file format

HEADER FILE
#include <ifl/iflFormat.h>

PUBLIC METHOD SUMMARY

   Format lookup
static iflFormat* findNext ( int& index, int openDSOifNecessary=TRUE);
static iflFormat* findByMagic ( int fd, int openDSOifNecessary=TRUE);
static iflFormat* findByFormatName ( const char* formatName, int openDSOifNecessary=TRUE);
static iflFormat* findByFileName ( const char* fileName, int noMatchRule=FALSE, int openDSOifNecessary=TRUE);

   Attribute queries
const char* getName (  );
const char* getDefaultSuffix (  );
const char* getDescription (  );

   Attribute support queries
int accessModeIsSupported ( int mode);
virtual int typeIsSupported ( iflDataType type);
virtual int orderIsSupported ( iflOrder order);
virtual int orientationIsSupported ( iflOrientation orientation);
virtual int colorModelIsSupported ( iflColorModel colormodel);
virtual int compressionIsSupported ( iflCompression compression);
virtual int sizeIsSupported ( int width, int height, int z, int c, iflOrientation orientation);
virtual int pagingIsSupported (  );
virtual int pageSizeIsSupported ( int iWidth, int iHeight, int iz, int ic, int pWidth, int pHeight, int pz, int pc, iflOrientation orientation);
virtual int randomAccessReadIsSupported (  );
virtual int randomAccessWriteIsSupported (  );

   Attribute preference queries
virtual iflDataType getPreferredType (  );
virtual iflOrder getPreferredOrder (  );
virtual iflOrientation getPreferredOrientation (  );
virtual iflColorModel getPreferredColorModel ( int nc=0);
virtual iflCompression getPreferredCompression (  );
virtual void getPreferredPageSize ( int iWidth, int iHeight, int iz, int ic, int& pWidth, int& pHeight, int& pz, int& pc, iflOrientation orientation);

   Inheriting attributes
iflStatus applyDefaults ( iflFile* source, iflFileConfig& config);
iflStatus applyDefaults ( iflFileConfig* source, iflFileConfig& config);

   GUI support
iflTagDescription* getTagDescriptions ( int& count);

   Version query
int haveDSOVersion ( int major, int minor);

PROTECTED METHOD SUMMARY

   Constructing
iflFormat ( const char* formatName);
virtual iflFile* newfileobj (  );

   Implementing GUI support
virtual iflTagDescription* _getTagDescriptions ( int& count);

CLASS DESCRIPTION
An iflFormat object represents a description of the capabilities of a particular image file format. Usually there exists at most one such object per file format in a running program; functions that return iflFormat's (such as iflFile::getFormat()) generally return a pointer to the single static object of the appropriate subclass of iflFormat.

iflFormat is an abstract base class; every iflFormat object is actually an object of a file-format-specific subclass such as iflTIFFFormat.

   Format lookup functions
An IFL application can use the findNext(), findByMagic(), findByFormatName() and findByFileName() functions to step through all supported file formats, or to look up an image file format by format name, file name, or file magic number. The return value of each of these functions is an iflFormat* pointing to the single static object of the appropriate subclass of iflFormat (such as iflTIFFFormat).

   Supported attribute queries
These ...IsSupported() functions tell whether a given value of a given image attribute is supported by the image file format.

Note that certain combinations of parameters might not be supported, even if each parameter is individually supported; thus these functions cannot give a definitive positive answer for support of a set of parameters, though they may give a definitive negative answer.

   Preferred attribute queries
The getPreferred...() virtual member functions return the image file format's "preferred" value for the respective attributes. The returned value must be one of the supported values for that parameter, as reported by the corresponding "isSupported" method.

DERIVING SUBCLASSES
The derived class must define all of iflFormat's pure virtuals: accessModeIsSupported(), typeIsSupported(), orderIsSupported(), orientationIsSupported(), colorModelIsSupported(), compressionIsSupported(), sizeIsSupported(), pagingIsSupported(), pageSizeIsSupported(), randomAccessReadIsSupported(), randomAccessWriteIsSupported(), getPreferredType(), getPreferredOrder(), getPreferredOrientation(), getPreferredColorModel(), getPreferredCompression(), getPreferredPageSize() and newfileobj(). This will fully characterize the format, and, via newfileobj(), will tell iflFile::open() how to create an iflFile of this format's type.

Each image file format subclass format is expected to declare a single static object of its derived type. The base class constructor invoked automatically when the DSO is opened (becuase of the static object declaration) will put the derived format on the global format list as part of its initialization.

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

METHOD DESCRIPTIONS

   iflFormat()
iflFormat ( const char* formatName);

Derived classes should pass the name of the format as formatName so the format will be properly registered in the database. This name must match the name used in the 'ifl_database' file.

   _getTagDescriptions()
virtual iflTagDescription* _getTagDescriptions ( int& count);

This virtual member function is used to impelement the public getTagDescriptions() method.

   accessModeIsSupported()
int accessModeIsSupported ( int mode);

This virtual member function tells whether the given access mode (which must be one of O_RDONLY, O_WRONLY, or O_RDWR) is supported by the subclass.

Note that this function is also provided by iflDatabase, which gets the information from the FTR database without the overhead of opening any DSOs.

   applyDefaults()
iflStatus applyDefaults ( iflFile* source, iflFileConfig& config);
iflStatus applyDefaults ( iflFileConfig* source, iflFileConfig& config);

These member functions attempt to change all of the parameters of the iflFileConfig, config, that have the value 0 (i.e. don't care) to be reasonable values. The values are inherited from the source iflFile* (if it is non-NULL and the value is supported), the source iflFileConfig* (if it is non-NULL and the value is supported), or are heuristically selected to be a supported value most suitable for copying data from the source iflFile* or iflFileConfig*. If the source iflFile* is NULL or the source iflFileConfig* is NULL, the don't-care parameters are changed to the image file format's preferred values.

   colorModelIsSupported()
virtual int colorModelIsSupported ( iflColorModel colormodel);

This virtual member function tells whether the given color model is supported by the image file format.

   compressionIsSupported()
virtual int compressionIsSupported ( iflCompression compression);

This virtual member function tells whether the given compression is supported by the image file format.

   findByFileName()
static iflFormat* findByFileName ( const char* fileName, int noMatchRule=FALSE, int openDSOifNecessary=TRUE);

This static class member function is used to look up an image file format by file name, where the file name is given by the fileName argument. This is accomplished by matching the filename against against the suffixes list given for each image file format in the FTR database.

The noMatchRule argument can be used to limit searching to those formats that have no match rule.

The openDSOifNecessary argument can be used to limit searching to those formats whose DSOs have already been opened.

   findByFormatName()
static iflFormat* findByFormatName ( const char* formatName, int openDSOifNecessary=TRUE);

This static class member function is used to look up an image file format by name, where the name is given by the formatName argument.

The openDSOifNecessary argument can be used to limit searching to those formats whose DSOs have already been opened.

   findByMagic()
static iflFormat* findByMagic ( int fd, int openDSOifNecessary=TRUE);

This static class member function is used to look up an image file format by magic number of a given file that is open for reading.

The fd argument is a file descriptor referring to the file.

The openDSOifNecessary argument can be used to limit searching to those formats whose DSOs have already been opened.

   findNext()
static iflFormat* findNext ( int& index, int openDSOifNecessary=TRUE);

This static class member function is used to step through the (static, lazily created) list of supported file formats.

To start searching, initialize the index paramter to zero. It will be automatically updated by each call so that successive calls will iterate through all available formats. If there are no more formats, the function returns NULL.

If openDSOifNecessary is false, then no DSOs will be opened, and only formats whose DSOs have already been opened will be returned.

The following example prints the names of all supported formats: (note that iflDatabase can do this too):
    iflFormat* fmt;
    int index = 0;
    while ((fmt = iflFormat::findNext(index)) != NULL)
        printf("%s\n", fmt->getName());

   getDefaultSuffix()
const char* getDefaultSuffix (  );

This member function returns the default filename suffix (the first suffix listed in the "suffixes" declaration for a format in the IFL format database). The returned value is a pointer to a static string that is valid forever. Note that the returned value may be NULL.

   getDescription()
const char* getDescription (  );

This member function returns the format description, or NULL if there is none.

   getName()
const char* getName (  );

This member function returns the format name, which is a pointer to a static string that is valid forever.

   getPreferredColorModel()
virtual iflColorModel getPreferredColorModel ( int nc=0);

This virtual member function returns the image file format's "preferred" value for the color model attribute for an image with nc channels. If nc is zero the most common color model will be returned. The returned value must be one of the supported color models, as reported by the colorModelIsSupported() method.

   getPreferredCompression()
virtual iflCompression getPreferredCompression (  );

This virtual member function returns the image file format's "preferred" value for the compression attribute. The returned value must be one of the supported compressions, as reported by the compressionIsSupported() method.

   getPreferredOrder()
virtual iflOrder getPreferredOrder (  );

This virtual member function returns the image file format's "preferred" value for the order attribute. The returned value must be one of the supported orders, as reported by the orderIsSupported() method.

   getPreferredOrientation()
virtual iflOrientation getPreferredOrientation (  );

This virtual member function returns the image file format's "preferred" value for the orientation attribute. The returned value must be one of the supported orientations, as reported by the orientationIsSupported() method.

   getPreferredPageSize()
virtual void getPreferredPageSize ( int iWidth, int iHeight, int iz, int ic, int& pWidth, int& pHeight, int& pz, int& pc, iflOrientation orientation);

This virtual member function returns the image file format's "preferred" page size, pWidth, pHeight, pz and pc, for an image whose size is iWidth, iHeight, iz and ic (which must be a supported page size; the caller can check this by calling pageSizeIsSupported()).

   getPreferredType()
virtual iflDataType getPreferredType (  );

This virtual member function returns the image file format's "preferred" value for the data type attribute. The returned value must be one of the supported data types, as reported by the typeIsSupported() method.

   getTagDescriptions()
iflTagDescription* getTagDescriptions ( int& count);

This member function is used to get a description of all the tags that are supported with iflFile::getTag() and iflFile::setTag() for files of this format.

This might be useful to a GUI application that wants to build a panel that lets the user access format specific attributes.

   haveDSOVersion()
int haveDSOVersion ( int major, int minor);

This method is used to check the version of the DSO that is loaded for this format. This can be used to check whether it is safe to use methods only supported in later versions of the IFL api. The return value is TRUE if the DSO loaded is the same or newer than the indicated major and minor version numbers.

   newfileobj()
virtual iflFile* newfileobj (  );

The static functions iflFile::open() and iflFile::create() use this function to construct an object of the desired subclass of iflFile. The implementation should simply return a new object of the desired subclass of iflFile.

   orderIsSupported()
virtual int orderIsSupported ( iflOrder order);

This virtual member function tells whether the given dimension order is supported by the image file format.

   orientationIsSupported()
virtual int orientationIsSupported ( iflOrientation orientation);

This virtual member function tells whether the given orientation is supported by the image file format.

   pageSizeIsSupported()
virtual int pageSizeIsSupported ( int iWidth, int iHeight, int iz, int ic, int pWidth, int pHeight, int pz, int pc, iflOrientation orientation);

This virtual member function tells whether the image file format supports the given page size, pWidth, pHeight, pz and pc, for an image whose size is iWidth, iHeight, iz and ic (which must be a supported image size; the caller can check this by calling sizeIsSupported()).

   pagingIsSupported()
virtual int pagingIsSupported (  );

This virtual member function tells whether the image file format supports any page size other than the entire image size.

This might be useful to a GUI application that allows the user to enter a page size; the text entry widget could be disabled if paging is not supported.

   randomAccessReadIsSupported()
virtual int randomAccessReadIsSupported (  );

This virtual member function tells whether the corresponding iflFile subclass supports random access reads (as opposed to requiring that reads occur sequentially).

If the subclass does not support random access reads, out-of-order calls to iflFile::getPage() may return iflStatusEncode(iflUNSUPPORTEDBYFORMAT) (if the limitation is inherent in the file format) or iflStatusEncode(iflUNSUPPORTEDBYLIBRARY) (if the limitation is due to the implementation of the iflFile subclass).

This function is irrelevant for formats that do not support reading or that do not support paging.

   randomAccessWriteIsSupported()
virtual int randomAccessWriteIsSupported (  );

This virtual member function tells whether the corresponding iflFile subclass supports random access writes (as opposed to requiring that writes occur sequentially).

If the subclass does not support random access writes, out-of-order calls to iflFile::setPage() may return iflStatusEncode(iflUNSUPPORTEDBYFORMAT) (if the limitation is inherent in the file format) or iflStatusEncode(iflUNSUPPORTEDBYLIBRARY) (if the limitation is due to the implementation of the iflFile subclass).

This function is irrelevant for formats that do not support writing or that do not support paging.

   sizeIsSupported()
virtual int sizeIsSupported ( int width, int height, int z, int c, iflOrientation orientation);

This virtual member function tells whether the given image size, width, height, z and c, (which the caller must guarantee are all positive values) is supported by the image file format.

   typeIsSupported()
virtual int typeIsSupported ( iflDataType type);

This virtual member function tells whether the given data type is supported by the image file format.

SEE ALSO
iflDatabase, iflFile