summaryrefslogtreecommitdiffstats
path: root/src/3rdparty/libtiff/html/man/TIFFWriteScanline.3tiff.html
blob: da929e7295956d33bb345e45d1efe4a27c0482b9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
<!-- 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>