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

<!-- Creator     : groff version 1.18.1 -->
<!-- CreationDate: Mon Mar 13 18:03:11 2006 -->
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta name="Content-Style" content="text/css">
<title>TIFFWriteScanline</title>
</head>
<body>

<h1 align=center>TIFFWriteScanline</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#RETURN VALUES">RETURN VALUES</a><br>
<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>

<hr>
<a name="NAME"></a>
<h2>NAME</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p>TIFFWriteScanline &minus; write a scanline to an open
<small>TIFF</small> file</p>
</td>
</table>
<a name="SYNOPSIS"></a>
<h2>SYNOPSIS</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p><b>#include &lt;tiffio.h&gt;</b></p>
<!-- INDENTATION -->
<p><b>int TIFFWriteScanline(TIFF *</b><i>tif</i><b>,
tdata_t</b> <i>buf</i><b>, uint32</b> <i>row</i><b>,
tsample_t</b> <i>sample</i><b>)</b></p>
</td>
</table>
<a name="DESCRIPTION"></a>
<h2>DESCRIPTION</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p>Write data to a file at the specified row. The
<i>sample</i> parameter is used only if data are organized
in separate planes (<i>PlanarConfiguration</i>=2). The data
are 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 <small>TIFF</small> directory (see further below).
If the current scanline is past the end of the current
subfile, the <i>ImageLength</i> field is automatically
increased to include the scanline (except for
<i>PlanarConfiguration</i>=2, where the <i>ImageLength</i>
cannot be changed once the first data are written). If the
<i>ImageLength</i> is increased, the <i>StripOffsets</i> and
<i>StripByteCounts</i> fields are similarly enlarged to
reflect data written past the previous end of image.</p>
</td>
</table>
<a name="NOTES"></a>
<h2>NOTES</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p>The library writes encoded data using the native machine
byte order. Correctly implemented <small>TIFF</small>
readers are expected to do any necessary byte-swapping to
correctly process image data with BitsPerSample 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.</p>
<!-- INDENTATION -->
<p>In C++ the <i>sample</i> parameter defaults to 0.</p>
<!-- INDENTATION -->
<p>Once data are written to a file for the current
directory, the values of certain tags may not be altered;
see <i>TIFFSetField</i>(3TIFF) for more information.</p>
<!-- INDENTATION -->
<p>It is not possible to write scanlines to a file that uses
a tiled organization. The routine <i>TIFFIsTiled</i> can be
used to determine if the file is organized as tiles or
strips.</p>
</td>
</table>
<a name="RETURN VALUES"></a>
<h2>RETURN VALUES</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p><i>TIFFWriteScanline</i> returns &minus;1 if it
immediately detects an error and 1 for a successful
write.</p>
</td>
</table>
<a name="DIAGNOSTICS"></a>
<h2>DIAGNOSTICS</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p>All error messages are directed to the
<i>TIFFError</i>(3TIFF) routine.</p>
<!-- INDENTATION -->
<p><b>%s: File not open for writing .</b> The file was
opened for reading, not writing.</p>
<!-- INDENTATION -->
<p><b>Can not write scanlines to a tiled image</b>. An
attempt was made to write a scanline to a tiled image. The
image is assumed to be organized in tiles because the
<i>TileWidth</i> and <i>TileLength</i> tags have been set
with <i>TIFFSetField</i>(3TIFF).</p>
<!-- INDENTATION -->
<p><b>Compression algorithm does not support random
access</b>. Data was written in a non-sequential order to a
file that uses a compression algorithm and that has
<i>RowsPerStrip</i> 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 <i>RowsPerStrip</i> should be set to one.</p>
<!-- INDENTATION -->
<p><b>%s: Must set &quot;ImageWidth&quot; before writing
data</b>. The image&rsquo;s width has not be set before the
first write. See <b>TIFFSetField</b>(3TIFF) for information
on how to do this.</p>
<!-- INDENTATION -->
<p><b>%s: Must set &quot;PlanarConfiguration&quot; before
writing data</b>. The organization of data has not be
defined before the first write. See
<b>TIFFSetField</b>(3TIFF) for information on how to do
this.</p>
<!-- INDENTATION -->
<p><b>Can not change &quot;ImageLength&quot; when using
separate planes</b>. Separate image planes are being used
(<i>PlanarConfiguration</i>=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 are
organized in a contiguous manner
(<i>PlanarConfiguration</i>=1).</p>
<!-- INDENTATION -->
<p><b>%d: Sample out of range, max %d</b>. The <i>sample</i>
parameter was greater than the value of the SamplesPerPixel
tag.</p>
<!-- INDENTATION -->
<p><b>%s: No space for strip arrays .</b> There was not
enough space for the arrays that hold strip offsets and byte
counts.</p>
</td>
</table>
<a name="BUGS"></a>
<h2>BUGS</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p>Writing subsampled YCbCR data does not work correctly
because, for <i>PlanarConfiguration</i>=2 the size of a
scanline is not calculated on a per-sample basis, and for
<i>PlanarConfiguration</i>=1 the library does not pack the
block-interleaved samples.</p>
</td>
</table>
<a name="SEE ALSO"></a>
<h2>SEE ALSO</h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="91%">
<p><b>TIFFOpen</b>(3TIFF),
<b>TIFFWriteEncodedStrip</b>(3TIFF),
<b>TIFFWriteRawStrip</b>(3TIFF), <b>libtiff</b>(3TIFF)</p>
<!-- INDENTATION -->
<p>Libtiff library home page:
<b>http://www.remotesensing.org/libtiff/</b></p>
</td>
</table>
<hr>
</body>
</html>
Commit	Line	Data
	1	<!-- Creator : groff version 1.18.1 -->
	2	<!-- CreationDate: Mon Mar 13 18:03:11 2006 -->
	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 − 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 <tiffio.h></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 −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 "ImageWidth" before writing
	146	data</b>. The image’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 "PlanarConfiguration" 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 "ImageLength" 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>