TIFFReadScanline - read and decode a scanline of data from
an open TIFF file
SYNOPSIS
#include <tiffio.h>
int TIFFReadScanline(TIFF* tif, tdata_t buf, uint32 row,
tsample_t sample)
DESCRIPTION
Read the data for the specified row into the (user sup
plied) data buffer buf. The data are returned decom
pressed and, in the native byte- and bit-ordering, but are
otherwise packed (see further below). The buffer must be
large enough to hold an entire scanline of data. Applica
tions should call the routine TIFFScanlineSize to find out
the size (in bytes) of a scanline buffer. The row parame
ter is always used by TIFFReadScanline; the sample parame
ter is used only if data are organized in separate planes
(PlanarConfiguration=2).
NOTES
The library attempts to hide bit- and byte-ordering dif
ferences between the image and the native machine by con
verting data to the native machine order. Bit reversal is
done if the FillOrder tag is opposite to the native
machine bit order. 16- and 32-bit samples are automati
cally byte-swapped if the file was written with a byte
order opposite to the native machine byte order,
In C++ the sample parameter defaults to 0.
RETURN VALUES
TIFFReadScanline returns -1 if it detects an error; other
wise 1 is returned.
DIAGNOSTICS
All error messages are directed to the TIFFError(3T) rou
tine.
Compression algorithm does not support random access.
Data was requested in a non-sequential order from a file
that uses a compression algorithm and that has RowsPer
Strip greater than one. That is, data in the image is
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
accessed sequentially, or the file should be converted so
that each strip is made up of one row of data.
BUGS
Reading subsampled YCbCR data does not work correctly
because, for PlanarConfiguration=2 the size of a scanline
is not calculated on a per-sample basis, and for
block-interleaved samples; use the strip- and tile-based
interfaces to read these formats.
SEE ALSO
libtiff(3T), TIFFOpen(3T), TIFFReadEncodedStrip(3T), TIFF
ReadRawStrip(3T)
Man(1) output converted with
man2html