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

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

<?PubInc>

<refentry id="TIFFRGBAImage-3tiff">

<refmeta><refentrytitle>TIFFRGBAImage</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>TIFFRGBAImage</primary></indexterm><indexterm><primary>

read and decode an image into a raster</primary></indexterm>

<refnamediv id="TIFFRGBAImage-3tiff-name"><refdescriptor>TIFFRGBAImage</refdescriptor>

<refname>TIFFRGBAImageBegin</refname><refname>TIFFRGBAImageEnd</refname><refname>

TIFFRGBAImageGet</refname><refname>TIFFRGBAImageOK</refname><refname>TIFFRGBAImageOriented<?Pub Caret>

</refname><refpurpose>read and decode an image into a raster</refpurpose>

</refnamediv>

<refsect1 id="TIFFRGBAImage-3tiff-synp"><title>&synp-tt;</title>

<programlisting>#include &lt;tiffio.h>

typedef unsigned char TIFFRGBValue;

typedef struct _TIFFRGBAImage TIFFRGBAImage;

int TIFFRGBAImageOK(TIFF* tif, char emsg[1024]);

int TIFFRGBAImageBegin(TIFFRGBAImage* img, TIFF* tif, int stopOnError, char emsg[1024]);

int TIFFRGBAImageGet(TIFFRGBAImage* img, uint32* raster, uint32 width, uint32 height);

void TIFFRGBAImageEnd(TIFFRGBAImage* img);</programlisting>

</refsect1>

<refsect1 id="TIFFRGBAImage-3tiff-desc"><title>&desc-tt;</title>

<para>The routines described here provide a high-level interface through which

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

and so on. Decoding state is encapsulated in a <literal>TIFFRGBAImage</literal>

structure, which makes it possible to capture state for multiple images and

quickly switch between them. The target raster format can be customized to

the needs of a particular application by installing custom routines that manipulate

image data according to application requirements.</para>

<para>The default usage of these routines is as follows:</para>

<orderedlist>

<listitem><para>Use <literal>TIFFRGBAImageOK</literal> to check whether an

image can be processed.</para></listitem>

<listitem><para>Use <literal>TIFFRGBAImageBegin</literal> to construct a decoder

state block.</para></listitem>

<listitem><para>Use <literal>TIFFRGBAImageGet</literal> to read and decode

an image into a target raster.</para></listitem>

<listitem><para>Use <literal>TIFFRGBAImageEnd</literal> to release resources.

</para></listitem>

</orderedlist>

<para><literal>TIFFRGBAImageGet</literal> 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 <literal>

TIFFRGBAImageGet</literal> as needed to display an image.</para>

<para>The generated raster is assumed to be an array of <replaceable>width

</replaceable> times <replaceable>height</replaceable> 32-bit entries, where <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="TIFFRGBAImage-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>TIFFRGBAImageGet</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>

TIFFRGBAImageGet</literal> continues to process data until all of the possible

data in the image has been requested.</para>

<refsect2 id="TIFFRGBAImage-3tiff-exde-raster">

<title>Alternate Raster Formats</title>

<para>To use the core support for reading and processing TIFF images, but

write the resulting raster data in a different format, you need only override

the &ldquo;put methods&rdquo; used to store raster data. These methods are

defined in the <literal>TIFFRGBAImage</literal> structure and initially set

up by <literal>TIFFRGBAImageBegin</literal> to point to routines that pack

raster data in the default ABGR pixel format. </para>

<para>Two different routines are used according to the physical organization

of the image data in the file:</para>

<itemizedlist>

<listitem><para>PlanarConfiguration=1 (packed samples)</para></listitem>

<listitem><para>PlanarConfiguration=2 (separated samples). </para></listitem>

</itemizedlist>

<para>Note that this mechanism can be used to transform the data before storing

the data in the raster. For example, you can convert data to colormap indices

for display on a colormap display.</para>

</refsect2>

<refsect2 id="TIFFRGBAImage-3tiff-exde-display">

<title>Simultaneous Raster Store and Display</title>

<para>An image can be displayed as the image is being into memory by overriding

the put methods as described above to support alternate raster formats. Simply

keep a reference to the default put methods set up by <literal>TIFFRGBAImageBegin

</literal> and then invoke these methods before or after each display operation.

For example, the <command>tiffgt(1)</command> utility uses the following put

method to update the display as the raster is being filled:</para>

<programlisting>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);

}

}

</programlisting>

<para>The original routine provided by the library is saved in the variable <literal>

putContig</literal>.</para>

</refsect2>

<refsect2 id="TIFFRGBAImage-3tiff-exde-tiff">

<title>Supporting Additional TIFF Formats</title>

<para>The <literal>TIFFRGBAImage</literal> routines support the most commonly

encountered flavors of TIFF. You can extend this support by overriding the &ldquo;get

method&rdquo; invoked by <literal>TIFFRGBAImageGet</literal> to read TIFF

image data. Details of how to do this can be quite involved, it is best to

make a copy of an existing get method and modify to suit the needs of an application.

</para>

</refsect2>

<refsect2 id="TIFFRGBAImage-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="TIFFRGBAImage-3tiff-rtrn"><title>&rtrn-tt;</title>

<para>All routines return 1 if the operation was successful. Otherwise, 0

is returned if an error was encountered and <literal>stopOnError</literal>

is zero.</para>

</refsect1>

<refsect1 id="TIFFRGBAImage-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="TIFFRGBAImage-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>TIFFReadRGBAImage

</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="TIFFRGBAImage-3tiff-note"><title>&note-tt;</title>

<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>Orientations other than bottom-left or top-left are not processed correctly.

</para>

<para>This man page was originally written by Sam Leffler. Updated by Breda

McColgan, Sun Microsystems Inc., 2004.</para>

</refsect1>

</refentry>

<?Pub *0000013365>