<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [

<!--ArborText, Inc., 1988-1999, v.4002-->

<!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">

<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>

<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>