362 lines
10 KiB
HTML
362 lines
10 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||
|
|
<HTML><HEAD><TITLE>Manpage of TIFFOpen</TITLE>
|
||
|
|
</HEAD><BODY BGCOLOR=WHITE><FONT FACE="helvetica, sans, arial">
|
||
|
|
<H1>TIFFOpen</H1>
|
||
|
|
Section: Misc. Reference Manual Pages (3T)<BR>Updated: January 9, 1996<BR><A HREF="#index">Index</A>
|
||
|
|
<BR><A HREF="index.html">Return to Main Contents</A>
|
||
|
|
<HR>
|
||
|
|
|
||
|
|
<A NAME="lbAB"> </A>
|
||
|
|
<H2>NAME</H2>
|
||
|
|
|
||
|
|
TIFFOpen, TIFFFdOpen, TIFFClientOpen - open a
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
file for reading or writing
|
||
|
|
<A NAME="lbAC"> </A>
|
||
|
|
<H2>SYNOPSIS</H2>
|
||
|
|
|
||
|
|
<PRE>
|
||
|
|
<B>#include <<A HREF="file:/usr/include/tiffio.h">tiffio.h</A>></B>
|
||
|
|
<B>TIFF* TIFFOpen(const char* filename, const char* mode)</B>
|
||
|
|
|
||
|
|
<B>TIFF* TIFFFdOpen(const int fd, const char* filename, const char* mode)</B>
|
||
|
|
|
||
|
|
<B>typedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t);</B>
|
||
|
|
<B>typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);</B>
|
||
|
|
<B>typedef int (*TIFFCloseProc)(thandle_t);</B>
|
||
|
|
<B>typedef toff_t (*TIFFSizeProc)(thandle_t);</B>
|
||
|
|
<B>typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);</B>
|
||
|
|
<B>typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);</B>
|
||
|
|
|
||
|
|
<B>TIFF* TIFFClientOpen(const char* filename, const char* mode, thandle_t clientdata,</B>
|
||
|
|
<B> TIFFReadWriteProc readproc, TIFFReadWriteProc writeproc, TIFFSeekProc seekproc,</B>
|
||
|
|
<B> TIFFCloseProc closeproc, TIFFSizeProc sizeproc, TIFFMapFileProc mapproc,</B>
|
||
|
|
<B> TIFFUnmapFileProc unmapproc)</B>
|
||
|
|
</PRE>
|
||
|
|
|
||
|
|
<A NAME="lbAD"> </A>
|
||
|
|
<H2>DESCRIPTION</H2>
|
||
|
|
|
||
|
|
<I>TIFFOpen</I>
|
||
|
|
|
||
|
|
opens a
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
file whose name is
|
||
|
|
<I>filename</I>
|
||
|
|
|
||
|
|
and returns a handle to be used in subsequent calls to routines in
|
||
|
|
<I>libtiff</I>.
|
||
|
|
|
||
|
|
If the open operation fails, then zero is returned.
|
||
|
|
The
|
||
|
|
<I>mode</I>
|
||
|
|
|
||
|
|
parameter specifies if the file is to be opened for reading (``r''),
|
||
|
|
writing (``w''), or appending (``a'') and, optionally, whether
|
||
|
|
to override certain default aspects of library operation (see below).
|
||
|
|
When a file is opened for appending, existing data will not
|
||
|
|
be touched; instead new data will be written as additional subfiles.
|
||
|
|
If an existing file is opened for writing, all previous data is
|
||
|
|
overwritten.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
If a file is opened for reading, the first
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
directory in the file is automatically read
|
||
|
|
(also see
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?TIFFSetDirectory+3t">TIFFSetDirectory</A></I>(3T)
|
||
|
|
|
||
|
|
for reading directories other than the first).
|
||
|
|
If a file is opened for writing or appending, a default directory
|
||
|
|
is automatically created for writing subsequent data.
|
||
|
|
This directory has all the default values specified in
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
Revision 6.0:
|
||
|
|
<I>BitsPerSample</I>=1,
|
||
|
|
|
||
|
|
<I>ThreshHolding</I>=bilevel art scan,
|
||
|
|
|
||
|
|
<I>FillOrder</I>=1
|
||
|
|
|
||
|
|
(most significant bit of each data byte is filled first),
|
||
|
|
<I>Orientation</I>=1
|
||
|
|
|
||
|
|
(the 0th row represents the visual top of the image, and the 0th
|
||
|
|
column represents the visual left hand side),
|
||
|
|
<I>SamplesPerPixel</I>=1,
|
||
|
|
|
||
|
|
<I>RowsPerStrip</I>=infinity,
|
||
|
|
|
||
|
|
<I>ResolutionUnit</I>=2
|
||
|
|
|
||
|
|
(inches), and
|
||
|
|
<I>Compression</I>=1
|
||
|
|
|
||
|
|
(no compression).
|
||
|
|
To alter these values, or to define values for additional fields,
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?TIFFSetField+3t">TIFFSetField</A></I>(3T)
|
||
|
|
|
||
|
|
must be used.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<I>TIFFFdOpen</I>
|
||
|
|
|
||
|
|
is like
|
||
|
|
<I>TIFFOpen</I>
|
||
|
|
|
||
|
|
except that it opens a
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
file given an open file descriptor
|
||
|
|
<I>fd</I>.
|
||
|
|
|
||
|
|
The file's name and mode must reflect that of the open descriptor.
|
||
|
|
The object associated with the file descriptor
|
||
|
|
<B>must support random access</B>.
|
||
|
|
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<I>TIFFClientOpen</I>
|
||
|
|
|
||
|
|
is like
|
||
|
|
<I>TIFFOpen</I>
|
||
|
|
|
||
|
|
except that the caller supplies a collection of functions that the
|
||
|
|
library will use to do <FONT SIZE="-1">UNIX</FONT>-like I/O operations.
|
||
|
|
The
|
||
|
|
<I>readproc</I>
|
||
|
|
|
||
|
|
and
|
||
|
|
<I>writeproc</I>
|
||
|
|
|
||
|
|
are called to read and write data at the current file position.
|
||
|
|
<I>seekproc</I>
|
||
|
|
|
||
|
|
is called to change the current file position a la
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?lseek+2">lseek</A></I>(2).
|
||
|
|
|
||
|
|
<I>closeproc</I>
|
||
|
|
|
||
|
|
is invoked to release any resources associated with an open file.
|
||
|
|
<I>sizeproc</I>
|
||
|
|
|
||
|
|
is invoked to obtain the size in bytes of a file.
|
||
|
|
<I>mapproc</I>
|
||
|
|
|
||
|
|
and
|
||
|
|
<I>unmapproc</I>
|
||
|
|
|
||
|
|
are called to map and unmap a file's contents in memory; c.f.
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?mmap+2">mmap</A></I>(2)
|
||
|
|
|
||
|
|
and
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?munmap+2">munmap</A></I>(2).
|
||
|
|
|
||
|
|
The
|
||
|
|
<I>clientdata</I>
|
||
|
|
|
||
|
|
parameter is an opaque ``handle'' passed to the client-specified
|
||
|
|
routines passed as parameters to
|
||
|
|
<I>TIFFClientOpen</I>.
|
||
|
|
|
||
|
|
<A NAME="lbAE"> </A>
|
||
|
|
<H2>OPTIONS</H2>
|
||
|
|
|
||
|
|
The open mode parameter can include the following flags in
|
||
|
|
addition to the ``r'', ``w'', and ``a'' flags.
|
||
|
|
Note however that option flags must follow the read-write-append
|
||
|
|
specification.
|
||
|
|
<DL COMPACT>
|
||
|
|
<DT><B>l</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
When creating a new file force information be written with
|
||
|
|
Little-Endian byte order (but see below).
|
||
|
|
By default the library will create new files using the native
|
||
|
|
<FONT SIZE="-1">CPU</FONT>
|
||
|
|
byte order.
|
||
|
|
<DT><B>b</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
When creating a new file force information be written with
|
||
|
|
Big-Endian byte order (but see below).
|
||
|
|
By default the library will create new files using the native
|
||
|
|
<FONT SIZE="-1">CPU</FONT>
|
||
|
|
byte order.
|
||
|
|
<DT><B>L</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Force image data that is read or written to be treated with
|
||
|
|
bits filled from Least Significant Bit (<FONT SIZE="-1">LSB</FONT>) to
|
||
|
|
Most Significant Bit (<FONT SIZE="-1">MSB</FONT>).
|
||
|
|
Note that this is the opposite to the way the library has
|
||
|
|
worked from its inception.
|
||
|
|
<DT><B>B</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Force image data that is read or written to be treated with
|
||
|
|
bits filled from Most Significant Bit (<FONT SIZE="-1">MSB</FONT>) to
|
||
|
|
Least Significant Bit (<FONT SIZE="-1">LSB</FONT>); this is the default.
|
||
|
|
<DT><B>H</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Force image data that is read or written to be treated with
|
||
|
|
bits filled in the same order as the native
|
||
|
|
<FONT SIZE="-1">CPU.</FONT>
|
||
|
|
<DT><B>M</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Enable the use of memory-mapped files for images opened read-only.
|
||
|
|
If the underlying system does not support memory-mapped files
|
||
|
|
or if the specific image being opened cannot be memory-mapped
|
||
|
|
then the library will fallback to using the normal system interface
|
||
|
|
for reading information.
|
||
|
|
By default the library will attempt to use memory-mapped files.
|
||
|
|
<DT><B>m</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Disable the use of memory-mapped files.
|
||
|
|
<DT><B>C</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Enable the use of ``strip chopping'' when reading images
|
||
|
|
that are comprised of a single strip or tile of uncompressed data.
|
||
|
|
Strip chopping is a mechanism by which the library will automatically
|
||
|
|
convert the single-strip image to multiple strips,
|
||
|
|
each of which has about 8 Kilobytes of data.
|
||
|
|
This facility can be useful in reducing the amount of memory used
|
||
|
|
to read an image because the library normally reads each strip
|
||
|
|
in its entirety.
|
||
|
|
Strip chopping does however alter the apparent contents of the
|
||
|
|
image because when an image is divided into multiple strips it
|
||
|
|
looks as though the underlying file contains multiple separate
|
||
|
|
strips.
|
||
|
|
Finally, note that default handling of strip chopping is a compile-time
|
||
|
|
configuration parameter.
|
||
|
|
The default behaviour, for backwards compatibility, is to enable
|
||
|
|
strip chopping.
|
||
|
|
<DT><B>c</B>
|
||
|
|
|
||
|
|
<DD>
|
||
|
|
Disable the use of strip chopping when reading images.
|
||
|
|
</DL>
|
||
|
|
<A NAME="lbAF"> </A>
|
||
|
|
<H2>BYTE ORDER</H2>
|
||
|
|
|
||
|
|
The
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
specification (<B>all versions</B>) states that compliant readers
|
||
|
|
<I>must be capable of reading images written in either byte order</I>.
|
||
|
|
|
||
|
|
Nonetheless some software that claims to support the reading of
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
images is incapable of reading images in anything but the native
|
||
|
|
<FONT SIZE="-1">CPU</FONT>
|
||
|
|
byte order on which the software was written.
|
||
|
|
(Especially notorious
|
||
|
|
are applications written to run on Intel-based machines.)
|
||
|
|
By default the library will create new files with the native
|
||
|
|
byte-order of the
|
||
|
|
<FONT SIZE="-1">CPU</FONT>
|
||
|
|
on which the application is run.
|
||
|
|
This ensures optimal performance and is portable to any application
|
||
|
|
that conforms to the TIFF specification.
|
||
|
|
To force the library to use a specific byte-order when creating
|
||
|
|
a new file the ``b'' and ``l'' option flags may be included in
|
||
|
|
the call to open a file; for example, ``wb'' or ``wl''.
|
||
|
|
<A NAME="lbAG"> </A>
|
||
|
|
<H2>RETURN VALUES</H2>
|
||
|
|
|
||
|
|
Upon successful completion
|
||
|
|
<I>TIFFOpen</I>,
|
||
|
|
|
||
|
|
<I>TIFFFdOpen</I>,
|
||
|
|
|
||
|
|
and
|
||
|
|
<I>TIFFClientOpen</I>
|
||
|
|
|
||
|
|
return a
|
||
|
|
<FONT SIZE="-1">TIFF</FONT>
|
||
|
|
pointer.
|
||
|
|
Otherwise, NULL is returned.
|
||
|
|
<A NAME="lbAH"> </A>
|
||
|
|
<H2>DIAGNOSTICS</H2>
|
||
|
|
|
||
|
|
All error messages are directed to the
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?TIFFError+3t">TIFFError</A></I>(3T)
|
||
|
|
|
||
|
|
routine.
|
||
|
|
Likewise, warning messages are directed to the
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?TIFFWarning+3t">TIFFWarning</A></I>(3T)
|
||
|
|
|
||
|
|
routine.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>"%s": Bad mode</B>.
|
||
|
|
The specified
|
||
|
|
<I>mode</I>
|
||
|
|
|
||
|
|
parameter was not one of ``r'' (read), ``w'' (write), or ``a'' (append).
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>%s: Cannot open</B>.
|
||
|
|
|
||
|
|
<I>TIFFOpen</I>()
|
||
|
|
|
||
|
|
was unable to open the specified filename for read/writing.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>Cannot read TIFF header</B>.
|
||
|
|
|
||
|
|
An error occurred while attempting to read the header information.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>Error writing TIFF header</B>.
|
||
|
|
|
||
|
|
An error occurred while writing the default header information
|
||
|
|
for a new file.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>Not a TIFF file, bad magic number %d (0x%x)</B>.
|
||
|
|
|
||
|
|
The magic number in the header was not (hex)
|
||
|
|
0x4d4d or (hex) 0x4949.
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>Not a TIFF file, bad version number %d (0x%x)</B>.
|
||
|
|
|
||
|
|
The version field in the header was not 42 (decimal).
|
||
|
|
<P>
|
||
|
|
|
||
|
|
<B>Cannot append to file that has opposite byte ordering</B>.
|
||
|
|
|
||
|
|
A file with a byte ordering opposite to the native byte
|
||
|
|
ordering of the current machine was opened for appending (``a'').
|
||
|
|
This is a limitation of the library.
|
||
|
|
<A NAME="lbAI"> </A>
|
||
|
|
<H2>SEE ALSO</H2>
|
||
|
|
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?libtiff+3t">libtiff</A></I>(3T),
|
||
|
|
|
||
|
|
<I><A HREF="http:/cgi-bin/man2html?TIFFClose+3t">TIFFClose</A></I>(3T)
|
||
|
|
|
||
|
|
|
||
|
|
<HR>
|
||
|
|
<A NAME="index"> </A><H2>Index</H2>
|
||
|
|
<DL>
|
||
|
|
<DT><A HREF="#lbAB">NAME</A><DD>
|
||
|
|
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
|
|
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
|
|
<DT><A HREF="#lbAE">OPTIONS</A><DD>
|
||
|
|
<DT><A HREF="#lbAF">BYTE ORDER</A><DD>
|
||
|
|
<DT><A HREF="#lbAG">RETURN VALUES</A><DD>
|
||
|
|
<DT><A HREF="#lbAH">DIAGNOSTICS</A><DD>
|
||
|
|
<DT><A HREF="#lbAI">SEE ALSO</A><DD>
|
||
|
|
</DL>
|
||
|
|
<HR>
|
||
|
|
This document was created by
|
||
|
|
<A HREF="index.html">man2html</A>,
|
||
|
|
using the manual pages.<BR>
|
||
|
|
Time: 01:31:37 GMT, November 23, 1999
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|