c3402403ea
be used if build directory is not the same as source directory.
* man/{TIFFGetField.3tiff, man/TIFFSetField.3tiff}: Documented
TIFFTAG_PHOTOSHOP, TIFFTAG_RICHTIFFIPTC, and TIFFTAG_XMLPACKET,
and re-sorted tag names in alphabetical order.
309 lines
11 KiB
HTML
309 lines
11 KiB
HTML
<!-- Creator : groff version 1.19.2 -->
|
|
<!-- CreationDate: Mon Jan 2 17:41:44 2006 -->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="groff -Thtml, see www.gnu.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
|
<meta name="Content-Style" content="text/css">
|
|
<style type="text/css">
|
|
p { margin-top: 0; margin-bottom: 0; }
|
|
pre { margin-top: 0; margin-bottom: 0; }
|
|
table { margin-top: 0; margin-bottom: 0; }
|
|
</style>
|
|
<title>TIFFRGBAImage</title>
|
|
|
|
</head>
|
|
<body>
|
|
|
|
<h1 align=center>TIFFRGBAImage</h1>
|
|
|
|
<a href="#NAME">NAME</a><br>
|
|
<a href="#SYNOPSIS">SYNOPSIS</a><br>
|
|
<a href="#DESCRIPTION">DESCRIPTION</a><br>
|
|
<a href="#ALTERNATE RASTER FORMATS">ALTERNATE RASTER FORMATS</a><br>
|
|
<a href="#SIMULTANEOUS RASTER STORE AND DISPLAY">SIMULTANEOUS RASTER STORE AND DISPLAY</a><br>
|
|
<a href="#SUPPORTING ADDITIONAL TIFF FORMATS">SUPPORTING ADDITIONAL TIFF FORMATS</a><br>
|
|
<a href="#NOTES">NOTES</a><br>
|
|
<a href="#RETURN VALUES">RETURN VALUES</a><br>
|
|
<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
|
|
<a href="#SEE ALSO">SEE ALSO</a><br>
|
|
|
|
<hr>
|
|
|
|
|
|
<a name="NAME"></a>
|
|
<h2>NAME</h2>
|
|
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">TIFFRGBAImageOK,
|
|
TIFFRGBAImageBegin, TIFFRGBAImageGet, TIFFRGBAImageEnd
|
|
− read and decode an image into a raster</p>
|
|
|
|
<a name="SYNOPSIS"></a>
|
|
<h2>SYNOPSIS</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>#include
|
|
<tiffio.h></b></p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>typedef
|
|
unsigned char TIFFRGBValue; typedef struct _TIFFRGBAImage
|
|
TIFFRGBAImage;</b></p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>int
|
|
TIFFRGBAImageOK(TIFF *</b><i>tif</i><b>, char</b>
|
|
<i>emsg[1024]</i><b>) <br>
|
|
int TIFFRGBAImageBegin(TIFFRGBAImage *</b><i>img</i><b>,
|
|
TIFF*</b> <i>tif</i><b>, int</b> <i>stopOnError</i><b>,
|
|
char</b> <i>emsg[1024]</i><b>) <br>
|
|
int TIFFRGBAImageGet(TIFFRGBAImage *</b><i>img</i><b>,
|
|
uint32*</b> <i>raster</i><b>, uint32</b> <i>width</i> <b>,
|
|
uint32</b> <i>height</i><b>) <br>
|
|
void TIFFRGBAImageEnd(TIFFRGBAImage
|
|
*</b><i>img</i><b>)</b></p>
|
|
|
|
<a name="DESCRIPTION"></a>
|
|
<h2>DESCRIPTION</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">The routines
|
|
described here provide a high-level interface through which
|
|
<small>TIFF</small> images may be read into memory. Images
|
|
may be strip- or tile-based and have a variety of different
|
|
characteristics: bits/sample, samples/pixel, photometric,
|
|
etc. Decoding state is encapsulated in a
|
|
<i>TIFFRGBAImage</i> structure making it possible to capture
|
|
state for multiple images and quickly switch between them.
|
|
The target raster format can be customized to a particular
|
|
application’s needs by installing custom routines that
|
|
manipulate image data according to application
|
|
requirements.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">The default
|
|
usage for these routines is: check if an image can be
|
|
processed using <i>TIFFRGBAImageOK</i>, construct a decoder
|
|
state block using <i>TIFFRGBAImageBegin</i>, read and decode
|
|
an image into a target raster using <i>TIFFRGBAImageGet</i>,
|
|
and then release resources using <i>TIFFRGBAImageEnd</i>.
|
|
<i>TIFFRGBAImageGet</i> can be called multiple times to
|
|
decode an image using different state parameters. If
|
|
multiple images are to be displayed and there is not enough
|
|
space for each of the decoded rasters, multiple state blocks
|
|
can be managed and then calls can be made to
|
|
<i>TIFFRGBAImageGet</i> as needed to display an image.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">The generated
|
|
raster is assumed to be an array of <i>width</i> times
|
|
<i>height</i> 32-bit entries, where <i>width</i> must be
|
|
less than or equal to the width of the image (<i>height</i>
|
|
may be any non-zero size). If the raster dimensions are
|
|
smaller than the image, the image data is cropped to the
|
|
raster bounds. If the raster height is greater than that of
|
|
the image, then the image data are placed in the lower part
|
|
of the raster. (Note that the raster is assume to be
|
|
organized such that the pixel at location
|
|
(<i>x</i>,<i>y</i>) is
|
|
<i>raster</i>[<i>y</i>*<i>width</i>+<i>x</i>]; with the
|
|
raster origin in the <b>lower-left</b> hand corner.)</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">Raster pixels
|
|
are 8-bit packed red, green, blue, alpha samples. The macros
|
|
<i>TIFFGetR</i>, <i>TIFFGetG</i>, <i>TIFFGetB</i>, and
|
|
<i>TIFFGetA</i> should be used to access individual samples.
|
|
Images without Associated Alpha matting information have a
|
|
constant Alpha of 1.0 (255).</p>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><i>TIFFRGBAImageGet</i>
|
|
converts non-8-bit images by scaling sample values. Palette,
|
|
grayscale, bilevel, <small>CMYK</small> , and YCbCr images
|
|
are converted to <small>RGB</small> transparently. Raster
|
|
pixels are returned uncorrected by any colorimetry
|
|
information present in the directory.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">The parameter
|
|
<i>stopOnError</i> specifies how to act if an error is
|
|
encountered while reading the image. If <i>stopOnError</i>
|
|
is non-zero, then an error will terminate the operation;
|
|
otherwise <i>TIFFRGBAImageGet</i> will continue processing
|
|
data until all the possible data in the image have been
|
|
requested.</p>
|
|
|
|
<a name="ALTERNATE RASTER FORMATS"></a>
|
|
<h2>ALTERNATE RASTER FORMATS</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">To use the core
|
|
support for reading and processing <small>TIFF</small>
|
|
images, but write the resulting raster data in a different
|
|
format one need only override the ‘‘<i>put
|
|
methods</i>’’ used to store raster data. These
|
|
methods are are defined in the <i>TIFFRGBAImage</i>
|
|
structure and initially setup by <i>TIFFRGBAImageBegin</i>
|
|
to point to routines that pack raster data in the default
|
|
<small>ABGR</small> pixel format. Two different routines are
|
|
used according to the physical organization of the image
|
|
data in the file: <i>PlanarConfiguration</i>=1 (packed
|
|
samples), and <i>PlanarConfiguration</i>=2 (separated
|
|
samples). Note that this mechanism can be used to transform
|
|
the data before storing it in the raster. For example one
|
|
can convert data to colormap indices for display on a
|
|
colormap display.</p>
|
|
|
|
<a name="SIMULTANEOUS RASTER STORE AND DISPLAY"></a>
|
|
<h2>SIMULTANEOUS RASTER STORE AND DISPLAY</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">It is simple to
|
|
display an image as it is being read into memory by
|
|
overriding the put methods as described above for supporting
|
|
alternate raster formats. Simply keep a reference to the
|
|
default put methods setup by <i>TIFFRGBAImageBegin</i> and
|
|
then invoke them before or after each display operation. For
|
|
example, the <i>tiffgt</i>(1) utility uses the following put
|
|
method to update the display as the raster is being
|
|
filled:</p>
|
|
|
|
<pre style="margin-left:11%; margin-top: 1em">static void
|
|
putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
|
|
uint32 x, uint32 y, uint32 w, uint32 h,
|
|
int32 fromskew, int32 toskew,
|
|
unsigned char* cp)
|
|
{
|
|
(*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
|
|
if (x+w == width) {
|
|
w = width;
|
|
if (img->orientation == ORIENTATION_TOPLEFT)
|
|
lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
|
|
else
|
|
lrectwrite(0, y, w-1, y+h-1, raster);
|
|
}
|
|
}</pre>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">(the original
|
|
routine provided by the library is saved in the variable
|
|
<i>putContig</i>.)</p>
|
|
|
|
<a name="SUPPORTING ADDITIONAL TIFF FORMATS"></a>
|
|
<h2>SUPPORTING ADDITIONAL TIFF FORMATS</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">The
|
|
<i>TIFFRGBAImage</i> routines support the most commonly
|
|
encountered flavors of <small>TIFF.</small> It is possible
|
|
to extend this support by overriding the
|
|
‘‘<i>get method</i>’’ invoked by
|
|
<i>TIFFRGBAImageGet</i> to read <small>TIFF</small> image
|
|
data. Details of doing this are a bit involved, it is best
|
|
to make a copy of an existing get method and modify it to
|
|
suit the needs of an application.</p>
|
|
|
|
<a name="NOTES"></a>
|
|
<h2>NOTES</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">Samples must be
|
|
either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel
|
|
must be either 1, 3, or 4 (i.e. <i>SamplesPerPixel</i> minus
|
|
<i>ExtraSamples</i>).</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">Palette image
|
|
colormaps that appear to be incorrectly written as 8-bit
|
|
values are automatically scaled to 16-bits.</p>
|
|
|
|
<a name="RETURN VALUES"></a>
|
|
<h2>RETURN VALUES</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">All routines
|
|
return 1 if the operation was successful. Otherwise, 0 is
|
|
returned if an error was encountered and <i>stopOnError</i>
|
|
is zero.</p>
|
|
|
|
<a name="DIAGNOSTICS"></a>
|
|
<h2>DIAGNOSTICS</h2>
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">All error
|
|
messages are directed to the <i>TIFFError</i>(3TIFF)
|
|
routine.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>Sorry, can
|
|
not handle %d-bit pictures</b>. The image had
|
|
<i>BitsPerSample</i> other than 1, 2, 4, 8, or 16.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>Sorry, can
|
|
not handle %d-channel images</b>. The image had
|
|
<i>SamplesPerPixel</i> other than 1, 3, or 4.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>Missing
|
|
needed "PhotometricInterpretation" tag</b>. The
|
|
image did not have a tag that describes how to display the
|
|
data.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No
|
|
"PhotometricInterpretation" tag, assuming RGB</b>.
|
|
The image was missing a tag that describes how to display
|
|
it, but because it has 3 or 4 samples/pixel, it is assumed
|
|
to be <small>RGB.</small></p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No
|
|
"PhotometricInterpretation" tag, assuming
|
|
min-is-black</b>. The image was missing a tag that describes
|
|
how to display it, but because it has 1 sample/pixel, it is
|
|
assumed to be a grayscale or bilevel image.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No space for
|
|
photometric conversion table</b>. There was insufficient
|
|
memory for a table used to convert image samples to 8-bit
|
|
<small>RGB.</small></p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>Missing
|
|
required "Colormap" tag</b>. A Palette image did
|
|
not have a required <i>Colormap</i> tag.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No space for
|
|
tile buffer</b>. There was insufficient memory to allocate
|
|
an i/o buffer.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No space for
|
|
strip buffer</b>. There was insufficient memory to allocate
|
|
an i/o buffer.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>Can not
|
|
handle format</b>. The image has a format (combination of
|
|
<i>BitsPerSample</i>, <i>SamplesPerPixel</i>, and
|
|
<i>PhotometricInterpretation</i>) that can not be
|
|
handled.</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No space for
|
|
B&W mapping table</b>. There was insufficient memory to
|
|
allocate a table used to map grayscale data to
|
|
<small>RGB.</small></p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>No space for
|
|
Palette mapping table</b>. There was insufficient memory to
|
|
allocate a table used to map data to 8-bit
|
|
<small>RGB.</small></p>
|
|
|
|
<a name="SEE ALSO"></a>
|
|
<h2>SEE ALSO</h2>
|
|
|
|
|
|
|
|
<p style="margin-left:11%; margin-top: 1em"><b>TIFFOpen</b>(3TIFF),
|
|
<b>TIFFReadRGBAImage</b>(3TIFF),
|
|
<b>TIFFReadRGBAImageOriented</b>(3TIFF),
|
|
<b>TIFFReadRGBAStrip</b>(3TIFF),
|
|
<b>TIFFReadRGBATile</b>(3TIFF), <b>libtiff</b>(3TIFF)</p>
|
|
|
|
<p style="margin-left:11%; margin-top: 1em">Libtiff library
|
|
home page: <b>http://www.remotesensing.org/libtiff/</b></p>
|
|
<hr>
|
|
</body>
|
|
</html>
|