<!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 synp-tt "SYNOPSIS">
<!ENTITY cmd "TIFFWriteScanline">
<!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="TIFFWriteScanline-3tiff">
<!-- %Z%%M% %I% %E% SMI; -->
<refmeta><refentrytitle>TIFFWriteScanline</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>TIFFWriteScanline</primary></indexterm><indexterm><primary>
write a scanline to an open TIFF file</primary></indexterm>
<refnamediv id="TIFFWriteScanline-3tiff-name"><refname>TIFFWriteScanline</refname>
<refpurpose>write a scanline to an open TIFF file</refpurpose></refnamediv>
<refsect1 id="TIFFWriteScanline-3tiff-synp"><title>&synp-tt;</title>
<programlisting>#include &lt;tiffio.h>
int TIFFWriteScanline(TIFF* tif, tdata_t buf, uint32 row,
tsample_t sample);

</programlisting>
</refsect1>
<refsect1 id="TIFFWriteScanline-3tiff-desc"><title>&desc-tt;</title>
<para>Write data to a file at the specified row. The <literal>sample</literal>
parameter is used only if data is organized in separate planes (PlanarConfiguration=2).
The data is assumed to be uncompressed and in the native bit- and byte-order
of the host machine. The data written to the file is compressed according
to the compression scheme of the current TIFF directory as described below.
If the current scanline is past the end of the current subfile, the <literal>
ImageLength</literal> field is automatically increased to include the scanline
(except for PlanarConfiguration=2, where the <literal>ImageLength</literal>
cannot be changed once the first data is written). If the <literal>ImageLength
</literal> is increased, the <literal>StripOffsets</literal> and <literal>
StripByteCounts</literal> fields are similarly enlarged to reflect data written
past the previous end of image.</para>
</refsect1>
<refsect1 id="TIFFWriteRawTile-3tiff-exde"><title>&exde-tt;</title>
<para>The library writes encoded data using the native machine byte order.
Correctly implemented TIFF readers are expected to do any necessary byte-swapping
to correctly process image data with <literal>BitsPerSample</literal> greater
than 8. The library attempts to hide bit-ordering differences between the
image and the native machine by converting data from the native machine order.
</para>
<refsect2 id="TIFFWriteRawTile-3tiff-exde-diags">
<title>Diagnostics</title>
<para>All error messages are directed to the <literal>TIFFError(3tiff)</literal>
routine.</para>
<variablelist>
<varlistentry><term>%s: File not open for writing.</term><listitem><para>
The file was opened for reading, not writing.</para>
</listitem></varlistentry>
<varlistentry><term>Can not write scanlines to a tiled image.</term><listitem>
<para>An attempt was made to write a scanline to a tiled image. The image
is assumed to be organized in tiles because the <literal>TileWidth</literal>
and <literal>TileLength</literal> tags have been set with <literal>TIFFSetField(3tiff)
</literal>.</para>
</listitem></varlistentry>
<varlistentry><term>Compression algorithm does not support random access.
</term><listitem><para>Data was written in a non-sequential order to a file
that uses a compression algorithm and that has <literal>RowsPerStrip</literal>
greater than one. That is, data in the image is to be stored in a compressed
form, and with multiple rows packed into a strip. In this case, the library
does not support random access to the data. The data should either be written
as entire strips, sequentially by rows, or the value of <literal>RowsPerStrip
</literal> should be set to one.</para>
</listitem></varlistentry>
<varlistentry><term>%s: Must set "ImageWidth" before writing data.</term>
<listitem><para>The image width has not been set before the first write. See <literal>
TIFFSetField(3tiff)</literal> for information on how to do this.</para>
</listitem></varlistentry>
<varlistentry><term>%s: Must set "PlanarConfiguration" before writing data.
</term><listitem><para>The organization of data has not been defined before
the first write. See <literal>TIFFSetField(3tiff)</literal> for information on
how to do this.</para>
</listitem></varlistentry>
<varlistentry><term>Can not change "ImageLength" when using separate planes.
</term><listitem><para>Separate image planes are being used (PlanarConfiguration=2),
but the number of rows has not been specified before the first write. The
library supports the dynamic growth of an image only when data is organized
in a contiguous manner (PlanarConfiguration=1).</para>
</listitem></varlistentry>
<varlistentry><term>%d: Sample out of range, max %d.</term><listitem><para>
The <literal>sample</literal> parameter was greater than the value of the <literal>
SamplesPerPixel</literal> tag.</para>
</listitem></varlistentry>
<varlistentry><term>%s: No space for strip arrays".</term><listitem><para>
There was not enough space for the arrays that hold strip offsets and byte
counts.</para>
</listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1 id="TIFFWriteScanline-3tiff-rtrn"><title>&rtrn-tt;</title>
<para>Returns &mdash;1 if it immediately detects an error, and 1 for a successful
write.</para>
</refsect1>
<refsect1 id="TIFFWriteScanline-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="TIFFWriteScanline-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>TIFFWriteEncodedStrip
</refentrytitle><manvolnum>3tiff</manvolnum></citerefentry>, <citerefentry>
<refentrytitle>TIFFWriteRawStrip</refentrytitle><manvolnum>3tiff</manvolnum>
</citerefentry></para>
</refsect1>
<refsect1 id="TIFFWriteScanline-3tiff-note"><title>&note-tt;</title>
<para>In C++, the sample parameter defaults to 0.</para>
<para>Once data is written to a file for the current directory, the values
of certain tags may not be altered. See <literal>TIFFSetField(3tiff)</literal>
for more information.</para>
<para>It is not possible to write scanlines to a file that uses a tiled organization.
The routine <literal>TIFFIsTiled</literal> can be used to determine if the
file is organized as tiles or strips.</para>
<para>Writ<?Pub Caret>ing subsampled YCbCR data does not work correctly because:
</para>
<itemizedlist>
<listitem><para>For PlanarConfiguration=2, the size of a scanline is not calculated
on a per-sample basis.</para></listitem>
<listitem><para>For PlanarConfiguration=1, the library does not unpack the
block-interleaved samples.</para></listitem>
</itemizedlist>
<para>This man page was originally written by Sam Leffler. Updated by Breda
McColgan, Sun Microsystems Inc., 2004.</para>
</refsect1>
</refentry>
<?Pub *0000008302>
