iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)NAMEiflFormat - abstraction of an image file format
INHERITS FROM
This is a base class with no inheritance.
HEADER FILE
#include <ifl/iflCdefs.h>
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(),
Page 1
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)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.
CLASS MEMBER FUNCTION SUMMARY
Format lookup
static iflFormat* iflFormatFindNext(iflFormat *obj,
int* index,
int openDSOifNecessary)
static iflFormat* iflFormatFindByMagic(iflFormat *obj,
int fd, int openDSOifNecessary)
static iflFormat* iflFormatFindByFormatName(iflFormat *obj,
const char* formatName,
int openDSOifNecessary)
static iflFormat* iflFormatFindByFileName(iflFormat *obj,
const char* fileName,
int noMatchRule,
int openDSOifNecessary)
Attribute queries
const char* iflFormatGetName(iflFormat *obj)
const char* iflFormatGetDefaultSuffix(iflFormat *obj)
const char* iflFormatGetDescription(iflFormat *obj)
Attribute support queries
int iflFormatAccessModeIsSupported(iflFormat *obj, int mode)
virtual int iflFormatTypeIsSupported(iflFormat *obj, iflDataType type)
virtual int iflFormatOrderIsSupported(iflFormat *obj,
iflOrder order)
virtual int iflFormatOrientationIsSupported(iflFormat *obj,
iflOrientation orientation)
virtual int iflFormatColorModelIsSupported(iflFormat *obj,
iflColorModel colormodel)
virtual int iflFormatCompressionIsSupported(iflFormat *obj,
iflCompression compression)
virtual int iflFormatSizeIsSupported(iflFormat *obj, int width,
int height, int z,
int c, iflOrientation orientation)
virtual int iflFormatPagingIsSupported(iflFormat *obj)
Page 2
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
virtual int iflFormatPageSizeIsSupported(iflFormat *obj,
int iWidth,
int iHeight,
int iz, int ic,
int pWidth,
int pHeight,
int pz, int pc,
iflOrientation orientation)
virtual int iflFormatRandomAccessReadIsSupported(iflFormat *obj)
virtual int iflFormatRandomAccessWriteIsSupported(iflFormat *obj)
Attribute preference queries
virtual iflDataType iflFormatGetPreferredType(iflFormat *obj)
virtual iflOrder iflFormatGetPreferredOrder(iflFormat *obj)
virtual iflOrientation iflFormatGetPreferredOrientation(iflFormat *obj)
virtual iflColorModel iflFormatGetPreferredColorModel(iflFormat *obj,
int nc)
virtual iflCompression iflFormatGetPreferredCompression(iflFormat *obj)
virtual void iflFormatGetPreferredPageSize(iflFormat *obj,
int iWidth,
int iHeight,
int iz, int ic,
int* pWidth,
int* pHeight,
int* pz,
int* pc,
iflOrientation orientation)
Inheriting attributes
iflStatus iflFormatApplyDefaults(iflFormat *obj, iflFile* source,
iflFileConfig* config)
iflStatus iflFormatApplyDefaultsConfig(iflFormat *obj,
iflFileConfig* source,
iflFileConfig* config)
int iflFormatHaveDSOVersion(iflFormat *obj, int major,
int minor)
int iflFormatHaveICC(iflFormat *obj)
FUNCTION DESCRIPTIONSiflFormat()
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.
accessModeIsSupported()
Page 3
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
int iflFormatAccessModeIsSupported(iflFormat *obj, 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 iflFormatApplyDefaults(iflFormat *obj, iflFile* source,
iflFileConfig* config)
iflStatus iflFormatApplyDefaultsConfig(iflFormat *obj,
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 iflFormatColorModelIsSupported(iflFormat *obj,
iflColorModel colormodel)
This virtual member function tells whether the given color model is
supported by the image file format.
compressionIsSupported()
virtual int iflFormatCompressionIsSupported(iflFormat *obj,
iflCompression compression)
This virtual member function tells whether the given compression is
supported by the image file format.
findByFileName()
Page 4
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
static iflFormat* iflFormatFindByFileName(iflFormat *obj,
const char* fileName,
int noMatchRule,
int openDSOifNecessary)
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 iflExtensions variable 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* iflFormatFindByFormatName(iflFormat *obj,
const char* formatName,
int openDSOifNecessary)
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* iflFormatFindByMagic(iflFormat *obj,
int fd, int openDSOifNecessary)
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* iflFormatFindNext(iflFormat *obj,
int* index,
int openDSOifNecessary )
Page 5
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
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* iflFormatGetDefaultSuffix(iflFormat *obj)
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* iflFormatGetDescription(iflFormat *obj)
This member function returns the format description, or NULL if
there is none.
getName()
const char* iflFormatGetName(iflFormat *obj)
This member function returns the format name, which is a pointer to
a static string that is valid forever.
getPreferredColorModel()
virtual iflColorModel iflFormatGetPreferredColorModel(iflFormat *obj,
int nc)
Page 6
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
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 iflFormatGetPreferredCompression(iflFormat *obj)
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 iflFormatGetPreferredOrder(iflFormat *obj)
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 iflFormatGetPreferredOrientation(iflFormat *obj)
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 iflFormatGetPreferredPageSize(iflFormat *obj,
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 7
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
page size; the caller can check this by calling
pageSizeIsSupported()).
getPreferredType()
virtual iflDataType iflFormatGetPreferredType(iflFormat *obj)
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.
haveDSOVersion()
int iflFormatHaveDSOVersion(iflFormat *obj, int major,
int minor)
This member function returns TRUE if the DSO loaded is the same of
newer than the indicated major and minor version numbers.
haveICC()
int iflFormatHaveICC(iflFormat *obj)
This member function returns TRUE if the DSO loaded supports the ICC
methods: getICCProfile(), freeICCProfile() and setICCProfile().
orderIsSupported()
virtual int iflFormatOrderIsSupported(iflFormat *obj,
iflOrder order)
This virtual member function tells whether the given dimension order
is supported by the image file format.
orientationIsSupported()
virtual int iflFormatOrientationIsSupported(iflFormat *obj,
iflOrientation orientation)
This virtual member function tells whether the given orientation is
supported by the image file format.
pageSizeIsSupported()
Page 8
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
virtual int iflFormatPageSizeIsSupported(iflFormat *obj,
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 iflFormatPagingIsSupported(iflFormat *obj)
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 iflFormatRandomAccessReadIsSupported(iflFormat *obj)
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 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 iflFormatRandomAccessWriteIsSupported(iflFormat *obj)
Page 9
iflFormat(3) Image Format Library C++ Reference Manual iflFormat(3)
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 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 iflFormatSizeIsSupported(iflFormat *obj, 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 iflFormatTypeIsSupported(iflFormat *obj, iflDataType type)
This virtual member function tells whether the given data type is
supported by the image file format.
SEE ALSO
iflFile, iflDatabase
NOTE
Applications that use iflFormat functionality should check to see whether
the less-filling iflDatabase satisfies its needs.
Page 10
