| | 1 | .\" |
| | 2 | .\" Copyright (c) 1988-1997 Sam Leffler |
| | 3 | .\" Copyright (c) 1991-1997 Silicon Graphics, Inc. |
| | 4 | .\" |
| | 5 | .\" Permission to use, copy, modify, distribute, and sell this software and |
| | 6 | .\" its documentation for any purpose is hereby granted without fee, provided |
| | 7 | .\" that (i) the above copyright notices and this permission notice appear in |
| | 8 | .\" all copies of the software and related documentation, and (ii) the names of |
| | 9 | .\" Sam Leffler and Silicon Graphics may not be used in any advertising or |
| | 10 | .\" publicity relating to the software without the specific, prior written |
| | 11 | .\" permission of Sam Leffler and Silicon Graphics. |
| | 12 | .\" |
| | 13 | .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, |
| | 14 | .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY |
| | 15 | .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |
| | 16 | .\" |
| | 17 | .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR |
| | 18 | .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, |
| | 19 | .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, |
| | 20 | .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF |
| | 21 | .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE |
| | 22 | .\" OF THIS SOFTWARE. |
| | 23 | .\" |
| | 24 | .if n .po 0 |
| | 25 | .TH TIFFReadScanline 3TIFF "October 15, 1995" "libtiff" |
| | 26 | .SH NAME |
| | 27 | TIFFReadScanline \- read and decode a scanline of data from an open |
| | 28 | .SM TIFF |
| | 29 | file |
| | 30 | .SH SYNOPSIS |
| | 31 | .B "#include <tiffio.h>" |
| | 32 | .sp |
| | 33 | .BI "int TIFFReadScanline(TIFF *" tif ", tdata_t " buf ", uint32 " row ", tsample_t " sample ")" |
| | 34 | .SH DESCRIPTION |
| | 35 | Read the data for the specified row into the (user supplied) data buffer |
| | 36 | .IR buf . |
| | 37 | The data are returned decompressed and, in the native byte- and bit-ordering, |
| | 38 | but are otherwise packed (see further below). The buffer must be large enough |
| | 39 | to hold an entire scanline of data. Applications should call the routine |
| | 40 | .IR TIFFScanlineSize |
| | 41 | to find out the size (in bytes) of a scanline buffer. |
| | 42 | The |
| | 43 | .I row |
| | 44 | parameter is always used by |
| | 45 | .IR TIFFReadScanline ; |
| | 46 | the |
| | 47 | .I sample |
| | 48 | parameter is used only if data are organized in separate planes (\c |
| | 49 | .IR PlanarConfiguration =2). |
| | 50 | .SH NOTES |
| | 51 | The library attempts to hide bit- and byte-ordering differences between the |
| | 52 | image and the native machine by converting data to the native machine order. |
| | 53 | Bit reversal is done if the |
| | 54 | .I FillOrder |
| | 55 | tag is opposite to the native machine bit order. 16- and 32-bit samples are |
| | 56 | automatically byte-swapped if the file was written with a byte order opposite |
| | 57 | to the native machine byte order, |
| | 58 | .PP |
| | 59 | In C++ the |
| | 60 | .I sample |
| | 61 | parameter defaults to 0. |
| | 62 | .SH "RETURN VALUES" |
| | 63 | .IR TIFFReadScanline |
| | 64 | returns \-1 if it detects an error; otherwise 1 is returned. |
| | 65 | .SH DIAGNOSTICS |
| | 66 | All error messages are directed to the |
| | 67 | .IR TIFFError (3TIFF) |
| | 68 | routine. |
| | 69 | .PP |
| | 70 | .BR "Compression algorithm does not support random access" . |
| | 71 | Data was requested in a non-sequential order from a file that uses a |
| | 72 | compression algorithm and that has |
| | 73 | .I RowsPerStrip |
| | 74 | greater than one. |
| | 75 | That is, data in the image is stored in a compressed form, and with multiple |
| | 76 | rows packed into a strip. In this case, the library does not support random |
| | 77 | access to the data. The data should either be accessed sequentially, or the |
| | 78 | file should be converted so that each strip is made up of one row of data. |
| | 79 | .SH BUGS |
| | 80 | Reading subsampled YCbCR data does not work correctly because, for |
| | 81 | .IR PlanarConfiguration =2 |
| | 82 | the size of a scanline is not calculated on a per-sample basis, and for |
| | 83 | .IR PlanarConfiguration =1 |
| | 84 | the library does not unpack the block-interleaved samples; use the strip- and |
| | 85 | tile-based interfaces to read these formats. |
| | 86 | .SH "SEE ALSO" |
| | 87 | .BR TIFFOpen (3TIFF), |
| | 88 | .BR TIFFReadEncodedStrip (3TIFF), |
| | 89 | .BR TIFFReadRawStrip (3TIFF), |
| | 90 | .BR libtiff (3TIFF) |
| | 91 | .PP |
| | 92 | Libtiff library home page: |
| | 93 | .BR http://www.remotesensing.org/libtiff/ |
projects / wxWidgets.git / blame_incremental