iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
NAME
iflFile - abstraction for image file access
INHERITS FROM
This is a base class
HEADER FILE
#include <il/iflFile.h>
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.
Page 1
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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 getItem() and setItem() deal with "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.
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
Page 2
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
with a semaphore mechanism. The application does this by supplying a
beginFileIO callback with setBeginFileIOCB() (which should acquire a
semaphore) and an endFileIO callback with setEndFileIOCB() (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()/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()/getPage() code is completely non-MP-safe, the
implementor may choose to surround the entire function bodies with
beginFileIO()/endFileIO().
Creating and destroying
The IFL library's functions open()/create()/close() methods call the
openFile()/createFile()/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.
CLASS MEMBER FUNCTION SUMMARY
Constructor
iflFile() protected
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(iflFileDesc& fileDesc, iflFile* source,
const iflFileConfig* cfg=NULL,
Page 3
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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(const char *filename, iflFile* source,
const iflFileConfig* cfg=NULL,
iflFormat* format=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)
Public functions to get/set image data
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)
virtual iflStatus getCompressedPage(...)
virtual iflStatus decompressPage(...)
virtual iflStatus compressPage(...)
virtual iflStatus setCompressedPage(...)
Manipulating the current image index
virtual int getNumImgs()
virtual int getCurrentImg()
virtual iflStatus setCurrentImg(int i)
Adding images
virtual iflStatus appendImg(iflFile* source, iflFileConfig* fc=NULL)
Attribute query
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()
Page 4
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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)
iflStatus getItem(int tag, ...)
virtual iflStatus getItem(int tag, va_list ap)
int haveAttributesChanged()
Attribute setting
virtual iflStatus setColormap(const iflColormap* cmap)
virtual iflStatus setStatMinMax(double min, double max)
virtual iflStatus setScaleMinMax(double min, double max)
iflStatus setItem(int tag, ...)
virtual iflStatus setItem(int tag, va_list ap)
void setBeginFileIO_CB(iflStatus(*cb)(void*), void* arg)
void setEndFileIO_CB(iflStatus(*cb)(void*), void* arg)
void markAttributesChanged() protected
File argument parsing
int parseArguments(iflParameterDesc* params, int maxParams) protected
static int lookupName(const char* name, const iflNameDesc* names)protected
Multi-processing protection
iflStatus beginFileIO() protected
iflStatus endFileIO() protected
ICC profile access
virtual iflStatus getICCProfile(int& size, void*& profile)
virtual iflStatus freeICCProfile(void* profile)
virtual iflStatus setICCProfile(int size, const void* profile)
FUNCTION DESCRIPTIONS
iflFile()
iflFile() protected
The protected default constructor, called implicitly in derived-
class constructors, initializes itself to an empty state.
Page 5
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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 cfg 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() protected
Calls the beginFileIO callback that was set by the application by a
previous call to setBeginFileIOCB(), 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
Page 6
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
be returned up the caller; otherwise iflOKAY will be returned.
compressPage()
virtual iflStatus compressPage(...)
This method is part of IFL's intended future support for for per-
page compression and decompression of image data. It is currently
unsupported.
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(3) 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*.
Page 7
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
decompressPage()
virtual iflStatus decompressPage(...)
This method is part of IFL's intended future support for for per-
page compression and decompression of image data. It is currently
unsupported.
endFileIO()
iflStatus endFileIO() protected
Calls the endFileIO callback that was set by the application by a
previous call to setEndFileIOCB(), 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()
virtual iflStatus freeICCProfile(void* profile)
The virtual member function frees the profile returned by
getICCProfile().
getChannelPermutation()
int* getChannelPermutation()
Page 8
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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()/setPage()). This should be used by callers of
getPage()/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
setItem() 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.
getCompressedPage()
virtual iflStatus getCompressedPage(...)
This method is part of IFL's intended future support for for per-
page compression and decompression of image data. It is currently
unsupported.
getCompression()
iflCompression getCompression()
Returns the compression method used for the current image in the
image file.
getCsize()
Page 9
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
int getCsize()
Returns the number of 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.
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()
Page 10
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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()
virtual iflStatus getICCProfile(int& size, void*& profile)
This virtual member function 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)
Gets the value of an item associated with the current image in the
image file.
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.
The second overloaded form of this method is used by libraries that
are passing along a variable calling sequence in ap through some
wrapper layer.
getNumImgs()
virtual int getNumImgs()
Page 11
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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 setBeginFileIOCB(), setEndFileIOCB() for how to do
this).
This function 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).
Page 12
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
Page 13
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
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
setItem() since last call to this method.
lookupName()
Page 14
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
static int lookupName(const char* name, const iflNameDesc* names) protected
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() protected
The method is used by a setItem() implementation to indicate that
some above the above core attributes were changed as a side effect.
This flag is tested and cleared by calling haveAttributesChanged().
open()
static iflFile* open(const char* filename, 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(iflFileDesc& fileDesc, 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 filename.
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 filename 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 setCurrentImage() 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
Page 15
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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(3) 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.
parseArguments()
int parseArguments(iflParameterDesc* params, int maxParams) protected
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).
Page 16
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
This function is called automatically by the open() member function.
setBeginFileIOCB()
void setBeginFileIO_CB(iflStatus(*cb)(void*), void* arg)
Sets the callback and arg 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.
setCompressedPage()
virtual iflStatus setCompressedPage(...)
This method is part of IFL's intended future support for for per-
page compression and decompression of image data. It is currently
unsupported.
setCurrentImg()
virtual iflStatus setCurrentImg(int i)
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.
Page 17
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
setEndFileIOCB()
void setEndFileIO_CB(iflStatus(*cb)(void*), void* arg)
Sets the callback and arg that will be called by endFileIO() during
calls to getPage() and setPage(). To disable this callback, use
NULL for the cb argument.
setICCProfile()
virtual iflStatus setICCProfile(int size, const void* profile)
This virtual member function 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)
Sets the value of an item associated with the current image in the
image file.
Calling setItem() may change some image attributes. This can be
check by calling haveAttributesChanged() after calling setItem().
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.
The second overloaded form of this method is used by libraries that
are passing along a variable calling sequence in ap through some
wrapper layer.
setPage()
virtual iflStatus setPage(const void* data, int x, int y,
int z, int c, int nx, int ny,
int nz, int nc)
Page 18
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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 MP safety issues apply here as for getPage() (see above).
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.
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.
Page 19
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
SEE ALSO
iflFormat(3), iflSize(3), iflFileDesc(3)
Page 20