[wxWidgets.git] / 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
8414a40c VZ	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>