diff options
Diffstat (limited to 'libtiff')
| -rw-r--r-- | libtiff/tif_close.c | 19 | ||||
| -rw-r--r-- | libtiff/tif_codec.c | 15 | ||||
| -rw-r--r-- | libtiff/tif_compress.c | 12 | ||||
| -rw-r--r-- | libtiff/tif_dir.c | 44 | ||||
| -rw-r--r-- | libtiff/tif_dirread.c | 11 | ||||
| -rw-r--r-- | libtiff/tif_extension.c | 8 | ||||
| -rw-r--r-- | libtiff/tif_flush.c | 9 | ||||
| -rw-r--r-- | libtiff/tif_open.c | 64 | ||||
| -rw-r--r-- | libtiff/tif_read.c | 9 | ||||
| -rw-r--r-- | libtiff/tif_strip.c | 37 | ||||
| -rw-r--r-- | libtiff/tif_tile.c | 12 | ||||
| -rw-r--r-- | libtiff/tif_write.c | 6 | ||||
| -rw-r--r-- | libtiff/tiffio.h | 1350 | ||||
| -rw-r--r-- | libtiff/tiffiop.h | 11 |
14 files changed, 1176 insertions, 431 deletions
diff --git a/libtiff/tif_close.c b/libtiff/tif_close.c index 04977bc7..d3bcccb1 100644 --- a/libtiff/tif_close.c +++ b/libtiff/tif_close.c @@ -32,15 +32,6 @@ /* TIFFCleanup() */ /************************************************************************/ -/** - * Auxiliary function to free the TIFF structure. Given structure will be - * completely freed, so you should save opened file handle and pointer - * to the close procedure in external variables before calling - * _TIFFCleanup(), if you will need these ones to close the file. - * - * @param tif A TIFF pointer. - */ - void TIFFCleanup(TIFF* tif) { @@ -112,16 +103,6 @@ TIFFCleanup(TIFF* tif) /* TIFFClose() */ /************************************************************************/ -/** - * Close a previously opened TIFF file. - * - * TIFFClose closes a file that was previously opened with TIFFOpen(). - * Any buffered data are flushed to the file, including the contents of - * the current directory (if modified); and all resources are reclaimed. - * - * @param tif A TIFF pointer. - */ - void TIFFClose(TIFF* tif) { diff --git a/libtiff/tif_codec.c b/libtiff/tif_codec.c index 931eb093..ef9a8123 100644 --- a/libtiff/tif_codec.c +++ b/libtiff/tif_codec.c @@ -80,8 +80,8 @@ static int NotConfigured(TIFF*, int); #define TIFFInitWebP NotConfigured #endif -/* - * Compression schemes statically built into the library. +/** + * @brief Built-in compression schemes. */ const TIFFCodec _TIFFBuiltinCODECS[] = { { "None", COMPRESSION_NONE, TIFFInitDumpMode }, @@ -134,17 +134,6 @@ NotConfigured(TIFF* tif, int scheme) return (1); } -/************************************************************************/ -/* TIFFIsCODECConfigured() */ -/************************************************************************/ - -/** - * Check whether we have working codec for the specific coding scheme. - * - * @return returns 1 if the codec is configured and working. Otherwise - * 0 will be returned. - */ - int TIFFIsCODECConfigured(uint16_t scheme) { diff --git a/libtiff/tif_compress.c b/libtiff/tif_compress.c index 8fcedf45..0645c2b6 100644 --- a/libtiff/tif_compress.c +++ b/libtiff/tif_compress.c @@ -235,18 +235,6 @@ TIFFUnRegisterCODEC(TIFFCodec* c) "Cannot remove compression scheme %s; not registered", c->name); } -/************************************************************************/ -/* TIFFGetConfisuredCODECs() */ -/************************************************************************/ - -/** - * Get list of configured codecs, both built-in and registered by user. - * Caller is responsible to free this structure. - * - * @return returns array of TIFFCodec records (the last record should be NULL) - * or NULL if function failed. - */ - TIFFCodec* TIFFGetConfiguredCODECs() { diff --git a/libtiff/tif_dir.c b/libtiff/tif_dir.c index e90f14a0..45ff2941 100644 --- a/libtiff/tif_dir.c +++ b/libtiff/tif_dir.c @@ -1272,10 +1272,6 @@ _TIFFVGetField(TIFF* tif, uint32_t tag, va_list ap) return(ret_val); } -/* - * Return the value of a field in the - * internal directory structure. - */ int TIFFGetField(TIFF* tif, uint32_t tag, ...) { @@ -1288,12 +1284,6 @@ TIFFGetField(TIFF* tif, uint32_t tag, ...) return (status); } -/* - * Like TIFFGetField, but taking a varargs - * parameter list. This routine is useful - * for building higher-level interfaces on - * top of the library. - */ int TIFFVGetField(TIFF* tif, uint32_t tag, va_list ap) { @@ -1309,9 +1299,6 @@ TIFFVGetField(TIFF* tif, uint32_t tag, va_list ap) } \ } -/* - * Release storage associated with a directory. - */ void TIFFFreeDirectory(TIFF* tif) { @@ -1364,13 +1351,6 @@ TIFFSetTagExtender(TIFFExtendProc extender) return (prev); } -/* - * Setup for a new directory. Should we automatically call - * TIFFWriteDirectory() if the current one is dirty? - * - * The newly created directory will not exist on the file till - * TIFFWriteDirectory(), TIFFFlush() or TIFFClose() is called. - */ int TIFFCreateDirectory(TIFF* tif) { @@ -1413,9 +1393,6 @@ TIFFCreateEXIFDirectory(TIFF* tif) return TIFFCreateCustomDirectory(tif, exifFieldArray); } -/* - * Creates the EXIF GPS custom directory - */ int TIFFCreateGPSDirectory(TIFF* tif) { @@ -1638,9 +1615,6 @@ TIFFAdvanceDirectory(TIFF* tif, uint64_t* nextdir, uint64_t* off) } } -/* - * Count the number of directories in a file. - */ uint16_t TIFFNumberOfDirectories(TIFF* tif) { @@ -1668,10 +1642,7 @@ TIFFNumberOfDirectories(TIFF* tif) return (n); } -/* - * Set the n-th directory as the current directory. - * NB: Directories are numbered starting at 0. - */ + int TIFFSetDirectory(TIFF* tif, uint16_t dirn) { @@ -1700,12 +1671,6 @@ TIFFSetDirectory(TIFF* tif, uint16_t dirn) return (TIFFReadDirectory(tif)); } -/* - * Set the current directory to be the directory - * located at the specified file offset. This interface - * is used mainly to access directories linked with - * the SubIFD tag (e.g. thumbnail images). - */ int TIFFSetSubDirectory(TIFF* tif, uint64_t diroff) { @@ -1718,19 +1683,12 @@ TIFFSetSubDirectory(TIFF* tif, uint64_t diroff) return (TIFFReadDirectory(tif)); } -/* - * Return file offset of the current directory. - */ uint64_t TIFFCurrentDirOffset(TIFF* tif) { return (tif->tif_diroff); } -/* - * Return an indication of whether or not we are - * at the last directory in the file. - */ int TIFFLastDirectory(TIFF* tif) { diff --git a/libtiff/tif_dirread.c b/libtiff/tif_dirread.c index 32653f04..104a2963 100644 --- a/libtiff/tif_dirread.c +++ b/libtiff/tif_dirread.c @@ -3904,10 +3904,6 @@ static int ByteCountLooksBad(TIFF* tif) } -/* - * Read the next TIFF directory from a file and convert it to the internal - * format. We read directories sequentially. - */ int TIFFReadDirectory(TIFF* tif) { @@ -4885,10 +4881,6 @@ TIFFReadCustomDirectory(TIFF* tif, toff_t diroff, return 1; } -/* - * EXIF is important special case of custom IFD, so we have a special - * function to read it. - */ int TIFFReadEXIFDirectory(TIFF* tif, toff_t diroff) { @@ -4897,9 +4889,6 @@ TIFFReadEXIFDirectory(TIFF* tif, toff_t diroff) return TIFFReadCustomDirectory(tif, diroff, exifFieldArray); } -/* - *--: EXIF-GPS custom directory reading as another special case of custom IFD. - */ int TIFFReadGPSDirectory(TIFF* tif, toff_t diroff) { diff --git a/libtiff/tif_extension.c b/libtiff/tif_extension.c index 9d46d3ea..9c0314a0 100644 --- a/libtiff/tif_extension.c +++ b/libtiff/tif_extension.c @@ -22,11 +22,11 @@ * OF THIS SOFTWARE. */ -/* - * TIFF Library. +/** + * @file LibTIFF extensions. * - * Various routines support external extension of the tag set, and other - * application extension capabilities. + * Support for external extension of the tag set, and other + * application-extension capabilities. */ #include "tiffiop.h" diff --git a/libtiff/tif_flush.c b/libtiff/tif_flush.c index f7fa2072..8710c515 100644 --- a/libtiff/tif_flush.c +++ b/libtiff/tif_flush.c @@ -142,15 +142,6 @@ int TIFFForceStrileArrayWriting(TIFF* tif) return 0; } -/* - * Flush buffered data to the file. - * - * Frank Warmerdam'2000: I modified this to return 1 if TIFF_BEENWRITING - * is not set, so that TIFFFlush() will proceed to write out the directory. - * The documentation says returning 1 is an error indicator, but not having - * been writing isn't exactly a an error. Hopefully this doesn't cause - * problems for other people. - */ int TIFFFlushData(TIFF* tif) { diff --git a/libtiff/tif_open.c b/libtiff/tif_open.c index 549f56ce..6e9fc410 100644 --- a/libtiff/tif_open.c +++ b/libtiff/tif_open.c @@ -525,18 +525,12 @@ TIFFSetFileName(TIFF* tif, const char *name) return (old_name); } -/* - * Return open file's I/O descriptor. - */ int TIFFFileno(TIFF* tif) { return (tif->tif_fd); } -/* - * Set open file's I/O descriptor, and return previous value. - */ int TIFFSetFileno(TIFF* tif, int fd) { @@ -545,18 +539,12 @@ TIFFSetFileno(TIFF* tif, int fd) return old_fd; } -/* - * Return open file's clientdata. - */ thandle_t TIFFClientdata(TIFF* tif) { return (tif->tif_clientdata); } -/* - * Set open file's clientdata, and return previous value. - */ thandle_t TIFFSetClientdata(TIFF* tif, thandle_t newvalue) { @@ -565,18 +553,12 @@ TIFFSetClientdata(TIFF* tif, thandle_t newvalue) return m; } -/* - * Return read/write mode. - */ int TIFFGetMode(TIFF* tif) { return (tif->tif_mode); } -/* - * Return read/write mode. - */ int TIFFSetMode(TIFF* tif, int mode) { @@ -585,73 +567,48 @@ TIFFSetMode(TIFF* tif, int mode) return (old_mode); } -/* - * Return nonzero if file is organized in - * tiles; zero if organized as strips. - */ int TIFFIsTiled(TIFF* tif) { return (isTiled(tif)); } -/* - * Return current row being read/written. - */ uint32_t TIFFCurrentRow(TIFF* tif) { return (tif->tif_row); } -/* - * Return index of the current directory. - */ uint16_t TIFFCurrentDirectory(TIFF* tif) { return (tif->tif_curdir); } -/* - * Return current strip. - */ uint32_t TIFFCurrentStrip(TIFF* tif) { return (tif->tif_curstrip); } -/* - * Return current tile. - */ uint32_t TIFFCurrentTile(TIFF* tif) { return (tif->tif_curtile); } -/* - * Return nonzero if the file has byte-swapped data. - */ int TIFFIsByteSwapped(TIFF* tif) { return ((tif->tif_flags & TIFF_SWAB) != 0); } -/* - * Return nonzero if the data is returned up-sampled. - */ int TIFFIsUpSampled(TIFF* tif) { return (isUpSampled(tif)); } -/* - * Return nonzero if the data is returned in MSB-to-LSB bit order. - */ int TIFFIsMSB2LSB(TIFF* tif) { @@ -676,63 +633,42 @@ TIFFIsBigTIFF(TIFF *tif) return (tif->tif_header.common.tiff_version == TIFF_VERSION_BIG); } -/* - * Return pointer to file read method. - */ TIFFReadWriteProc TIFFGetReadProc(TIFF* tif) { return (tif->tif_readproc); } -/* - * Return pointer to file write method. - */ TIFFReadWriteProc TIFFGetWriteProc(TIFF* tif) { return (tif->tif_writeproc); } -/* - * Return pointer to file seek method. - */ TIFFSeekProc TIFFGetSeekProc(TIFF* tif) { return (tif->tif_seekproc); } -/* - * Return pointer to file close method. - */ TIFFCloseProc TIFFGetCloseProc(TIFF* tif) { return (tif->tif_closeproc); } -/* - * Return pointer to file size requesting method. - */ TIFFSizeProc TIFFGetSizeProc(TIFF* tif) { return (tif->tif_sizeproc); } -/* - * Return pointer to memory mapping method. - */ TIFFMapFileProc TIFFGetMapFileProc(TIFF* tif) { return (tif->tif_mapproc); } -/* - * Return pointer to memory unmapping method. - */ TIFFUnmapFileProc TIFFGetUnmapFileProc(TIFF* tif) { diff --git a/libtiff/tif_read.c b/libtiff/tif_read.c index 66f2e402..168d3569 100644 --- a/libtiff/tif_read.c +++ b/libtiff/tif_read.c @@ -1260,15 +1260,6 @@ TIFFFillTile(TIFF* tif, uint32_t tile) return (TIFFStartTile(tif, tile)); } -/* - * Setup the raw data buffer in preparation for - * reading a strip of raw data. If the buffer - * is specified as zero, then a buffer of appropriate - * size is allocated by the library. Otherwise, - * the client must guarantee that the buffer is - * large enough to hold any individual strip of - * raw data. - */ int TIFFReadBufferSetup(TIFF* tif, void* bp, tmsize_t size) { diff --git a/libtiff/tif_strip.c b/libtiff/tif_strip.c index d7b27526..7ab04d3c 100644 --- a/libtiff/tif_strip.c +++ b/libtiff/tif_strip.c @@ -69,9 +69,6 @@ TIFFNumberOfStrips(TIFF* tif) return (nstrips); } -/* - * Compute the # bytes in a variable height, row-aligned strip. - */ uint64_t TIFFVStripSize64(TIFF* tif, uint32_t nrows) { @@ -133,9 +130,6 @@ TIFFVStripSize(TIFF* tif, uint32_t nrows) return _TIFFCastUInt64ToSSize(tif, m, module); } -/* - * Compute the # bytes in a raw strip. - */ uint64_t TIFFRawStripSize64(TIFF* tif, uint32_t strip) { @@ -174,14 +168,6 @@ TIFFRawStripSize(TIFF* tif, uint32_t strip) return(n); } -/* - * Compute the # bytes in a (row-aligned) strip. - * - * Note that if RowsPerStrip is larger than the - * recorded ImageLength, then the strip size is - * truncated to reflect the actual space required - * to hold the strip. - */ uint64_t TIFFStripSize64(TIFF* tif) { @@ -200,12 +186,6 @@ TIFFStripSize(TIFF* tif) return _TIFFCastUInt64ToSSize(tif, m, module); } -/* - * Compute a default strip size based on the image - * characteristics and a requested value. If the - * request is <1 then we choose a strip size according - * to certain heuristics. - */ uint32_t TIFFDefaultStripSize(TIFF* tif, uint32_t request) { @@ -236,16 +216,6 @@ _TIFFDefaultStripSize(TIFF* tif, uint32_t s) return (s); } -/* - * Return the number of bytes to read/write in a call to - * one of the scanline-oriented i/o routines. Note that - * this number may be 1/samples-per-pixel if data is - * stored as separate planes. - * The ScanlineSize in case of YCbCrSubsampling is defined as the - * strip size divided by the strip height, i.e. the size of a pack of vertical - * subsampling lines divided by vertical subsampling. It should thus make - * sense when multiplied by a multiple of vertical subsampling. - */ uint64_t TIFFScanlineSize64(TIFF* tif) { @@ -303,6 +273,7 @@ TIFFScanlineSize64(TIFF* tif) } return(scanline_size); } + tmsize_t TIFFScanlineSize(TIFF* tif) { @@ -312,12 +283,6 @@ TIFFScanlineSize(TIFF* tif) return _TIFFCastUInt64ToSSize(tif, m, module); } -/* - * Return the number of bytes required to store a complete - * decoded and packed raster scanline (as opposed to the - * I/O size returned by TIFFScanlineSize which may be less - * if data is store as separate planes). - */ uint64_t TIFFRasterScanlineSize64(TIFF* tif) { diff --git a/libtiff/tif_tile.c b/libtiff/tif_tile.c index 058be9f7..87bc6c3b 100644 --- a/libtiff/tif_tile.c +++ b/libtiff/tif_tile.c @@ -135,9 +135,6 @@ TIFFNumberOfTiles(TIFF* tif) return (ntiles); } -/* - * Compute the # bytes in each row of a tile. - */ uint64_t TIFFTileRowSize64(TIFF* tif) { @@ -245,9 +242,6 @@ TIFFVTileSize(TIFF* tif, uint32_t nrows) return _TIFFCastUInt64ToSSize(tif, m, module); } -/* - * Compute the # bytes in a row-aligned tile. - */ uint64_t TIFFTileSize64(TIFF* tif) { @@ -262,12 +256,6 @@ TIFFTileSize(TIFF* tif) return _TIFFCastUInt64ToSSize(tif, m, module); } -/* - * Compute a default tile size based on the image - * characteristics and a requested value. If a - * request is <1 then we choose a size according - * to certain heuristics. - */ void TIFFDefaultTileSize(TIFF* tif, uint32_t* tw, uint32_t* th) { diff --git a/libtiff/tif_write.c b/libtiff/tif_write.c index 46e07763..745715c6 100644 --- a/libtiff/tif_write.c +++ b/libtiff/tif_write.c @@ -565,12 +565,6 @@ TIFFSetupStrips(TIFF* tif) } #undef isUnspecified -/* - * Verify file is writable and that the directory - * information is setup properly. In doing the latter - * we also "freeze" the state of the directory so - * that important information is not changed. - */ int TIFFWriteCheck(TIFF* tif, int tiles, const char* module) { diff --git a/libtiff/tiffio.h b/libtiff/tiffio.h index 18dfd11e..a9c7b7ac 100644 --- a/libtiff/tiffio.h +++ b/libtiff/tiffio.h @@ -25,15 +25,16 @@ #ifndef _TIFFIO_ #define _TIFFIO_ -/* - * TIFF I/O Library Definitions. +/** + * @file tiffio.h + * @brief TIFF I/O Library Definitions. */ #include "tiff.h" #include "tiffvers.h" -/* - * TIFF is defined as an incomplete type to hide the - * library's internal data structures from clients. +/** + * @brief A TIFF image file. + * @details The internal details of this structure are private. */ typedef struct tiff TIFF; @@ -44,38 +45,65 @@ typedef struct tiff TIFF; * in tiff.h. Note also that the varargs interface used * to pass tag types and values uses the types defined in * tiff.h directly. - * - * NB: ttag_t is unsigned int and not unsigned short because - * ANSI C requires that the type before the ellipsis be a - * promoted type (i.e. one of int, unsigned int, pointer, - * or double) and because we defined pseudo-tags that are - * outside the range of legal Aldus-assigned tags. - * NB: tsize_t is signed and not unsigned because some functions - * return -1. - * NB: toff_t is not off_t for many reasons; TIFFs max out at - * 32-bit file offsets, and BigTIFF maxes out at 64-bit - * offsets being the most important, and to ensure use of - * a consistently unsigned type across architectures. - * Prior to libtiff 4.0, this was an unsigned 32 bit type. */ -/* - * this is the machine addressing size type, only it's signed, so make it - * int32_t on 32bit machines, int64_t on 64bit machines + +/** + * @brief Signed machine addressing size type. + * @details This type int32_t on 32bit machines, int64_t on 64bit machines. */ typedef TIFF_SSIZE_T tmsize_t; + +/** + * @brief Maximum size of tmsize_t. + */ #define TIFF_TMSIZE_T_MAX (tmsize_t)(SIZE_MAX >> 1) -typedef uint64_t toff_t; /* file offset */ +/** + * @brief File offset + * @note toff_t is not off_t for many reasons; TIFFs max out at + * 32-bit file offsets, and BigTIFF maxes out at 64-bit + * offsets being the most important, and to ensure use of + * a consistently unsigned type across architectures. + * Prior to libtiff 4.0, this was an unsigned 32-bit type. + */ +typedef uint64_t toff_t; + /* the following are deprecated and should be replaced by their defining counterparts */ -typedef uint32_t ttag_t; /* directory tag */ -typedef uint16_t tdir_t; /* directory index */ -typedef uint16_t tsample_t; /* sample number */ -typedef uint32_t tstrile_t; /* strip or tile number */ -typedef tstrile_t tstrip_t; /* strip number */ -typedef tstrile_t ttile_t; /* tile number */ -typedef tmsize_t tsize_t; /* i/o size in bytes */ -typedef void* tdata_t; /* image data ref */ + +/** + * @brief Directory tag. + * @note ttag_t is unsigned int and not unsigned short because + * ANSI C requires that the type before the ellipsis be a + * promoted type (i.e. one of int, unsigned int, pointer, + * or double) and because we defined pseudo-tags that are + * outside the range of legal Aldus-assigned tags. + */ +typedef uint32_t ttag_t; + +/** Directory index */ +typedef uint16_t tdir_t; + +/** Sample number */ +typedef uint16_t tsample_t; + +/** Strip or tile number */ +typedef uint32_t tstrile_t; + +/** Strip number */ +typedef tstrile_t tstrip_t; + +/** Tile number */ +typedef tstrile_t ttile_t; + +/** I/O size in bytes + * @note tsize_t is signed and not unsigned because some functions + * return -1. + */ +typedef tmsize_t tsize_t; + +/** Image data reference */ +typedef void* tdata_t; #if !defined(__WIN32__) && (defined(_WIN32) || defined(WIN32)) #define __WIN32__ @@ -98,12 +126,15 @@ typedef void* tdata_t; /* image data ref */ # define VC_EXTRALEAN # include <windows.h> # ifdef __WIN32__ -DECLARE_HANDLE(thandle_t); /* Win32 file handle */ +/** Client data handle */ +DECLARE_HANDLE(thandle_t); # else -typedef HFILE thandle_t; /* client data handle */ +/** Client data handle */ +typedef HFILE thandle_t; # endif /* __WIN32__ */ #else -typedef void* thandle_t; /* client data handle */ +/** Client data handle */ +typedef void* thandle_t; #endif /* USE_WIN32_FILEIO */ /* @@ -112,49 +143,65 @@ typedef void* thandle_t; /* client data handle */ * very large. Bit-or these flags to enable printing * multiple items. */ -#define TIFFPRINT_NONE 0x0 /* no extra info */ -#define TIFFPRINT_STRIPS 0x1 /* strips/tiles info */ -#define TIFFPRINT_CURVES 0x2 /* color/gray response curves */ -#define TIFFPRINT_COLORMAP 0x4 /* colormap */ -#define TIFFPRINT_JPEGQTABLES 0x100 /* JPEG Q matrices */ -#define TIFFPRINT_JPEGACTABLES 0x200 /* JPEG AC tables */ -#define TIFFPRINT_JPEGDCTABLES 0x200 /* JPEG DC tables */ + +/** Print no extra information */ +#define TIFFPRINT_NONE 0x0 +/** Print strips or tiles information */ +#define TIFFPRINT_STRIPS 0x1 +/** Print color or gray response curves */ +#define TIFFPRINT_CURVES 0x2 +/** Print colormap */ +#define TIFFPRINT_COLORMAP 0x4 + +/** Print JPEG Q matrices */ +#define TIFFPRINT_JPEGQTABLES 0x100 +/** Print JPEG AC tables */ +#define TIFFPRINT_JPEGACTABLES 0x200 +/** Print JPEG DC tables */ +#define TIFFPRINT_JPEGDCTABLES 0x200 /* - * Colour conversion stuff + * Colour conversion macros. */ -/* reference white */ +/** Reference white (D65 X) */ #define D65_X0 (95.0470F) +/** Reference white (D65 Y) */ #define D65_Y0 (100.0F) +/** Reference white (D65 Z) */ #define D65_Z0 (108.8827F) +/** Reference white (D50 X) */ #define D50_X0 (96.4250F) +/** Reference white (D50 Y) */ #define D50_Y0 (100.0F) +/** Reference white (D50 Z) */ #define D50_Z0 (82.4680F) -/* Structure for holding information about a display device. */ -typedef unsigned char TIFFRGBValue; /* 8-bit samples */ +/** 8-bit R, G or B sample */ +typedef unsigned char TIFFRGBValue; +/** Display device description. */ typedef struct { - float d_mat[3][3]; /* XYZ -> luminance matrix */ - float d_YCR; /* Light o/p for reference white */ - float d_YCG; - float d_YCB; - uint32_t d_Vrwr; /* Pixel values for ref. white */ - uint32_t d_Vrwg; - uint32_t d_Vrwb; - float d_Y0R; /* Residual light for black pixel */ - float d_Y0G; - float d_Y0B; - float d_gammaR; /* Gamma values for the three guns */ - float d_gammaG; - float d_gammaB; + float d_mat[3][3]; /**< XYZ -> luminance matrix */ + float d_YCR; /**< Light o/p for reference white (R) */ + float d_YCG; /**< Light o/p for reference white (G) */ + float d_YCB; /**< Light o/p for reference white (B) */ + uint32_t d_Vrwr; /**< Pixel values for reference white (R) */ + uint32_t d_Vrwg; /**< Pixel values for reference white (G) */ + uint32_t d_Vrwb; /**< Pixel values for reference white (B) */ + float d_Y0R; /**< Residual light for black pixel (R) */ + float d_Y0G; /**< Residual light for black pixel (G) */ + float d_Y0B; /**< Residual light for black pixel (B) */ + float d_gammaR; /**< Gamma values for the three guns (R) */ + float d_gammaG; /**< Gamma values for the three guns (G) */ + float d_gammaB; /**< Gamma values for the three guns (B) */ } TIFFDisplay; -typedef struct { /* YCbCr->RGB support */ - TIFFRGBValue* clamptab; /* range clamping table */ +/** YCbCr conversion to RGB */ +typedef struct { + TIFFRGBValue* clamptab; /** Range clamping table */ int* Cr_r_tab; int* Cb_b_tab; int32_t* Cr_g_tab; @@ -162,24 +209,26 @@ typedef struct { /* YCbCr->RGB support */ int32_t* Y_tab; } TIFFYCbCrToRGB; -typedef struct { /* CIE Lab 1976->RGB support */ - int range; /* Size of conversion table */ +/** CIE Lab 1976 conversion to RGB */ +typedef struct { + int range; /**< Size of conversion table */ #define CIELABTORGB_TABLE_RANGE 1500 float rstep, gstep, bstep; - float X0, Y0, Z0; /* Reference white point */ + float X0, Y0, Z0; /**< Reference white point */ TIFFDisplay display; - float Yr2r[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yr to r */ - float Yg2g[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yg to g */ - float Yb2b[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yb to b */ + float Yr2r[CIELABTORGB_TABLE_RANGE + 1]; /**< Conversion of Yr to r */ + float Yg2g[CIELABTORGB_TABLE_RANGE + 1]; /**< Conversion of Yg to g */ + float Yb2b[CIELABTORGB_TABLE_RANGE + 1]; /**< Conversion of Yb to b */ } TIFFCIELabToRGB; -/* - * RGBA-style image support. +/** + * RGBA-style image. */ typedef struct _TIFFRGBAImage TIFFRGBAImage; + /* * The image reading and conversion routines invoke - * ``put routines'' to copy/image/whatever tiles of + * "put routines" to copy/image/whatever tiles of * raw image data. A default set of routines are * provided to convert/copy raw image data to 8-bit * packed ABGR format rasters. Applications can supply @@ -193,40 +242,41 @@ typedef void (*tileContigRoutine) typedef void (*tileSeparateRoutine) (TIFFRGBAImage*, uint32_t*, uint32_t, uint32_t, uint32_t, uint32_t, int32_t, int32_t, unsigned char*, unsigned char*, unsigned char*, unsigned char*); + /* * RGBA-reader state. */ struct _TIFFRGBAImage { - TIFF* tif; /* image handle */ - int stoponerr; /* stop on read error */ - int isContig; /* data is packed/separate */ - int alpha; /* type of alpha data present */ - uint32_t width; /* image width */ - uint32_t height; /* image height */ - uint16_t bitspersample; /* image bits/sample */ - uint16_t samplesperpixel; /* image samples/pixel */ - uint16_t orientation; /* image orientation */ - uint16_t req_orientation; /* requested orientation */ - uint16_t photometric; /* image photometric interp */ - uint16_t* redcmap; /* colormap palette */ + TIFF* tif; /**< image handle */ + int stoponerr; /**< stop on read error */ + int isContig; /**< data is packed/separate */ + int alpha; /**< type of alpha data present */ + uint32_t width; /**< image width */ + uint32_t height; /**< image height */ + uint16_t bitspersample; /**< image bits/sample */ + uint16_t samplesperpixel; /**< image samples/pixel */ + uint16_t orientation; /**< image orientation */ + uint16_t req_orientation; /**< requested orientation */ + uint16_t photometric; /**< image photometric interp */ + uint16_t* redcmap; /**< colormap palette */ uint16_t* greencmap; uint16_t* bluecmap; - /* get image data routine */ + /** get image data routine */ int (*get)(TIFFRGBAImage*, uint32_t*, uint32_t, uint32_t); - /* put decoded strip/tile */ + /** put decoded strip/tile */ union { void (*any)(TIFFRGBAImage*); tileContigRoutine contig; tileSeparateRoutine separate; } put; - TIFFRGBValue* Map; /* sample mapping array */ - uint32_t** BWmap; /* black&white map */ - uint32_t** PALmap; /* palette image map */ - TIFFYCbCrToRGB* ycbcr; /* YCbCr conversion state */ - TIFFCIELabToRGB* cielab; /* CIE L*a*b conversion state */ + TIFFRGBValue* Map; /**< sample mapping array */ + uint32_t** BWmap; /**< black&white map */ + uint32_t** PALmap; /**< palette image map */ + TIFFYCbCrToRGB* ycbcr; /**< YCbCr conversion state */ + TIFFCIELabToRGB* cielab; /**< CIE L*a*b conversion state */ - uint8_t* UaToAa; /* Unassociated alpha to associated alpha conversion LUT */ - uint8_t* Bitdepth16To8; /* LUT for conversion from 16bit to 8bit values */ + uint8_t* UaToAa; /**< Unassociated alpha to associated alpha conversion LUT */ + uint8_t* Bitdepth16To8; /**< LUT for conversion from 16bit to 8bit values */ int row_offset; int col_offset; @@ -248,7 +298,11 @@ struct _TIFFRGBAImage { * More codecs may be registered through calls to the library * and/or the builtin implementations may be overridden. */ + +/** Codec initialisation method. */ typedef int (*TIFFInitMethod)(TIFF*, int); + +/** Codec definition */ typedef struct { char* name; uint16_t scheme; @@ -272,157 +326,1049 @@ typedef struct { #if defined(c_plusplus) || defined(__cplusplus) extern "C" { #endif -typedef void (*TIFFErrorHandler)(const char*, const char*, va_list); -typedef void (*TIFFErrorHandlerExt)(thandle_t, const char*, const char*, va_list); -typedef tmsize_t (*TIFFReadWriteProc)(thandle_t, void*, tmsize_t); -typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int); -typedef int (*TIFFCloseProc)(thandle_t); -typedef toff_t (*TIFFSizeProc)(thandle_t); -typedef int (*TIFFMapFileProc)(thandle_t, void** base, toff_t* size); -typedef void (*TIFFUnmapFileProc)(thandle_t, void* base, toff_t size); -typedef void (*TIFFExtendProc)(TIFF*); +/** + * @brief Pointer to error handling function. + * @param module Module name + * @param fmt Message format string + * @param ap Message format arguments + */ +typedef void (*TIFFErrorHandler)(const char* module, const char* fmt, va_list ap); + +/** + * @brief Pointer to extended error handling function. + * @param handle Client handle + * @param module Module name + * @param fmt Message format string + * @param ap Message format arguments + */ +typedef void (*TIFFErrorHandlerExt)(thandle_t handle, const char* module, const char* fmt, va_list ap); + +/** + * @brief Pointer to read or write function. + * @param handle Client handle + * @param buf Pointer to data buffer for reading into or writing from + * @param size Size of data buffer + * @returns Number of bytes read or written + */ +typedef tmsize_t (*TIFFReadWriteProc)(thandle_t handle, void* buf, tmsize_t size); + +/** + * @brief Pointer to seek function. + * @param handle Client handle + * @param offset Offset value + * @param whence Seek directive + * @returns New file offset + */ +typedef toff_t (*TIFFSeekProc)(thandle_t handle, toff_t offset, int whence); + +/** + * @brief Pointer to close function. + * @param handle Client handle + * @returns Status value + */ +typedef int (*TIFFCloseProc)(thandle_t handle); + +/** + * @brief Pointer to size function. + * @param handle Client handle + * @returns Client handle filesize in bytes + */ +typedef toff_t (*TIFFSizeProc)(thandle_t handle); + +/** + * @brief Pointer to memory map function. + * @param handle Client handle + * @param[out] base Pointer to the address of the mapped region + * @param[out] size Pointer to the size of the mapped region + * @returns Status value + */ +typedef int (*TIFFMapFileProc)(thandle_t handle, void** base, toff_t* size); + +/** + * @brief Pointer to memory unmap function. + * @param handle Client handle + * @param[out] base Address of the mapped region + * @param[out] size Size of the mapped region + * @returns Status value + */ +typedef void (*TIFFUnmapFileProc)(thandle_t handle, void* base, toff_t size); + +/** + * @brief Pointer to tag extender function. + * @param tif TIFF file + */ +typedef void (*TIFFExtendProc)(TIFF* tif); + +/** + * @brief Get LibTIFF release version number as a string. + * @return Version string + */ extern const char* TIFFGetVersion(void); -extern const TIFFCodec* TIFFFindCODEC(uint16_t); -extern TIFFCodec* TIFFRegisterCODEC(uint16_t, const char*, TIFFInitMethod); -extern void TIFFUnRegisterCODEC(TIFFCodec*); -extern int TIFFIsCODECConfigured(uint16_t); +/** + * @brief Find a compression codec by number. + * @details Search registered codecs, then built-in codecs. + * @param scheme Compression codec scheme number + * @return Pointer to compression codec, or NULL if the codec was not found + */ +extern const TIFFCodec* TIFFFindCODEC(uint16_t scheme); + +/** + * @brief Register a compression codec. + * @param scheme Compression codec scheme number + * @param name Compression codec name + * @param init Initialisation function + * @return Pointer to compression codec, or NULL if the codec could not be registered + */ +extern TIFFCodec* TIFFRegisterCODEC(uint16_t scheme, const char* name, TIFFInitMethod init); + +/** + * @brief Unregister a compression codec. + * @param codec Codec to unregister + */ +extern void TIFFUnRegisterCODEC(TIFFCodec* codec); + +/** + * @brief Check if codec is functional. + * @param scheme Compression codec scheme number + * @return 1 if the codec is configured and working, otherwise 0. + */ +extern int TIFFIsCODECConfigured(uint16_t scheme); + +/** + * @brief Get list of configured codecs + * @details The list includes both built-in codecs and codecs registered by the user. + * @note The caller is responsible for freeing the returned structure, which + * is a contiguous allocation containing all of the TIFFCodec records. Free + * with _TIFFfree. + * + * @return An array of TIFFCodec records (the last record is NULL) + * or NULL if function failed. + */ extern TIFFCodec* TIFFGetConfiguredCODECs(void); /* - * Auxiliary functions. + * Memory functions. */ +/** + * Allocate memory. + * @param s Size to allocate + * @return Pointer to allocated memory, or NULL if allocation failed or s was 0. + */ extern void* _TIFFmalloc(tmsize_t s); + +/** + * Allocate cleared memory. + * @param nmemb Number of members + * @param siz Size of each member + * @return Pointer to allocated memory, or NULL if allocation failed or s was 0. + */ extern void* _TIFFcalloc(tmsize_t nmemb, tmsize_t siz); + +/** + * Resize allocated memory. + * @param p Pointer to existing allocation + * @param s Size to reallocate; must be nonzero + * @return Pointer to reallocated memory, or NULL if allocation failed. + */ extern void* _TIFFrealloc(void* p, tmsize_t s); + +/** + * Set memory to value + * @param p Pointer to object to fill + * @param v Value to set + * @param c Object size + */ extern void _TIFFmemset(void* p, int v, tmsize_t c); + +/** + * Copy memory + * @param d Destination object + * @param s Source object + * @param c Object size + */ extern void _TIFFmemcpy(void* d, const void* s, tmsize_t c); + +/** + * @brief Compare memory + * @details Lexicographical comparison of memory values + * @param p1 First object + * @param p2 Second object + * @param c Object size + * @return <0 if p1 sorts before p2, >0 if p1 sorts after p2, 0 if p1 and p2 are identical + */ extern int _TIFFmemcmp(const void* p1, const void* p2, tmsize_t c); + +/** + * Free allocated memory + * @param p Pointer to allocated memory + */ extern void _TIFFfree(void* p); -/* -** Stuff, related to tag handling and creating custom tags. -*/ -extern int TIFFGetTagListCount( TIFF * ); -extern uint32_t TIFFGetTagListEntry(TIFF *, int tag_index ); - -#define TIFF_ANY TIFF_NOTYPE /* for field descriptor searching */ -#define TIFF_VARIABLE -1 /* marker for variable length tags */ -#define TIFF_SPP -2 /* marker for SamplesPerPixel tags */ -#define TIFF_VARIABLE2 -3 /* marker for uint32_t var-length tags */ +/** + * @brief Get number of "custom" tags in the current directory. + * @param tif TIFF file + * @return Number of tags + */ +extern int TIFFGetTagListCount( TIFF * tif); + +/** + * @brief Get the TIFF tag number for a "custom" tag by index + * @param tif TIFF file + * @param tag_index "custom" tag index number + * @return TIFF tag number, or -1 if the index was invalid + */ +extern uint32_t TIFFGetTagListEntry(TIFF * tif, int tag_index ); +/** TIFF tag length is determined by field descriptor searching */ +#define TIFF_ANY TIFF_NOTYPE +/* TIFF tag length is variable length, stored as uint16_t */ +#define TIFF_VARIABLE -1 +/* TIFF tag length is variable length, defined by SamplesPerPixel tag */ +#define TIFF_SPP -2 +/* TIFF tag length is variable length, stored as uint32_t */ +#define TIFF_VARIABLE2 -3 + +/** TIFFField custom bit */ #define FIELD_CUSTOM 65 +/** + * @brief TIFF Field structure. + * @details This private structure defines the content of a TIFF field, + * including the tag number, tag name, field type, read and write counts. + */ typedef struct _TIFFField TIFFField; + +/** + * @brief Array of TIFF Field structures. + * @details This private structure defines a collection of TIFF fields. + */ typedef struct _TIFFFieldArray TIFFFieldArray; -extern const TIFFField* TIFFFindField(TIFF *, uint32_t, TIFFDataType); -extern const TIFFField* TIFFFieldWithTag(TIFF*, uint32_t); -extern const TIFFField* TIFFFieldWithName(TIFF*, const char *); +/** + * @brief Find field by tag number and datatype + * @param tif TIFF file + * @param tag Field tag number + * @param dt Field data type + * @return Field, or NULL if not found + */ +extern const TIFFField* TIFFFindField(TIFF *tif, uint32_t tag, TIFFDataType dt); + +/** + * @brief Find field by tag number + * @details Will find any datatype and is equivalent to + * TIFFFindField with TAG_ANY as the datatype. + * @param tif TIFF file + * @return Field, or NULL if not found + */ +extern const TIFFField* TIFFFieldWithTag(TIFF* tif, uint32_t tag); + +/** + * @brief Find field by tag name + * @details Will find any datatype and is equivalent to + * _TIFFFindFieldByName with TAG_ANY as the datatype. + * @param tif TIFF file + * @param field_name Field name to find + * @return Field, or NULL if not found + */ +extern const TIFFField* TIFFFieldWithName(TIFF* tif, const char * field_name); + +/** + * @brief Get field tag number + * @param fip Field information pointer + * @return Field tag number + */ +extern uint32_t TIFFFieldTag(const TIFFField* fip); + +/** + * @brief Get field tag name + * @param fip Field information pointer + * @return Field tag name + */ +extern const char* TIFFFieldName(const TIFFField* fip); + +/** + * @brief Get field data type + * @param fip Field information pointer + * @return Field data type + */ +extern TIFFDataType TIFFFieldDataType(const TIFFField* fip); + +/** + * @brief Get field pass count + * @param fip Field information pointer + * @return Field pass count + */ +extern int TIFFFieldPassCount(const TIFFField* fip); + +/** + * @brief Get field read count + * @param fip Field information pointer + * @return Field read count + */ +extern int TIFFFieldReadCount(const TIFFField* fip); + +/** + * @brief Get field write count + * @param fip Field information pointer + * @return Field write count + */ +extern int TIFFFieldWriteCount(const TIFFField* fip); + +/** + * @brief Get field data type size + * @details Internal storage size of field data type in bytes. + * @param fip Field information pointer + * @return Field data type size + */ + +extern int TIFFFieldSetGetSize(const TIFFField* fip); -extern uint32_t TIFFFieldTag(const TIFFField*); -extern const char* TIFFFieldName(const TIFFField*); -extern TIFFDataType TIFFFieldDataType(const TIFFField*); -extern int TIFFFieldPassCount(const TIFFField*); -extern int TIFFFieldReadCount(const TIFFField*); -extern int TIFFFieldWriteCount(const TIFFField*); -extern int TIFFFieldSetGetSize(const TIFFField*); /* returns internal storage size of TIFFSetGetFieldType in bytes. */ -extern int TIFFFieldSetGetCountSize(const TIFFField*); /* returns size of count parameter 0=none, 2=uint16_t, 4=uint32_t */ -extern int TIFFFieldIsAnonymous(const TIFFField *); +/** + * @brief Get field data type count size + * @details Size of count parameter 0=none, 2=uint16_t, 4=uint32_t + * @param fip Field information pointer + * @return Field data type count size + */ +extern int TIFFFieldSetGetCountSize(const TIFFField* fip); + +/** + * @brief Get field anonymous status + * @param fip Field information pointer + * @return Field anonymous status + */ +extern int TIFFFieldIsAnonymous(const TIFFField * fip); + +/** + * @brief Pointer to value setting function. + * @param tif TIFF file + * @param tag Field tag number + * @param ap Value-setting arguments + */ +typedef int (*TIFFVSetMethod)(TIFF* tif, uint32_t tag, va_list ap); + +/** + * @brief Pointer to value getting function. + * @param tif TIFF file + * @param tag Field tag number + * @param ap Value-getting arguments + */ +typedef int (*TIFFVGetMethod)(TIFF* tif, uint32_t tag, va_list ap); -typedef int (*TIFFVSetMethod)(TIFF*, uint32_t, va_list); -typedef int (*TIFFVGetMethod)(TIFF*, uint32_t, va_list); -typedef void (*TIFFPrintMethod)(TIFF*, FILE*, long); +/** + * @brief Pointer to directory printing function. + * @param tif TIFF file + * @param file File handle to send formatted output to + * @param flags Printing flags; @see TIFFPrintDirectory for details + */ +typedef void (*TIFFPrintMethod)(TIFF* tif, FILE* fd, long flags); +/** + * @brief TIFF tag functions. + */ typedef struct { - TIFFVSetMethod vsetfield; /* tag set routine */ - TIFFVGetMethod vgetfield; /* tag get routine */ - TIFFPrintMethod printdir; /* directory print routine */ + TIFFVSetMethod vsetfield; /**< Tag set routine */ + TIFFVGetMethod vgetfield; /**< Tag get routine */ + TIFFPrintMethod printdir; /**< Directory print routine */ } TIFFTagMethods; -extern TIFFTagMethods *TIFFAccessTagMethods(TIFF *); -extern void *TIFFGetClientInfo(TIFF *, const char *); -extern void TIFFSetClientInfo(TIFF *, void *, const char *); +/** + * @brief Get tag methods for TIFF file + * @note The tag methods are not overridable by the user, + * so there is no corresponding function to modify the + * methods. + * @param tif TIFF file + * @return Pointer to the tag methods + */ +extern TIFFTagMethods *TIFFAccessTagMethods(TIFF *tif); + +/** + * @brief Get client information + * @details Retrieve a previously-stored item by name. + * @param tif TIFF file + * @param name Client information name + * @return Pointer to client data, or NULL if name not found + */ +extern void *TIFFGetClientInfo(TIFF *tif, const char *name); + +/** + * @brief Set client information + * @details The name must be unique; if data has already been + * stored with this name, it will be updated to use the new + * data value. + * @param tif TIFF file + * @param name Client information name + * @param data Client data + */ +extern void TIFFSetClientInfo(TIFF *tif, void *name, const char *data); +/** + * @brief Free the TIFF structure + * @details The given structure will be completely freed, so ensure + * the opened file handle and pointer to the close procedure are + * saved in external variables before callingTIFFCleanup(), if you + * will need this information to properly close the file. + * + * @param tif TIFF file + */ extern void TIFFCleanup(TIFF* tif); + +/** + * @brief Close a previously opened TIFF file. + * @details Close a file that was previously opened with TIFFOpen(). + * Any buffered data are flushed to the file, including the contents of + * the current directory (if modified), and all resources are reclaimed. + * + * @param tif TIFF file + */ extern void TIFFClose(TIFF* tif); + +/** + * @brief Flush pending changes to TIFF file. + * @details This function will flush buffered data, update the strip + * or tile arrays and rewrite the current directory. + * @param tif TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFFlush(TIFF* tif); + +/** + * @brief Flush pending image data writes to TIFF file. + * @details Buffered data will be flushed to the TIFF file. + * @note Frank Warmerdam'2000: I modified this to return 1 if + * TIFF_BEENWRITING is not set, so that TIFFFlush() will proceed to + * write out the directory. The documentation says returning 1 is an + * error indicator, but not having been writing isn't exactly a an + * error. Hopefully this doesn't cause problems for other people. + * + * @param tif TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFFlushData(TIFF* tif); + +/** + * @brief Get field value + * @details Get the value of a field in the internal directory structure. + * The arguments required are tag-specific and may also depend upon + * other field values, such as SamplesPerPixel. + * @param tif TIFF file + * @param tag Field tag number + * @param ... Get arguments + * @return 0 on error, 1 on success + */ extern int TIFFGetField(TIFF* tif, uint32_t tag, ...); + +/** + * @brief Get field value (variable arguments) + * @details Get the value of a field in the internal directory structure. + * The arguments required are tag-specific and may also depend upon + * other field values, such as SamplesPerPixel. + * Like TIFFGetField, but taking a varargs + * parameter list. This routine is useful + * for building higher-level interfaces on + * top of the library. + * @param tif TIFF file + * @param tag Field tag number + * @param va_list Get variable arguments + * @return 0 on error, 1 on success + */ extern int TIFFVGetField(TIFF* tif, uint32_t tag, va_list ap); + +/** + * @brief Get field value with default if unset + * @details Get the value of a field in the internal directory structure. + * The arguments required are tag-specific and may also depend upon + * other field values, such as SamplesPerPixel. If unset, the default + * value for the field will be returned. + * @param tif TIFF file + * @param tag Field tag number + * @param ... Get arguments + * @return 0 on error, 1 on success + */ extern int TIFFGetFieldDefaulted(TIFF* tif, uint32_t tag, ...); + +/** + * @brief Get field value with default if unset (variable arguments) + * @details Get the value of a field in the internal directory structure. + * The arguments required are tag-specific and may also depend upon + * other field values, such as SamplesPerPixel. If unset, the default + * value for the field will be returned. + * Like TIFFGetField, but taking a varargs + * parameter list. This routine is useful + * for building higher-level interfaces on + * top of the library. + * @param tif TIFF file + * @param tag Field tag number + * @param va_list Get variable arguments + * @return 0 on error, 1 on success + */ extern int TIFFVGetFieldDefaulted(TIFF* tif, uint32_t tag, va_list ap); + +/** + * @brief Read the next TIFF directory + * @details Read the next TIFF directory from a file and convert it to + * the internal format. Directories are read sequentially. + * @param tif TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFReadDirectory(TIFF* tif); + +/** + * @brief Read TIFF directory (with custom fields) + * @details Read custom TIFF directory from an arbitrary offset + * and convert it into the internal format using custom fields. + * Similar to TIFFReadDirectory(). + * @param tif TIFF file + * @param diroff Offset into TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFReadCustomDirectory(TIFF* tif, toff_t diroff, const TIFFFieldArray* infoarray); + +/** + * @brief Read EXIF directory + * @details Read EXIF directory from an arbitrary offset + * and convert it into the internal format. + * @note EXIF is an important special case of a custom directory. + * @param tif TIFF file + * @param diroff Offset into TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFReadEXIFDirectory(TIFF* tif, toff_t diroff); + +/** + * @brief Read EXIF-GPS directory + * @details Read EXIF-GPS directory from an arbitrary offset + * and convert it into the internal format. + * @note EXIF-GPS is an important special case of a custom directory. + * @param tif TIFF file + * @param diroff Offset into TIFF file + * @return 0 on error, 1 on success + */ extern int TIFFReadGPSDirectory(TIFF* tif, toff_t diroff); + +/** + * @brief Get size of scanline (unsigned 64-bit) + * @details Get the number of bytes to read/write in a call to + * one of the scanline-oriented I/O routines. Note that + * this number may be 1/SamplesPerPixel if the data is + * stored as separate planes. + * The ScanlineSize in case of YCbCrSubsampling is defined as the + * strip size divided by the strip height, i.e. the size of a pack + * of vertical subsampling lines divided by vertical subsampling. + * It should thus make sense when multiplied by a multiple of + * vertical subsampling. + * @param tif TIFF file + * @return Scanline size in bytes, or 0 on error + */ extern uint64_t TIFFScanlineSize64(TIFF* tif); + +/** + * @brief Get size of scanline (signed integer) + * @details Get the number of bytes to read/write in a call to + * one of the scanline-oriented I/O routines. Note that + * this number may be 1/SamplesPerPixel if the data is + * stored as separate planes. + * The ScanlineSize in case of YCbCrSubsampling is defined as the + * strip size divided by the strip height, i.e. the size of a pack + * of vertical subsampling lines divided by vertical subsampling. + * It should thus make sense when multiplied by a multiple of + * vertical subsampling. + * @param tif TIFF file + * @return Scanline size in bytes, or 0 on error + */ extern tmsize_t TIFFScanlineSize(TIFF* tif); + +/** + * @brief Get size of raster scanline (unsigned 64-bit) + * @details Return the number of bytes required to store a complete + * decoded and packed raster scanline (as opposed to the + * I/O size returned by TIFFScanlineSize which may be less + * if data is store as separate planes). + * @param tif TIFF file + * @return Raster scanline size in bytes, or 0 on error + */ extern uint64_t TIFFRasterScanlineSize64(TIFF* tif); + +/** + * @brief Get size of raster scanline (signed integer) + * @details Return the number of bytes required to store a complete + * decoded and packed raster scanline (as opposed to the + * I/O size returned by TIFFScanlineSize which may be less + * if data is store as separate planes). + * @param tif TIFF file + * @return Raster scanline size in bytes, or 0 on error + */ extern tmsize_t TIFFRasterScanlineSize(TIFF* tif); + + +/** + * @brief Get size of a strip (unsigned 64-bit) + * @details Get the number of bytes in a row-aligned strip. + * @note If RowsPerStrip is larger than the + * recorded ImageLength, then the strip size is + * truncated to reflect the actual space required + * to hold the strip. + * @param tif TIFF file + * @return Strip size in bytes, or 0 on error + */ extern uint64_t TIFFStripSize64(TIFF* tif); + +/** + * @brief Get size of a strip (signed integer) + * @details Get the number of bytes in a row-aligned strip. + * @note If RowsPerStrip is larger than the + * recorded ImageLength, then the strip size is + * truncated to reflect the actual space required + * to hold the strip. + * @param tif TIFF file + * @return Strip size in bytes, or 0 on error + */ extern tmsize_t TIFFStripSize(TIFF* tif); + +/** + * @brief Get "raw" size of a strip (unsigned 64-bit) + * @details Get the number of bytes in a row-aligned strip. + * @note "Raw" means the size of a strip which has not been + * decoded. + * @param tif TIFF file + * @return Strip size in bytes, or 0 on error + */ extern uint64_t TIFFRawStripSize64(TIFF* tif, uint32_t strip); + +/** + * @brief Get "raw" size of a strip (signed integer) + * @details Get the number of bytes in a row-aligned strip. + * @note "Raw" means the size of a strip which has not been + * decoded. + * @param tif TIFF file + * @return Strip size in bytes, or 0 on error + */ extern tmsize_t TIFFRawStripSize(TIFF* tif, uint32_t strip); + +/** + * @brief Get size of a strip with variable row count (unsigned 64-bit) + * @details Get the number of bytes in a row-aligned strip with the + * specified row count. + * @note If RowsPerStrip is larger than the + * recorded ImageLength, then the strip size is + * truncated to reflect the actual space required + * to hold the strip. + * @param tif TIFF file + * @param nrows Row count + * @return Strip size in bytes, or 0 on error + */ extern uint64_t TIFFVStripSize64(TIFF* tif, uint32_t nrows); + +/** + * @brief Get size of a strip with variable row count (signed integer) + * @details Get the number of bytes in a row-aligned strip with the + * specified row count. + * @note If RowsPerStrip is larger than the + * recorded ImageLength, then the strip size is + * truncated to reflect the actual space required + * to hold the strip. + * @param tif TIFF file + * @param nrows Row count + * @return Strip size in bytes, or 0 on error + */ extern tmsize_t TIFFVStripSize(TIFF* tif, uint32_t nrows); + +/** + * @brief Get size of each row of a tile (unsigned 64-bit) + * @details Get the number of bytes in each row of a tile. + * @param tif TIFF file + * @return Row size in bytes, or 0 on error + */ extern uint64_t TIFFTileRowSize64(TIFF* tif); + +/** + * @brief Get size of each row of a tile (signed integer) + * @details Get the number of bytes in each row of a tile. + * @param tif TIFF file + * @return Row size in bytes, or 0 on error + */ extern tmsize_t TIFFTileRowSize(TIFF* tif); + +/** + * @brief Get size of a tile (unsigned 64-bit) + * @details Get the number of bytes in a row-aligned tile. + * @param tif TIFF file + * @return Row size in bytes, or 0 on error + */ extern uint64_t TIFFTileSize64(TIFF* tif); + +/** + * @brief Get size of a tile (signed integer) + * @details Get the number of bytes in a row-aligned tile. + * @param tif TIFF file + * @return Row size in bytes, or 0 on error + */ extern tmsize_t TIFFTileSize(TIFF* tif); + +/** + * @brief Get size of a tile with variable row count (unsigned 64-bit) + * @details Get the number of bytes in a row-aligned tile + * with the specified row count. + * @param tif TIFF file + * @param nrows Row count + * @return Row size in bytes, or 0 on error + */ extern uint64_t TIFFVTileSize64(TIFF* tif, uint32_t nrows); + +/** + * @brief Get size of a tile with variable row count (signed integer) + * @details Get the number of bytes in a row-aligned tile + * with the specified row count. + * @param tif TIFF file + * @param nrows Row count + * @return Row size in bytes, or 0 on error + */ extern tmsize_t TIFFVTileSize(TIFF* tif, uint32_t nrows); + +/** + * @brief Get default strip size for current directory + * @details Get the default strip size based upon the image + * characteristics and a requested value. If the + * request is <1, choose a strip size according + * to certain heuristics. + * @param tif TIFF file + * @param request Requested size. Set to <1 to compute default size. + * @return Computed strip size if request value was <1, or else request value. + */ extern uint32_t TIFFDefaultStripSize(TIFF* tif, uint32_t request); -extern void TIFFDefaultTileSize(TIFF*, uint32_t*, uint32_t*); -extern int TIFFFileno(TIFF*); -extern int TIFFSetFileno(TIFF*, int); -extern thandle_t TIFFClientdata(TIFF*); -extern thandle_t TIFFSetClientdata(TIFF*, thandle_t); -extern int TIFFGetMode(TIFF*); -extern int TIFFSetMode(TIFF*, int); -extern int TIFFIsTiled(TIFF*); -extern int TIFFIsByteSwapped(TIFF*); -extern int TIFFIsUpSampled(TIFF*); -extern int TIFFIsMSB2LSB(TIFF*); -extern int TIFFIsBigEndian(TIFF*); -extern int TIFFIsBigTIFF(TIFF*); -extern TIFFReadWriteProc TIFFGetReadProc(TIFF*); -extern TIFFReadWriteProc TIFFGetWriteProc(TIFF*); -extern TIFFSeekProc TIFFGetSeekProc(TIFF*); -extern TIFFCloseProc TIFFGetCloseProc(TIFF*); -extern TIFFSizeProc TIFFGetSizeProc(TIFF*); -extern TIFFMapFileProc TIFFGetMapFileProc(TIFF*); -extern TIFFUnmapFileProc TIFFGetUnmapFileProc(TIFF*); -extern uint32_t TIFFCurrentRow(TIFF*); -extern uint16_t TIFFCurrentDirectory(TIFF*); -extern uint16_t TIFFNumberOfDirectories(TIFF*); -extern uint64_t TIFFCurrentDirOffset(TIFF*); -extern uint32_t TIFFCurrentStrip(TIFF*); + +/** + * @brief Get default tile size for current directory + * @details Get the default tile size based on the image + * characteristics. If the tw or th requests are <1, + * choose a size according to certain heuristics. + * @param tif TIFF file + * @param[inout] tw Tile width; must be desired width or <1 to compute + * @param[inout] th Tile height; must be desired width or <1 to compute + */ +extern void TIFFDefaultTileSize(TIFF* tif, uint32_t* tw, uint32_t* th); + +/** + * @brief Get file descriptor for open TIFF file. + * @param tif TIFF file + * @return file descriptor number + */ +extern int TIFFFileno(TIFF* tif); + +/** + * @brief Change file descriptor for open TIFF file. + * @param tif TIFF file + * @param fd File descriptor number + * @return Previous file descriptor value + */ +extern int TIFFSetFileno(TIFF* tif, int fd); + +/** + * @brief Get client data for open TIFF file. + * @param tif TIFF file + * @return Client data + */ +extern thandle_t TIFFClientdata(TIFF* tif); + +/** + * @brief Set client data for open TIFF file. + * @param tif TIFF file + * @param newvalue New client data value + * @return Old client data + */ +extern thandle_t TIFFSetClientdata(TIFF* tif, thandle_t newvalue); + +/** + * @brief Get read/write mode for open TIFF file. + * @param tif TIFF file + * @return Read/write mode + */ +extern int TIFFGetMode(TIFF* tif); + +/** + * @brief Set read/write mode for open TIFF file. + * @param tif TIFF file + * @param mode New read/write mode + * @return Old read/write mode + */ +extern int TIFFSetMode(TIFF* tif, int mode); + +/** + * @brief Check if current TIFF directory is tiled. + * @param tif TIFF file. + * @return 0 if strips; nonzero if tiles + */ +extern int TIFFIsTiled(TIFF* tif); + +/** + * @brief Check if current TIFF file is byte-swapped. + * @param tif TIFF file. + * @return 0 not byte-swapped; nonzero if byte-swapped + */ +extern int TIFFIsByteSwapped(TIFF* tif); + +/** + * @brief Check if current TIFF directory is up-sampled. + * @param tif TIFF file. + * @return 0 if not upsampled; nonzero if up-sampled. + */ +extern int TIFFIsUpSampled(TIFF* tif); + +/** + * @brief Check if current TIFF directory is MSB-to-LSB bit order. + * @param tif TIFF file. + * @return 0 if LSB-to-MSB; nonzero if MSB-to-LSB. + */ +extern int TIFFIsMSB2LSB(TIFF* tif); + +/** + * @brief Check if current TIFF file is big-endian. + * @param tif TIFF file. + * @return 0 if little-endian; nonzero if big-endian. + */ +extern int TIFFIsBigEndian(TIFF* tif); + +/** + * @brief Check if current TIFF file is a BigTIFF format TIFF. + * @param tif TIFF file. + * @return 0 if standard TIFF; nonzero if BigTIFF.. + */ +extern int TIFFIsBigTIFF(TIFF* tif); + +/** + * Get file read method for TIFF file. + * @param tif TIFF file. + * @return File read method + */ +extern TIFFReadWriteProc TIFFGetReadProc(TIFF* tif); + +/** + * Get file write method for TIFF file. + * @param tif TIFF file. + * @return File write method + */ +extern TIFFReadWriteProc TIFFGetWriteProc(TIFF* tif); + +/** + * Get file seek method for TIFF file. + * @param tif TIFF file. + * @return File seek method + */ +extern TIFFSeekProc TIFFGetSeekProc(TIFF* tif); + +/** + * Get file close method for TIFF file. + * @param tif TIFF file. + * @return File close method + */ +extern TIFFCloseProc TIFFGetCloseProc(TIFF* tif); + +/** + * Get file size method for TIFF file. + * @param tif TIFF file. + * @return File size method + */ +extern TIFFSizeProc TIFFGetSizeProc(TIFF* tif); + +/** + * Get file memory map method for TIFF file. + * @param tif TIFF file. + * @return File memory map method + */ +extern TIFFMapFileProc TIFFGetMapFileProc(TIFF* tif); + +/** + * Get file memory unmap method for TIFF file. + * @param tif TIFF file. + * @return File memory unmap method + */ +extern TIFFUnmapFileProc TIFFGetUnmapFileProc(TIFF* tif); + +/** + * Get current row index being written + * @param tif TIFF file. + * @return Current row index. + */ +extern uint32_t TIFFCurrentRow(TIFF* tif); + +/** + * Get current directory index + * @param tif TIFF file. + * @return Current directory index + */ +extern uint16_t TIFFCurrentDirectory(TIFF* tif); + +/** + * Get the total number of directories in a file + * @param tif TIFF file. + * @return Directory count + */ +extern uint16_t TIFFNumberOfDirectories(TIFF* tif); + +/** + * Get file offset of the current directory. + * @param tif TIFF file. + * @return File offset + */ +extern uint64_t TIFFCurrentDirOffset(TIFF* tif); + +/** + * Get current strip index. + * @param tif + * @return Strip index + */ +extern uint32_t TIFFCurrentStrip(TIFF* tif); + +/** + * Get current tile index. + * @param tif + * @return tile index + */ extern uint32_t TIFFCurrentTile(TIFF* tif); + +/** + * @brief Set up raw read buffer. + * @details Set up the raw data buffer in preparation for + * reading a strip of raw data. If the buffer + * is specified as NULL, then a buffer of appropriate + * size is allocated by the library. Otherwise, + * the client must guarantee that the buffer is + * large enough to hold any individual strip of + * raw data. + * @param tif TIFF file + * @param bp Pointer to buffer; NULL to allocate automatically + * @param size Size of buffer; only used if bp is not NULL + * @return 0 on error, 1 on success + */ extern int TIFFReadBufferSetup(TIFF* tif, void* bp, tmsize_t size); -extern int TIFFWriteBufferSetup(TIFF* tif, void* bp, tmsize_t size); -extern int TIFFSetupStrips(TIFF *); -extern int TIFFWriteCheck(TIFF*, int, const char *); -extern void TIFFFreeDirectory(TIFF*); -extern int TIFFCreateDirectory(TIFF*); -extern int TIFFCreateCustomDirectory(TIFF*,const TIFFFieldArray*); -extern int TIFFCreateEXIFDirectory(TIFF*); -extern int TIFFCreateGPSDirectory(TIFF*); -extern int TIFFLastDirectory(TIFF*); -extern int TIFFSetDirectory(TIFF*, uint16_t); -extern int TIFFSetSubDirectory(TIFF*, uint64_t); -extern int TIFFUnlinkDirectory(TIFF*, uint16_t); -extern int TIFFSetField(TIFF*, uint32_t, ...); -extern int TIFFVSetField(TIFF*, uint32_t, va_list); -extern int TIFFUnsetField(TIFF*, uint32_t); -extern int TIFFWriteDirectory(TIFF *); -extern int TIFFWriteCustomDirectory(TIFF *, uint64_t *); -extern int TIFFCheckpointDirectory(TIFF *); -extern int TIFFRewriteDirectory(TIFF *); -extern int TIFFDeferStrileArrayWriting(TIFF *); -extern int TIFFForceStrileArrayWriting(TIFF* ); + +/** + * @brief Set up raw write buffer. + * @details Set up the raw data buffer in preparation for + * writing a strip of raw data. If the size is specified as -1, + * then a buffer of appropriate size is allocated by the library + * (bp is ignored). + * If bp is NULL, a buffer of the specified size will be allocated. + * Otherwise, bp and size will be used as specified; + * the client must guarantee that the buffer is + * large enough to hold any individual strip of + * raw data. + * @param tif TIFF file + * @param bp Pointer to buffer; NULL to allocate automatically + * @param size Size of buffer; only used if bp is not -1 and not NULL + * @return 0 on error, 1 on success + */ +extern int TIFFWriteBufferSetup(TIFF* tif, void* bp, tmsize_t size); + +/** + * @brief Set up directory for strip or tile reading and writing + * @details Compute number of strips or tiles, and allocate space + * for storing the per-strip or per-tile offsets and byte counts. + * @param tif TIFF file + * @return 0 on error, 1 on success + */ +extern int TIFFSetupStrips(TIFF* tif); + +/** + * @brief Check if set up properly for writing + * @details Verify file is writable and that the directory + * information is setup properly. In doing the latter + * we also "freeze" the state of the directory so + * that important information is not changed. + * @param tif TIFF file + * @param tiles 1 to check if writing tiles, 0 to check if writing strips + * @param module Module name (for error reporting) + * @return 0 on error, 1 on success + */ +extern int TIFFWriteCheck(TIFF* tif, int tiles, const char * module); + +/** + * @brief Release storage associated with a directory. + * @param tif TIFF file + */ +extern void TIFFFreeDirectory(TIFF* tif); + +/** + * @brief Create new directory + * @details Set up for a new directory. + * The newly created directory will not exist in the file until + * one of TIFFWriteDirectory(), TIFFFlush() or TIFFClose() is called. + * + * @todo Should we automatically call + * TIFFWriteDirectory() if the current one is dirty? Or fail? + * + * @param tif TIFF file + * @return 0 on error, 1 on success + */ +extern int TIFFCreateDirectory(TIFF* tif); + +/** + * @brief Create new custom directory + * @details In addition to the default setup performed by + * TIFFCreateDirectory, additionally set up the custom fields + * specified in the provided field array. + * @param tif TIFF file + * @param infoarray Field array + * @return 0 on error, 1 on success + */ +extern int TIFFCreateCustomDirectory(TIFF* tif,const TIFFFieldArray* infoarray); + +/** + * Create a new EXIF directory + * @param tif TIFF file + * @return 0 on error, 1 on success + */ +extern int TIFFCreateEXIFDirectory(TIFF* tif); + +/** + * Create a new EXIF-GPS directory + * @param tif TIFF file + * @return 0 on error, 1 on success + */ +extern int TIFFCreateGPSDirectory(TIFF* tif); + +/** + * @brief Check if current directory is the last directory + * @param tif TIFF file + * @return 1 if the last directory, otherwise 0 + */ +extern int TIFFLastDirectory(TIFF* tif); + +/** + * @brief Set current directory by directory index + * @details Set current directory to be the n-th directory + * in the file. + * @note Directories are numbered starting at 0. + * @param tif TIFF file + * @param dirn Directory index + * @return 0 on error, 1 on success + */ +extern int TIFFSetDirectory(TIFF* tif, uint16_t dirn); + +/** + * @brief Set current directory by directory offset in file + * @details Set the current directory to be the directory + * located at the specified file offset. This interface + * is used mainly to access directories linked with + * the SubIFD tag (e.g. thumbnail images). + * @param tif TIFF file + * @param diroff Directory offset + * @return 0 on error, 1 on success + */ +extern int TIFFSetSubDirectory(TIFF* tif, uint64_t diroff); + +extern int TIFFUnlinkDirectory(TIFF* tif, uint16_t); +extern int TIFFSetField(TIFF* tif, uint32_t, ...); +extern int TIFFVSetField(TIFF* tif, uint32_t, va_list); +extern int TIFFUnsetField(TIFF* tif, uint32_t); +extern int TIFFWriteDirectory(TIFF * tif); +extern int TIFFWriteCustomDirectory(TIFF * tif, uint64_t *); +extern int TIFFCheckpointDirectory(TIFF * tif); +extern int TIFFRewriteDirectory(TIFF * tif); +extern int TIFFDeferStrileArrayWriting(TIFF* tif); +extern int TIFFForceStrileArrayWriting(TIFF* tif); #if defined(c_plusplus) || defined(__cplusplus) extern void TIFFPrintDirectory(TIFF*, FILE*, long = 0); @@ -447,7 +1393,15 @@ extern int TIFFRGBAImageOK(TIFF*, char [1024]); extern int TIFFRGBAImageBegin(TIFFRGBAImage*, TIFF*, int, char [1024]); extern int TIFFRGBAImageGet(TIFFRGBAImage*, uint32_t*, uint32_t, uint32_t); extern void TIFFRGBAImageEnd(TIFFRGBAImage*); -extern TIFF* TIFFOpen(const char*, const char*); + +/** + * @brief Open a TIFF file for reading or writing. + * @param name The filename of the file to open + * @param mode THe open mode of the file + * @return The opened TIFF file, or NULL if opening failed + */ +extern TIFF* TIFFOpen(const char* name, const char* mode); + # ifdef __WIN32__ extern TIFF* TIFFOpenW(const wchar_t*, const char*); # endif /* __WIN32__ */ @@ -549,18 +1503,34 @@ extern void TIFFYCbCrtoRGB(TIFFYCbCrToRGB *, uint32_t, int32_t, int32_t, * Don't use this stuff in your applications, it may be removed in the future * libtiff versions. ****************************************************************************/ + +/** + * @brief TIFF field description (obsolete) + * @see TIFField + * @deprecated Use TIFFField and associated functions instead. + */ typedef struct { - ttag_t field_tag; /* field's tag */ - short field_readcount; /* read count/TIFF_VARIABLE/TIFF_SPP */ - short field_writecount; /* write count/TIFF_VARIABLE */ - TIFFDataType field_type; /* type of associated data */ - unsigned short field_bit; /* bit in fieldsset bit vector */ - unsigned char field_oktochange; /* if true, can change while writing */ - unsigned char field_passcount; /* if true, pass dir count on set */ - char *field_name; /* ASCII name */ + ttag_t field_tag; /**< field's tag */ + short field_readcount; /**< read count/TIFF_VARIABLE/TIFF_SPP */ + short field_writecount; /**< write count/TIFF_VARIABLE */ + TIFFDataType field_type; /**< type of associated data */ + unsigned short field_bit; /**< bit in field's set bit vector */ + unsigned char field_oktochange; /**< if true, can change while writing */ + unsigned char field_passcount; /**< if true, pass dir count on set */ + char *field_name; /**< ASCII name */ } TIFFFieldInfo; -extern int TIFFMergeFieldInfo(TIFF*, const TIFFFieldInfo[], uint32_t); +/** + * Merge custom TIFF field definitions for use with current TIFF file + * @see TIFField + * @deprecated Use TIFFField and associated functions instead. + * @todo Add example and references for replacement functionality. + * @param tif TIFF file + * @param info Array of field definitions + * @param n Number of field definitions in array + * @return 0 on success, -1 on failure + */ +extern int TIFFMergeFieldInfo(TIFF* tif, const TIFFFieldInfo info[], uint32_t n); #if defined(c_plusplus) || defined(__cplusplus) } diff --git a/libtiff/tiffiop.h b/libtiff/tiffiop.h index b4429f45..919c9027 100644 --- a/libtiff/tiffiop.h +++ b/libtiff/tiffiop.h @@ -62,10 +62,15 @@ #define FALSE 0 #endif +/** + * @brief Link to client-provided data, referenced by name + * @note The referenced data is not owned by LibTIFF; + * the client has responsibility for managing its lifetime. + */ typedef struct client_info { - struct client_info *next; - void *data; - char *name; + struct client_info *next; /**< Pointer to the next member */ + void *data; /**< Pointer to client data */ + char *name; /**< Name of client data value */ } TIFFClientInfoLink; /* |