<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!--ARC : LSARC 2003/085 libtiff, libjpeg, and libpng-->
<!ENTITY exde-tt "EXTENDED DESCRIPTION">
<!ENTITY synp-tt "SYNOPSIS">
<!ENTITY cmd "TIFFReadRGBAImage">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % gnomecommonents SYSTEM "gnomecommon.ent">
%gnomecommonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY suncopy "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.">
]>
<?Pub UDT _bookmark _target>
<?Pub EntList brvbar bull cross dash diam diams frac12 frac13 frac14 hellip
 laquo lArr loz mdash nabla ndash para pound rArr raquo sect yen amp>
<?Pub Inc>
<?PubInc>
<refentry id="TIFFReadRGBAImage-3tiff">
<!-- %Z%%M% %I% %E% SMI; -->
<refmeta><refentrytitle>TIFFReadRGBAImage</refentrytitle><manvolnum>3tiff
</manvolnum>
<refmiscinfo class="date">05 Apr 2004</refmiscinfo>
<refmiscinfo class="sectdesc">&man3;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
</refmeta>
<indexterm><primary>TIFFReadRGBAImage</primary></indexterm><indexterm><primary>
read and decode an image into a fixed-format raster</primary></indexterm>
<refnamediv id="TIFFReadRGBAImage-3tiff-name"><refname>TIFFReadRGBAImage</refname>
<refpurpose>read and decode an image into a fixed-format raster</refpurpose>
</refnamediv>
<refsect1 id="TIFFReadRGBAImage-3tiff-synp"><title>&synp-tt;</title>
<programlisting>#include &lt;tiffio.h>
#define TIFFGetR(abgr) ((abgr) &amp; 0xff)
#define TIFFGetG(abgr) (((abgr) >> 8) &amp; 0xff)
#define TIFFGetB(abgr) (((abgr) >> 16) &amp; 0xff)
#define TIFFGetA(abgr) (((abgr) >> 24) &amp; 0xff)
int TIFFReadRGBAImage(TIFF* tif, u_long width, u_long height, u_long* raster, int stopOnError)
</programlisting>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-desc"><title>&desc-tt;</title>
<para><literal>TIFFReadRGBAImage</literal> reads a strip- or tile-based image
into memory, storing the result in the user-supplied raster. The raster is
assumed to be an array of <replaceable>width</replaceable> times <replaceable>
height</replaceable> 32-bit entries, whe<?Pub Caret>re <replaceable>width
</replaceable> must be less than or equal to the width of the image, and <replaceable>
height</replaceable> 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 is
placed in the lower part of the raster. Note that the raster is assumed to
be organized such that the pixel at location (<replaceable>x,y</replaceable>)
is <replaceable>raster[y*width+x]</replaceable>, with the raster origin in
the bottom-left corner.</para>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-exde"><title>&exde-tt;</title>
<para>Raster pixels are 8-bit packed red, green, blue, alpha samples. The
macros <literal>TIFFGetR</literal>, <literal>TIFFGetG</literal>, <literal>
TIFFGetB</literal>, and <literal>TIFFGetA</literal> should be used to access
individual samples. Images without Associated Alpha matting information have
a constant Alpha of 1.0 (255).</para>
<para><literal>TIFFReadRGBAImage</literal> converts non-8-bit images by scaling
sample values. Palette, grayscale, bilevel, CMYK, and YCbCr images are converted
to RGB transparently. Raster pixels are returned uncorrected by any colorimetry
information present in the directory.</para>
<para>The parameter <literal>stopOnError</literal> specifies how to act if
an error is encountered while reading the image. If <literal>stopOnError</literal>
is non-zero, then an error terminates the operation. Otherwise, <literal>
TIFFReadRGBAImage</literal> continues to process data until all of the possible
data in the image has been requested.</para>
<para>Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel
must be either 1, 3, or 4 (that is, <literal>SamplesPerPixel</literal> minus <literal>
ExtraSamples</literal>).</para>
<para>Palette image colormaps that appear to be incorrectly written as 8-bit
values are automatically scaled to 16-bits.</para>
<para><literal>TIFFReadRGBAImage</literal> is just a wrapper around the more
general <literal>TIFFRGBAImage(3tiff)</literal> facilities.</para>
<refsect2 id="TIFFReadRGBAImage-3tiff-exde-diags">
<title>Diagnostics</title>
<para>All error messages are directed to the <literal>TIFFError(3tiff)</literal>
routine.</para>
<variablelist termlength="wholeline">
<varlistentry><term>Sorry, can not handle %d-bit pictures.</term><listitem>
<para>The image has a <literal>BitsPerSample</literal> value other than 1,
2, 4, 8, or 16.</para>
</listitem></varlistentry>
<varlistentry><term>Sorry, can not handle %d-channel images.</term><listitem>
<para>The image has a <literal>SamplesPerPixel</literal> value other than
1, 3, or 4.</para>
</listitem></varlistentry>
<varlistentry><term>Missing needed "PhotometricInterpretation" tag.</term>
<listitem><para>The image does not have a tag that describes how to display
the data.</para>
</listitem></varlistentry>
<varlistentry><term>No "PhotometricInterpretation" tag, assuming RGB.</term>
<listitem><para>The image does not have a tag that describes how to display
the data, but is assumed to be RGB because the image has 3 or 4 samples/pixel.
</para>
</listitem></varlistentry>
<varlistentry><term>No "PhotometricInterpretation" tag, assuming min-is-black.
</term><listitem><para>The image does not have a tag that describes how to
display the data, but is assumed to be a grayscale or bilevel image because
the image has 1 sample/pixel.</para>
</listitem></varlistentry>
<varlistentry><term>No space for photometric conversion table.</term><listitem>
<para>There is insufficient memory for a table needed to convert image samples
to 8-bit RGB.</para>
</listitem></varlistentry>
<varlistentry><term>Missing required "Colormap" tag.</term><listitem><para>
A Palette image does not have a required <literal>Colormap</literal> tag.
</para>
</listitem></varlistentry>
<varlistentry><term>No space for tile buffer.</term><listitem><para>There
is insufficient memory to allocate an i/o buffer.</para>
</listitem></varlistentry>
<varlistentry><term>No space for strip buffer.</term><listitem><para>There
is insufficient memory to allocate an i/o buffer.</para>
</listitem></varlistentry>
<varlistentry><term>Can not handle format.</term><listitem><para>The image
has a format (combination of <literal>BitsPerSample</literal>, <literal>SamplesPerPixel
</literal>, and <literal>PhotometricInterpretation</literal>) that <literal>
TIFFReadRGBAImage</literal> cannot process.</para>
</listitem></varlistentry>
<varlistentry><term>No space for B&amp;W mapping table.</term><listitem><para>
There is insufficient memory to allocate a table needed to map grayscale data
to RGB.</para>
</listitem></varlistentry>
<varlistentry><term>No space for Palette mapping table.</term><listitem><para>
There is insufficient memory to allocate a table needed to map data to 8-bit
RGB.</para>
</listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-rtrn"><title>&rtrn-tt;</title>
<para>1 is returned if the image was successfully read and converted. Otherwise,
0 is returned if an error was encountered and <literal>stopOnError</literal>
is zero.</para>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-attr"><title>&attr-tt;</title>
<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
for descriptions of the following attributes:</para>
<informaltable frame="all">
<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
<colspec colname="COLSPEC1" colwidth="1*">
<thead>
<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
valign="middle">ATTRIBUTE VALUE</entry></row>
</thead>
<tbody>
<row><entry><para>Availability</para></entry><entry><para>image/library/libtiff</para></entry>
</row>
<row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry
colname="COLSPEC1"><para>Uncommitted</para></entry></row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-also"><title>&also-tt;</title>
<!--Reference to another man page-->
<!--Reference to a Help manual-->
<!--Reference to a book.-->
<para><citerefentry><refentrytitle>libtiff</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry><refentrytitle>TIFFOpen</refentrytitle><manvolnum>
3tiff</manvolnum></citerefentry>, <citerefentry><refentrytitle>TIFFRGBAImage
</refentrytitle><manvolnum>3tiff</manvolnum></citerefentry>, <citerefentry>
<refentrytitle>TIFFReadRGBAStrip</refentrytitle><manvolnum>3tiff</manvolnum>
</citerefentry>, <citerefentry><refentrytitle>TIFFReadRGBATile</refentrytitle>
<manvolnum>3tiff</manvolnum></citerefentry></para>
</refsect1>
<refsect1 id="TIFFReadRGBAImage-3tiff-note"><title>&note-tt;</title>
<para>Orientations other than bottom-left or top-left are not processed correctly.
</para>
<para>In C++, the <literal>stopOnError</literal> parameter defaults to 0.
</para>
<para>This man page was originally written by Sam Leffler. Updated by Breda McColgan, Sun Microsystems Inc., 2004.</para>
</refsect1>
</refentry>
<?Pub *0000009392>
