iflFile(3) Image Format Library C++ Reference Manual iflFile(3)NAMEiflFile - abstraction for image file access
INHERITS FROM
This is a base class
HEADER FILE
#include <ifl/iflCdefs.h>
CLASS DESCRIPTIONiflFile 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 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 SUBCLASSESiflFile 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
Open/create/close methods
iflFile* iflFileOpenPreParsed(iflFile *obj, iflFileDesc* fileDesc,
int mode, iflStatus* status)
iflFile* iflFileOpenByDescriptor(iflFile *obj,
int fd, const char* filename,
int mode, iflFormat* format,
iflStatus* status)
iflFile* iflFileOpen(iflFile *obj, const char* filename,
int mode, iflStatus* status)
iflFile* iflFileCreatePreParsed(iflFile *obj, iflFileDesc* fileDesc,
iflFile* source,
const iflFileConfig* cfg,
iflStatus* status)
Page 3
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
iflFile* iflFileCreateByDescriptor(iflFile *obj,
int fd, const char *filename,
iflFile* source,
const iflFileConfig* cfg,
iflFormat* format,
iflStatus* status)
iflFile* iflFileCreate(iflFile *obj, const char *filename,
iflFile* source, const iflFileConfig* cfg,
iflFormat* format, iflStatus* status)
iflStatus iflFileClose(iflFile *obj, int flags)
iflStatus iflFileFlush(iflFile *obj)
char* iflFileParseFileName(iflFile *obj, const char* fullname,
char** formatName,
int* index, char** formatArgs)
Public functions to get/set image data
iflStatus iflFileGetTile(iflFile *obj, int x, int y, int z,
int nx, int ny, int nz, void *data,
const iflConfig* config)
iflStatus iflFileSetTile(iflFile *obj, int x, int y, int z,
int nx, int ny, int nz, const void *data,
const iflConfig* config)
iflStatus iflFileGetPage(iflFile *obj, void* data,
int x, int y, int z,
int c, int nx, int ny,
int nz, int nc)
iflStatus iflFileSetPage(iflFile *obj, const void* data,
int x, int y, int z,
int c, int nx, int ny,
int nz, int nc)
Manipulating the current image index
int iflFileGetNumImgs(iflFile *obj)
int iflFileGetCurrentImg(iflFile *obj)
iflStatus iflFileSetCurrentImg(iflFile *obj, int i)
Adding images
iflStatus iflFileAppendImg(iflFile *obj, iflFile* source,
iflFileConfig* fc)
Attribute query
const char* iflFileGetFileName(iflFile *obj)
int iflFileGetFileDesc(iflFile *obj)
int iflFileGetFileMode(iflFile *obj)
iflFormat* iflFileGetFormat(iflFile *obj)
iflColorModel iflFileGetColorModel(iflFile *obj)
int* iflFileGetChannelPermutation(iflFile *obj)
void iflFileGetDimensions(iflFile *obj, iflSize* dimensions)
Page 4
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
void iflFileGetSize(iflFile *obj, iflSize* sz, iflOrientation toOrientation)
int iflFileGetZsize(iflFile *obj)
int iflFileGetCsize(iflFile *obj)
iflDataType iflFileGetDataType(iflFile *obj)
iflOrder iflFileGetOrder(iflFile *obj)
void iflFileGetPageDimensions(iflFile *obj, iflSize* pageDims)
void iflFileGetPageSize(iflFile *obj, iflSize* sz, iflOrientation toOrientation)
iflOrientation iflFileGetOrientation(iflFile *obj)
iflCompression iflFileGetCompression(iflFile *obj)
iflStatus iflFileGetColormap(iflFile *obj, const iflColormap** cmap)
iflStatus iflFileGetStatMinMax(iflFile *obj, double* min,
double* max)
iflStatus iflFileGetScaleMinMax(iflFile *obj,
double* min,
double* max)
iflStatus iflFileGetItemV(iflFile *obj, int tag,
va_list ap)
int iflFileHaveAttributesChanged(iflFile *obj)
Attribute setting
iflStatus iflFileSetColormap(iflFile *obj, const iflColormap* cmap)
iflStatus iflFileSetStatMinMax(iflFile *obj, double min,
double max)
iflStatus iflFileSetScaleMinMax(iflFile *obj,
double min,
double max)
iflStatus iflFileSetItemV(iflFile *obj, int tag,
va_list ap)
ICC profile access
virtual iflStatus iflFileGetICCProfile(iflFile *obj, int* size,
void** profile)
virtual iflStatus iflFileFreeICCProfile(iflFile *obj,
void* profile)
virtual iflStatus iflFileSetICCProfile(iflFile *obj, int size,
const void* profile)
FUNCTION DESCRIPTIONSappendImg()
iflStatus iflFileAppendImg(iflFile *obj, iflFile* source,
iflFileConfig* fc)
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.
Page 5
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
iflStatus iflFileClose(iflFile *obj, int flags)
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.
create()
iflFile* iflFileCreate(iflFile *obj, const char *filename,
iflFile* source, const iflFileConfig* cfg,
iflFormat* format, iflStatus* status)
iflFile* iflFileCreateByDescriptor(iflFile *obj,
int fd, const char *filename,
iflFile* source,
const iflFileConfig* cfg,
iflFormat* format,
iflStatus* status)
iflFile* iflFileCreatePreParsed(iflFile *obj, iflFileDesc* fileDesc,
iflFile* source,
const iflFileConfig* cfg,
Page 6
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
iflStatus* status)
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*.
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.
flush()
iflStatus iflFileFlush(iflFile *obj)
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.
Page 7
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)freeICCProfile()
virtual iflStatus iflFileFreeICCProfile(iflFile *obj,
void* profile)
The virtual member function frees the profile returned by
getICCProfile().
getChannelPermutation()
int* iflFileGetChannelPermutation(iflFile *obj)
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 iflFileGetColorModel(iflFile *obj)
This member function returns the color model of the current image in
the image file.
getColormap()
iflStatus iflFileGetColormap(iflFile *obj, 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.
getCompression()
iflCompression iflFileGetCompression(iflFile *obj)
Page 8
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
Returns the compression method used for the current image in the
image file.
getCsize()
int iflFileGetCsize(iflFile *obj)
Returns the number of channels in the current image in the image
file.
getCurrentImg()
int iflFileGetCurrentImg(iflFile *obj)
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 iflFileGetDataType(iflFile *obj)
This member function returns the data type of the current image in
the image file.
getDimensions()
void iflFileGetDimensions(iflFile *obj, 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 iflFileGetFileDesc(iflFile *obj)
This member function returns the file descriptor used to access the
image file.
getFileMode()
int iflFileGetFileMode(iflFile *obj)
Page 9
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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* iflFileGetFileName(iflFile *obj)
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* iflFileGetFormat(iflFile *obj)
Returns a pointer to the file format associated with the file. The
pointed-to object is static and valid forever.
getICCProfile()
virtual iflStatus iflFileGetICCProfile(iflFile *obj, 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 iflFileGetItemV(iflFile *obj, 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.
Page 10
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)getNumImgs()
int iflFileGetNumImgs(iflFile *obj)
This virtual member function returns the number of images contained
in the image file.
getOrder()
iflOrder iflFileGetOrder(iflFile *obj)
Returns the dimension order of the current image in the image file.
getOrientation()
iflOrientation iflFileGetOrientation(iflFile *obj)
Returns the orientation of the current image in the image file.
getPage()
iflStatus iflFileGetPage(iflFile *obj, 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).
Page 11
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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).
getPageDimensions()
void iflFileGetPageDimensions(iflFile *obj, iflSize* pageDims)
Returns the natural page dimensions of the current image in the
image file, expressed as x == width, y == height.
getPageSize()
void iflFileGetPageSize(iflFile *obj, 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()
iflStatus iflFileGetScaleMinMax(iflFile *obj,
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 iflFileGetSize(iflFile *obj, 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.
Page 12
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)getStatMinMax()
iflStatus iflFileGetStatMinMax(iflFile *obj, 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.
getTile()
iflStatus iflFileGetTile(iflFile *obj, int x, int y, int z,
int nx, int ny, int nz, void *data,
const iflConfig* config)
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 iflFileGetZsize(iflFile *obj)
Returns the Z component of the size of the current image in the
image file.
Page 13
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)haveAttributesChanged()
int iflFileHaveAttributesChanged(iflFile *obj)
Returns TRUE if any image attributes have changed due to a call to
setItem() since last call to this method.
open()
iflFile* iflFileOpen(iflFile *obj, const char* filename,
int mode, iflStatus* status)
iflFile* iflFileOpenByDescriptor(iflFile *obj,
int fd, const char* filename,
int mode, iflFormat* format,
iflStatus* status)
iflFile* iflFileOpenPreParsed(iflFile *obj, iflFileDesc* fileDesc,
int mode, iflStatus* status)
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
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.
Page 14
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 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.
parseFileName()
char* iflFileParseFileName(iflFile *obj, const char* fullname,
char** formatName,
int* index, char** formatArgs)
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.
This function is called automatically by the open() member function.
setColormap()
iflStatus iflFileSetColormap(iflFile *obj, 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()
iflStatus iflFileSetCurrentImg(iflFile *obj, int i)
Page 15
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)
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.
virtual iflStatus iflFileSetICCProfile(iflFile *obj, 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, ...)
iflStatus iflFileSetItemV(iflFile *obj, 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.
Page 16
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)setPage()
iflStatus iflFileSetPage(iflFile *obj, 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 MP safety issues apply here as for getPage() (see above).
setScaleMinMax()
iflStatus iflFileSetScaleMinMax(iflFile *obj,
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()
iflStatus iflFileSetStatMinMax(iflFile *obj, 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.
Page 17
iflFile(3) Image Format Library C++ Reference Manual iflFile(3)setTile()
iflStatus iflFileSetTile(iflFile *obj, int x, int y, int z,
int nx, int ny, int nz, const void *data,
const iflConfig* config)
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.
SEE ALSOiflFormat(3), iflSize(3), iflFileDesc(3)
Page 18
