src/tiff/html/man/TIFFWriteScanline.3tiff.html

   1 <!-- Creator     : groff version 1.18.1 -->
   2 <!-- CreationDate: Sat Feb 24 18:37:18 2007 -->
   3 <html>
   4 <head>
   5 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   6 <meta name="Content-Style" content="text/css">
   7 <title>TIFFWriteScanline</title>
   8 </head>
   9 <body>
  10
  11 <h1 align=center>TIFFWriteScanline</h1>
  12 <a href="#NAME">NAME</a><br>
  13 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  14 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  15 <a href="#NOTES">NOTES</a><br>
  16 <a href="#RETURN VALUES">RETURN VALUES</a><br>
  17 <a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
  18 <a href="#BUGS">BUGS</a><br>
  19 <a href="#SEE ALSO">SEE ALSO</a><br>
  20
  21 <hr>
  22 <a name="NAME"></a>
  23 <h2>NAME</h2>
  24 <!-- INDENTATION -->
  25 <table width="100%" border=0 rules="none" frame="void"
  26        cols="2" cellspacing="0" cellpadding="0">
  27 <tr valign="top" align="left">
  28 <td width="8%"></td>
  29 <td width="91%">
  30 <p>TIFFWriteScanline &minus; write a scanline to an open
  31 <small>TIFF</small> file</p>
  32 </td>
  33 </table>
  34 <a name="SYNOPSIS"></a>
  35 <h2>SYNOPSIS</h2>
  36 <!-- INDENTATION -->
  37 <table width="100%" border=0 rules="none" frame="void"
  38        cols="2" cellspacing="0" cellpadding="0">
  39 <tr valign="top" align="left">
  40 <td width="8%"></td>
  41 <td width="91%">
  42 <p><b>#include &lt;tiffio.h&gt;</b></p>
  43 <!-- INDENTATION -->
  44 <p><b>int TIFFWriteScanline(TIFF *</b><i>tif</i><b>,
  45 tdata_t</b> <i>buf</i><b>, uint32</b> <i>row</i><b>,
  46 tsample_t</b> <i>sample</i><b>)</b></p>
  47 </td>
  48 </table>
  49 <a name="DESCRIPTION"></a>
  50 <h2>DESCRIPTION</h2>
  51 <!-- INDENTATION -->
  52 <table width="100%" border=0 rules="none" frame="void"
  53        cols="2" cellspacing="0" cellpadding="0">
  54 <tr valign="top" align="left">
  55 <td width="8%"></td>
  56 <td width="91%">
  57 <p>Write data to a file at the specified row. The
  58 <i>sample</i> parameter is used only if data are organized
  59 in separate planes (<i>PlanarConfiguration</i>=2). The data
  60 are assumed to be uncompressed and in the native bit- and
  61 byte-order of the host machine. The data written to the file
  62 is compressed according to the compression scheme of the
  63 current <small>TIFF</small> directory (see further below).
  64 If the current scanline is past the end of the current
  65 subfile, the <i>ImageLength</i> field is automatically
  66 increased to include the scanline (except for
  67 <i>PlanarConfiguration</i>=2, where the <i>ImageLength</i>
  68 cannot be changed once the first data are written). If the
  69 <i>ImageLength</i> is increased, the <i>StripOffsets</i> and
  70 <i>StripByteCounts</i> fields are similarly enlarged to
  71 reflect data written past the previous end of image.</p>
  72 </td>
  73 </table>
  74 <a name="NOTES"></a>
  75 <h2>NOTES</h2>
  76 <!-- INDENTATION -->
  77 <table width="100%" border=0 rules="none" frame="void"
  78        cols="2" cellspacing="0" cellpadding="0">
  79 <tr valign="top" align="left">
  80 <td width="8%"></td>
  81 <td width="91%">
  82 <p>The library writes encoded data using the native machine
  83 byte order. Correctly implemented <small>TIFF</small>
  84 readers are expected to do any necessary byte-swapping to
  85 correctly process image data with BitsPerSample greater than
  86 8. The library attempts to hide bit-ordering differences
  87 between the image and the native machine by converting data
  88 from the native machine order.</p>
  89 <!-- INDENTATION -->
  90 <p>In C++ the <i>sample</i> parameter defaults to 0.</p>
  91 <!-- INDENTATION -->
  92 <p>Once data are written to a file for the current
  93 directory, the values of certain tags may not be altered;
  94 see <i>TIFFSetField</i>(3TIFF) for more information.</p>
  95 <!-- INDENTATION -->
  96 <p>It is not possible to write scanlines to a file that uses
  97 a tiled organization. The routine <i>TIFFIsTiled</i> can be
  98 used to determine if the file is organized as tiles or
  99 strips.</p>
 100 </td>
 101 </table>
 102 <a name="RETURN VALUES"></a>
 103 <h2>RETURN VALUES</h2>
 104 <!-- INDENTATION -->
 105 <table width="100%" border=0 rules="none" frame="void"
 106        cols="2" cellspacing="0" cellpadding="0">
 107 <tr valign="top" align="left">
 108 <td width="8%"></td>
 109 <td width="91%">
 110 <p><i>TIFFWriteScanline</i> returns &minus;1 if it
 111 immediately detects an error and 1 for a successful
 112 write.</p>
 113 </td>
 114 </table>
 115 <a name="DIAGNOSTICS"></a>
 116 <h2>DIAGNOSTICS</h2>
 117 <!-- INDENTATION -->
 118 <table width="100%" border=0 rules="none" frame="void"
 119        cols="2" cellspacing="0" cellpadding="0">
 120 <tr valign="top" align="left">
 121 <td width="8%"></td>
 122 <td width="91%">
 123 <p>All error messages are directed to the
 124 <i>TIFFError</i>(3TIFF) routine.</p>
 125 <!-- INDENTATION -->
 126 <p><b>%s: File not open for writing .</b> The file was
 127 opened for reading, not writing.</p>
 128 <!-- INDENTATION -->
 129 <p><b>Can not write scanlines to a tiled image</b>. An
 130 attempt was made to write a scanline to a tiled image. The
 131 image is assumed to be organized in tiles because the
 132 <i>TileWidth</i> and <i>TileLength</i> tags have been set
 133 with <i>TIFFSetField</i>(3TIFF).</p>
 134 <!-- INDENTATION -->
 135 <p><b>Compression algorithm does not support random
 136 access</b>. Data was written in a non-sequential order to a
 137 file that uses a compression algorithm and that has
 138 <i>RowsPerStrip</i> greater than one. That is, data in the
 139 image is to be stored in a compressed form, and with
 140 multiple rows packed into a strip. In this case, the library
 141 does not support random access to the data. The data should
 142 either be written as entire strips, sequentially by rows, or
 143 the value of <i>RowsPerStrip</i> should be set to one.</p>
 144 <!-- INDENTATION -->
 145 <p><b>%s: Must set &quot;ImageWidth&quot; before writing
 146 data</b>. The image&rsquo;s width has not be set before the
 147 first write. See <b>TIFFSetField</b>(3TIFF) for information
 148 on how to do this.</p>
 149 <!-- INDENTATION -->
 150 <p><b>%s: Must set &quot;PlanarConfiguration&quot; before
 151 writing data</b>. The organization of data has not be
 152 defined before the first write. See
 153 <b>TIFFSetField</b>(3TIFF) for information on how to do
 154 this.</p>
 155 <!-- INDENTATION -->
 156 <p><b>Can not change &quot;ImageLength&quot; when using
 157 separate planes</b>. Separate image planes are being used
 158 (<i>PlanarConfiguration</i>=2), but the number of rows has
 159 not been specified before the first write. The library
 160 supports the dynamic growth of an image only when data are
 161 organized in a contiguous manner
 162 (<i>PlanarConfiguration</i>=1).</p>
 163 <!-- INDENTATION -->
 164 <p><b>%d: Sample out of range, max %d</b>. The <i>sample</i>
 165 parameter was greater than the value of the SamplesPerPixel
 166 tag.</p>
 167 <!-- INDENTATION -->
 168 <p><b>%s: No space for strip arrays .</b> There was not
 169 enough space for the arrays that hold strip offsets and byte
 170 counts.</p>
 171 </td>
 172 </table>
 173 <a name="BUGS"></a>
 174 <h2>BUGS</h2>
 175 <!-- INDENTATION -->
 176 <table width="100%" border=0 rules="none" frame="void"
 177        cols="2" cellspacing="0" cellpadding="0">
 178 <tr valign="top" align="left">
 179 <td width="8%"></td>
 180 <td width="91%">
 181 <p>Writing subsampled YCbCR data does not work correctly
 182 because, for <i>PlanarConfiguration</i>=2 the size of a
 183 scanline is not calculated on a per-sample basis, and for
 184 <i>PlanarConfiguration</i>=1 the library does not pack the
 185 block-interleaved samples.</p>
 186 </td>
 187 </table>
 188 <a name="SEE ALSO"></a>
 189 <h2>SEE ALSO</h2>
 190 <!-- INDENTATION -->
 191 <table width="100%" border=0 rules="none" frame="void"
 192        cols="2" cellspacing="0" cellpadding="0">
 193 <tr valign="top" align="left">
 194 <td width="8%"></td>
 195 <td width="91%">
 196 <p><b>TIFFOpen</b>(3TIFF),
 197 <b>TIFFWriteEncodedStrip</b>(3TIFF),
 198 <b>TIFFWriteRawStrip</b>(3TIFF), <b>libtiff</b>(3TIFF)</p>
 199 <!-- INDENTATION -->
 200 <p>Libtiff library home page:
 201 <b>http://www.remotesensing.org/libtiff/</b></p>
 202 </td>
 203 </table>
 204 <hr>
 205 </body>
 206 </html>