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

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

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

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

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