home *** CD-ROM | disk | FTP | other *** search
Text File | 2002-10-03 | 57.6 KB | 1,189 lines
iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) NNNNAAAAMMMMEEEE iiiiffffllllFFFFiiiilllleeee - abstraction for image file access IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM This is a base class HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <ifl/iflCdefs.h> CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN 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. CCCCrrrreeeeaaaattttiiiinnnngggg aaaannnndddd ddddeeeessssttttrrrrooooyyyyiiiinnnngggg An IFL application opens a file by calling iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() (to open an existing image file) or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee() (to create a new image file). The returned value is an _i_f_l_F_i_l_e* 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 cccclllloooosssseeee() member function. Buffered data is automatically flushed during the close(), but the application may elect to explicitly flush at any time by calling fffflllluuuusssshhhh(). 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. AAAAcccccccceeeessssssssiiiinnnngggg iiiimmmmaaaaggggeeee ddddaaaattttaaaa 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 ggggeeeettttTTTTiiiilllleeee() and sssseeeettttTTTTiiiilllleeee(), which allow reading and writing of arbitrary rectangular regions (_t_i_l_e_s), with an arbitrary data type, dimension ordering, and orientation. Optimized applications may want to use the lower-level ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee() interface, which does no conversion and requires the specified region to be one of the file's natural _p_a_g_e_s. The IFL library implements ggggeeeettttTTTTiiiilllleeee() and sssseeeettttTTTTiiiilllleeee() in terms of ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee(), which are defined by the format-specific subclasses of iflFile. PPPPaaaaggggeeee 1111 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) AAAAcccccccceeeessssssssiiiinnnngggg ssssuuuubbbb----iiiimmmmaaaaggggeeeessss 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 sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() method. The current index and total number of images in the file can be queried by calling the ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() or ggggeeeettttNNNNuuuummmmIIIImmmmggggssss() method, respectively. The initial index may also be set by specifying an index with the filename argument to iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() (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, ggggeeeettttNNNNuuuummmmIIIImmmmggggssss() returns 1, ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg() returns 0, and sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(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 aaaappppppppeeeennnnddddIIIImmmmgggg() member function. IIIICCCCCCCC pppprrrrooooffffiiiilllleeeessss An ICC (International Color Consortium) profile can be used for color management; see _h_t_t_p://_w_w_w._c_o_l_o_r._o_r_g for more details on the specifics of how such profiles are used. To access the profile for those formats that support it, call ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). When you are done with the profile call ffffrrrreeeeeeeeIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee() to release any allocated memory. You can update the profile of an image by calling sssseeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). 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. FFFFoooorrrrmmmmaaaatttt----ssssppppeeeecccciiiiffffiiiicccc ooooppppeeeerrrraaaattttiiiioooonnnnssss The member functions ggggeeeettttIIIItttteeeemmmm() and sssseeeettttIIIItttteeeemmmm() 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. DDDDeeeeaaaalllliiiinnnngggg wwwwiiiitttthhhh ccccoooonnnnccccuuuurrrrrrrreeeennnntttt aaaacccccccceeeesssssssseeeessss If an IFL application is going to make concurrent calls to an iflFile's ggggeeeettttPPPPaaaaggggeeee() and/or sssseeeettttPPPPaaaaggggeeee() methods, it must provide the iflFile object PPPPaaaaggggeeee 2222 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) with a semaphore mechanism. The application does this by supplying a beginFileIO callback with sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() (which should acquire a semaphore) and an endFileIO callback with sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() (which should release the semaphore). These callbacks will be called by ggggeeeettttPPPPaaaaggggeeee() and sssseeeettttPPPPaaaaggggeeee() surrounding thread-unsafe code. See the next section for the DSO implementor's interface to this mechanism. DDDDEEEERRRRIIIIVVVVIIIINNNNGGGG SSSSUUUUBBBBCCCCLLLLAAAASSSSSSSSEEEESSSS iflFile subclass implementors must surround code that needs to be executed atomically with calls to the protected bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO() and eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() 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 llllsssseeeeeeeekkkk() and a subsequent rrrreeeeaaaadddd() or wwwwrrrriiiitttteeee(); this code must be surrounded by bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO()/eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() to insure that concurrent calls don't change the I/O pointer between the seek and the read or write. If the underlying sssseeeettttPPPPaaaaggggeeee()/ggggeeeettttPPPPaaaaggggeeee() code is completely non-MP-safe, the implementor may choose to surround the entire function bodies with bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO()/eeeennnnddddFFFFiiiilllleeeeIIIIOOOO(). CCCCrrrreeeeaaaattttiiiinnnngggg aaaannnndddd ddddeeeessssttttrrrrooooyyyyiiiinnnngggg The IFL library's functions ooooppppeeeennnn()/ccccrrrreeeeaaaatttteeee()/cccclllloooosssseeee() methods call the ooooppppeeeennnnFFFFiiiilllleeee()/ccccrrrreeeeaaaatttteeeeFFFFiiiilllleeee()/cccclllloooosssseeeeFFFFiiiilllleeee() 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. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY OOOOppppeeeennnn////ccccrrrreeeeaaaatttteeee////cccclllloooosssseeee mmmmeeeetttthhhhooooddddssss 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) PPPPaaaaggggeeee 3333 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) 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) PPPPuuuubbbblllliiiicccc ffffuuuunnnnccccttttiiiioooonnnnssss ttttoooo ggggeeeetttt////sssseeeetttt iiiimmmmaaaaggggeeee ddddaaaattttaaaa 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) MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg tttthhhheeee ccccuuuurrrrrrrreeeennnntttt iiiimmmmaaaaggggeeee iiiinnnnddddeeeexxxx int iflFileGetNumImgs(iflFile *obj) int iflFileGetCurrentImg(iflFile *obj) iflStatus iflFileSetCurrentImg(iflFile *obj, int i) AAAAddddddddiiiinnnngggg iiiimmmmaaaaggggeeeessss iflStatus iflFileAppendImg(iflFile *obj, iflFile* source, iflFileConfig* fc) AAAAttttttttrrrriiiibbbbuuuutttteeee qqqquuuueeeerrrryyyy 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) PPPPaaaaggggeeee 4444 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) 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) AAAAttttttttrrrriiiibbbbuuuutttteeee sssseeeettttttttiiiinnnngggg 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) IIIICCCCCCCC pppprrrrooooffffiiiilllleeee aaaacccccccceeeessssssss 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) FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS aaaappppppppeeeennnnddddIIIImmmmgggg(((()))) 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. PPPPaaaaggggeeee 5555 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) The _s_o_u_r_c_e and _c_f_g parameters are treated the same as in the _c_r_e_a_t_e() static member function. On success, the function returns iflOKAY. If the operation fails for some reason, an IFL error will be thrown via the iiiiffffllllEEEErrrrrrrroooorrrr() 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 _I_F_L__C_L_O_S_E__D_I_S_C_A_R_D 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 iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee(). If the caller wants to keep the file descriptor open, it must dddduuuupppp() the file descriptor beforehand and use the resulting file descriptor as the argument to the original iiiiffffllllFFFFiiiilllleeee::::::::ooooppppeeeennnn() or iiiiffffllllFFFFiiiilllleeee::::::::ccccrrrreeeeaaaatttteeee(). Then _f_l_a_g_s parameter is the bitwise "or" of zero or more of the following: _I_F_L__C_L_O_S_E__D_I_S_C_A_R_D The default behavior is to call the fffflllluuuusssshhhh() 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. ccccrrrreeeeaaaatttteeee(((()))) 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, PPPPaaaaggggeeee 6666 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) iflStatus* status) This static class member function creates a new image file with the specified name and attributes. The _f_i_l_e_n_a_m_e argument specifies the file name of the file to be created. An existing file descriptor may be given additionally or instead using the _f_d parameter, exactly as for ooooppppeeeennnn(). The _f_o_r_m_a_t 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 iiiiffffllllFFFFoooorrrrmmmmaaaatttt::::::::ffffiiiinnnnddddBBBByyyyFFFFoooorrrrmmmmaaaattttNNNNaaaammmmeeee("TIFF") is used by default. The alternate form taking a _f_i_l_e_D_e_s_c argument, encapsulates the _f_d, _f_i_l_e_n_a_m_e and _f_o_r_m_a_t 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 _c_f_g parameter; if not, they are copied from the _s_o_u_r_c_e iflFile* if one was given (as described below) or defaulted to the format's "preferred" value for the respective parameter. When an existing _s_o_u_r_c_e iflFile* is specified; any parameters not specified in the _c_f_g 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 cccclllloooosssseeee() method. On failure, the function returns NULL and, if the _s_t_a_t_u_s argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value. fffflllluuuusssshhhh(((()))) 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 cccclllloooosssseeee() member function (but this can be overridden, see description of cccclllloooosssseeee() above). It should return iflOKAY on success, or an appropriate iflStatus error value on failure. PPPPaaaaggggeeee 7777 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) ffffrrrreeeeeeeeIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(((()))) virtual iflStatus iflFileFreeICCProfile(iflFile *obj, void* profile) The virtual member function frees the profile returned by ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(). ggggeeeettttCCCChhhhaaaannnnnnnneeeellllPPPPeeeerrrrmmmmuuuuttttaaaattttiiiioooonnnn(((()))) 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 ggggeeeettttPPPPaaaaggggeeee()/sssseeeettttPPPPaaaaggggeeee()). This should be used by callers of ggggeeeettttPPPPaaaaggggeeee()/sssseeeettttPPPPaaaaggggeeee() to re-order the data. ggggeeeettttCCCCoooolllloooorrrrMMMMooooddddeeeellll(((()))) iflColorModel iflFileGetColorModel(iflFile *obj) This member function returns the color model of the current image in the image file. ggggeeeettttCCCCoooolllloooorrrrmmmmaaaapppp(((()))) 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 _c_m_a_p 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 sssseeeettttCCCCoooolllloooorrrrmmmmaaaapppp(), sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(), aaaappppppppeeeennnnddddIIIImmmmgggg(), cccclllloooosssseeee(), or calls to sssseeeettttIIIItttteeeemmmm() 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 _c_m_a_p is undefined. ggggeeeettttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(((()))) iflCompression iflFileGetCompression(iflFile *obj) PPPPaaaaggggeeee 8888 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) Returns the compression method used for the current image in the image file. ggggeeeettttCCCCssssiiiizzzzeeee(((()))) int iflFileGetCsize(iflFile *obj) Returns the number of channels in the current image in the image file. ggggeeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(((()))) 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. ggggeeeettttDDDDaaaattttaaaaTTTTyyyyppppeeee(((()))) iflDataType iflFileGetDataType(iflFile *obj) This member function returns the data type of the current image in the image file. ggggeeeettttDDDDiiiimmmmeeeennnnssssiiiioooonnnnssss(((()))) 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. ggggeeeettttFFFFiiiilllleeeeDDDDeeeesssscccc(((()))) int iflFileGetFileDesc(iflFile *obj) This member function returns the file descriptor used to access the image file. ggggeeeettttFFFFiiiilllleeeeMMMMooooddddeeee(((()))) int iflFileGetFileMode(iflFile *obj) PPPPaaaaggggeeee 9999 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This member function returns the access mode by which the file can be accessed. It is _O__R_D_O_N_L_Y, _O__W_R_O_N_L_Y, or _O__R_D_W_R. ggggeeeettttFFFFiiiilllleeeeNNNNaaaammmmeeee(((()))) 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. ggggeeeettttFFFFoooorrrrmmmmaaaatttt(((()))) iflFormat* iflFileGetFormat(iflFile *obj) Returns a pointer to the file format associated with the file. The pointed-to object is static and valid forever. ggggeeeettttIIIICCCCCCCCPPPPrrrrooooffffiiiilllleeee(((()))) 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. ggggeeeettttIIIItttteeeemmmm(((()))) 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 _t_a_g 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 _a_p through some wrapper layer. PPPPaaaaggggeeee 11110000 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) ggggeeeettttNNNNuuuummmmIIIImmmmggggssss(((()))) int iflFileGetNumImgs(iflFile *obj) This virtual member function returns the number of images contained in the image file. ggggeeeettttOOOOrrrrddddeeeerrrr(((()))) iflOrder iflFileGetOrder(iflFile *obj) Returns the dimension order of the current image in the image file. ggggeeeettttOOOOrrrriiiieeeennnnttttaaaattttiiiioooonnnn(((()))) iflOrientation iflFileGetOrientation(iflFile *obj) Returns the orientation of the current image in the image file. ggggeeeettttPPPPaaaaggggeeee(((()))) 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 _d_a_t_a argument specifies the address of the memory buffer into which the data should be placed. The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the desired page within the source image file. The caller must guarantee that _n_x,_n_y,_n_z and _n_c 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 ggggeeeettttPPPPaaaaggggeeee() 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 ggggeeeettttPPPPaaaaggggeeee() and/or sssseeeettttPPPPaaaaggggeeee(), it needs to set I/O callbacks (see the description of sssseeeettttBBBBeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB(), sssseeeettttEEEEnnnnddddFFFFiiiilllleeeeIIIIOOOO____CCCCBBBB() for how to do this). PPPPaaaaggggeeee 11111111 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) This function is required to surround code that must be executed atomically by calls to bbbbeeeeggggiiiinnnnFFFFiiiilllleeeeIIIIOOOO() and eeeennnnddddFFFFiiiilllleeeeIIIIOOOO() (see the descriptions of these functions for more details and common cases where this is necessary). ggggeeeettttPPPPaaaaggggeeeeDDDDiiiimmmmeeeennnnssssiiiioooonnnnssss(((()))) 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. ggggeeeettttPPPPaaaaggggeeeeSSSSiiiizzzzeeee(((()))) 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. ggggeeeettttSSSSccccaaaalllleeeeMMMMiiiinnnnMMMMaaaaxxxx(((()))) 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 _m_i_n and _m_a_x 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. ggggeeeettttSSSSiiiizzzzeeee(((()))) 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. PPPPaaaaggggeeee 11112222 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) ggggeeeettttSSSSttttaaaattttMMMMiiiinnnnMMMMaaaaxxxx(((()))) 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 _m_i_n and _m_a_x 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. ggggeeeettttTTTTiiiilllleeee(((()))) 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,_n_x,_n_y and _n_z specify the origin and size of the desired tile within the source image file, in the coordinate space indicated in the _c_o_n_f_i_g parameter. The _d_a_t_a argument specifies the address of the memory buffer into which the data should be placed. The _c_o_n_f_i_g argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of _x,_y,_z,_n_x,_n_y and _n_z, as described above. If defaulted, attributes of the buffer are assumed to match those of the image. A successful call to ggggeeeettttTTTTiiiilllleeee() returns iflOKAY. If an error occurs, an iflStatus value is returned describing the error; in this case the buffer's contents are undefined. ggggeeeettttZZZZssssiiiizzzzeeee(((()))) int iflFileGetZsize(iflFile *obj) Returns the Z component of the size of the current image in the image file. PPPPaaaaggggeeee 11113333 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) hhhhaaaavvvveeeeAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd(((()))) int iflFileHaveAttributesChanged(iflFile *obj) Returns TRUE if any image attributes have changed due to a call to sssseeeettttIIIItttteeeemmmm() since last call to this method. ooooppppeeeennnn(((()))) 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 _f_i_l_e_n_a_m_e and _f_d 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 sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmaaaaggggeeee() 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__R_D_O_N_L_Y or _O__R_D_W_R. The _f_o_r_m_a_t 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 _f_i_l_e_D_e_s_c argument, encapsulates the _f_d, _f_i_l_e_n_a_m_e and _f_o_r_m_a_t arguments in this single argument. See iflFileDesc(3) for more details. PPPPaaaaggggeeee 11114444 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) 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 cccclllloooosssseeee() method. On failure, the function returns NULL and, if the _s_t_a_t_u_s argument is non-NULL, sets the pointed-to iflStatus value to the appropriate error value. ppppaaaarrrrsssseeeeFFFFiiiilllleeeeNNNNaaaammmmeeee(((()))) 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 _f_o_r_m_a_t_N_a_m_e 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 _i_n_d_e_x 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 _f_o_r_m_a_t_A_r_g_s 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. sssseeeettttCCCCoooolllloooorrrrmmmmaaaapppp(((()))) 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 _c_m_a_p. 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. sssseeeettttCCCCuuuurrrrrrrreeeennnnttttIIIImmmmgggg(((()))) iflStatus iflFileSetCurrentImg(iflFile *obj, int i) PPPPaaaaggggeeee 11115555 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) 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 _i_d_x. 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 iiiiffffllllSSSSttttaaaattttuuuussssEEEEnnnnccccooooddddeeee(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 iiiiffffllllEEEErrrrrrrroooorrrr() 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. sssseeeettttIIIItttteeeemmmm(((()))) 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 sssseeeettttIIIItttteeeemmmm() may change some image attributes. This can be check by calling hhhhaaaavvvveeeeAAAAttttttttrrrriiiibbbbuuuutttteeeessssCCCChhhhaaaannnnggggeeeedddd() after calling sssseeeettttIIIItttteeeemmmm(). The _t_a_g 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 _a_p through some wrapper layer. PPPPaaaaggggeeee 11116666 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) sssseeeettttPPPPaaaaggggeeee(((()))) 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 _d_a_t_a argument specifies the address of the memory buffer containing the data to be written. The arguments _x,_y,_z,_n_x,_n_y and _n_z specify the origin and size of the desired page within the source image file. The caller must guarantee that _n_x,_n_y,_n_z and _n_c 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 sssseeeettttPPPPaaaaggggeeee() 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 ggggeeeettttPPPPaaaaggggeeee() (see above). sssseeeettttSSSSccccaaaalllleeeeMMMMiiiinnnnMMMMaaaaxxxx(((()))) 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. sssseeeettttSSSSttttaaaattttMMMMiiiinnnnMMMMaaaaxxxx(((()))) 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. PPPPaaaaggggeeee 11117777 iiiiffffllllFFFFiiiilllleeee((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllFFFFiiiilllleeee((((3333)))) sssseeeettttTTTTiiiilllleeee(((()))) 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,_n_x,_n_y and _n_z specify the origin and size of the target tile within the destination image file, in the coordinate space indicated in the _c_o_n_f_i_g parameter. The _d_a_t_a argument specifies the address of the memory buffer containing the data to be written. The _c_o_n_f_i_g argument describes the configuration of the memory buffer, and its orientation also affects the interpretation of _x,_y,_z,_n_x,_n_y and _n_z, as described above. If defaulted, attributes of the buffer are assumed to match those of the image. A successful call to sssseeeettttTTTTiiiilllleeee() 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 sssseeeettttTTTTiiiilllleeee() may need to make calls to the subclass's ggggeeeettttPPPPaaaaggggeeee() as well as setPage() in order to write a tile that is not aligned with the file's pages. SSSSEEEEEEEE AAAALLLLSSSSOOOO iflFormat(3), iflSize(3), iflFileDesc(3) PPPPaaaaggggeeee 11118888 
