Initial import
git-svn-id: http://moon:8086/svn/software/trunk/libsrc/libtiff_2007@1 b431acfa-c32f-4a4a-93f1-934dc6c82436
This commit is contained in:
Executable
+361
@@ -0,0 +1,361 @@
|
||||
<!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="TIFFSetDirectory.3t.html">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="TIFFSetField.3t.html">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="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="mmap+2">mmap</A></I>(2)
|
||||
|
||||
and
|
||||
<I><A HREF="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="TIFFError.3t.html">TIFFError</A></I>(3T)
|
||||
|
||||
routine.
|
||||
Likewise, warning messages are directed to the
|
||||
<I><A HREF="TIFFWarning.3t.html">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="libtiff.3t.html">libtiff</A></I>(3T),
|
||||
|
||||
<I><A HREF="TIFFClose.3t.html">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>
|
||||
Reference in New Issue
Block a user