src/tiff/man/TIFFWriteScanline.3tiff

   1 .\" $Id: TIFFWriteScanline.3tiff,v 1.2 2005/11/02 11:07:18 dron Exp $
   2 .\"
   3 .\" Copyright (c) 1988-1997 Sam Leffler
   4 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   5 .\"
   6 .\" Permission to use, copy, modify, distribute, and sell this software and
   7 .\" its documentation for any purpose is hereby granted without fee, provided
   8 .\" that (i) the above copyright notices and this permission notice appear in
   9 .\" all copies of the software and related documentation, and (ii) the names of
  10 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
  11 .\" publicity relating to the software without the specific, prior written
  12 .\" permission of Sam Leffler and Silicon Graphics.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  15 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  16 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  17 .\"
  18 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  19 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  20 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  21 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  22 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  23 .\" OF THIS SOFTWARE.
  24 .\"
  25 .if n .po 0
  26 .TH TIFFWriteScanline 3TIFF "December 16, 1991" "libtiff"
  27 .SH NAME
  28 TIFFWriteScanline \- write a scanline to an open
  29 .SM TIFF
  30 file
  31 .SH SYNOPSIS
  32 .B "#include <tiffio.h>"
  33 .sp
  34 .BI "int TIFFWriteScanline(TIFF *" tif ", tdata_t " buf ", uint32 " row ", tsample_t " sample ")"
  35 .SH DESCRIPTION
  36 Write data to a file at the specified row. The
  37 .I sample
  38 parameter is used only if data are organized in separate planes (\c
  39 .IR PlanarConfiguration =2).
  40 The data are assumed to be uncompressed and in the native bit- and byte-order
  41 of the host machine. The data written to the file is compressed according to
  42 the compression scheme of the current
  43 .SM TIFF
  44 directory (see further below). If the current scanline is past the end of the
  45 current subfile, the
  46 .I ImageLength
  47 field is automatically increased to include the scanline (except
  48 for
  49 .IR PlanarConfiguration =2,
  50 where the
  51 .I ImageLength
  52 cannot be changed once the first data are written). If the
  53 .I ImageLength
  54 is increased, the
  55 .I StripOffsets
  56 and
  57 .I StripByteCounts
  58 fields are similarly enlarged to reflect data written past the previous end of
  59 image.
  60 .SH NOTES
  61 The library writes encoded data using the native machine byte order. Correctly
  62 implemented
  63 .SM TIFF
  64 readers are expected to do any necessary byte-swapping to correctly process
  65 image data with BitsPerSample greater than 8. The library attempts to hide
  66 bit-ordering differences between the image and the native machine by
  67 converting data from the native machine order.
  68 .PP
  69 In C++ the
  70 .I sample
  71 parameter defaults to 0.
  72 .PP
  73 Once data are written to a file for the current directory, the values of
  74 certain tags may not be altered; see
  75 .IR TIFFSetField (3TIFF)
  76 for more information.
  77 .PP
  78 It is not possible to write scanlines to a file that uses a tiled
  79 organization.  The routine
  80 .IR TIFFIsTiled
  81 can be used to determine if the file is organized as tiles or strips.
  82 .SH "RETURN VALUES"
  83 .IR TIFFWriteScanline
  84 returns \-1 if it immediately detects an error and 1 for a successful write.
  85 .SH DIAGNOSTICS
  86 All error messages are directed to the
  87 .IR TIFFError (3TIFF)
  88 routine.
  89 .PP
  90 .BR "%s: File not open for writing .
  91 The file was opened for reading, not writing.
  92 .PP
  93 .BR "Can not write scanlines to a tiled image" .
  94 An attempt was made to write a scanline to a tiled image. The image is assumed
  95 to be organized in tiles because the
  96 .I TileWidth
  97 and
  98 .I TileLength
  99 tags have been set with
 100 .IR TIFFSetField (3TIFF).
 101 .PP
 102 .BR "Compression algorithm does not support random access" .
 103 Data was written in a non-sequential order to a file that uses a compression
 104 algorithm and that has
 105 .I RowsPerStrip
 106 greater than one. That is, data in the image is to be stored in a compressed
 107 form, and with multiple rows packed into a strip. In this case, the library
 108 does not support random access to the data. The data should either be written
 109 as entire strips, sequentially by rows, or the value of
 110 .I RowsPerStrip
 111 should be set to one.
 112 .PP
 113 \fB%s: Must set "ImageWidth" before writing data\fP.
 114 The image's width has not be set before the first write.
 115 See
 116 .BR TIFFSetField (3TIFF)
 117 for information on how to do this.
 118 .PP
 119 \fB%s: Must set "PlanarConfiguration" before writing data\fP.
 120 The organization of data has not be defined before the first write.
 121 See
 122 .BR TIFFSetField (3TIFF)
 123 for information on how to do this.
 124 .PP
 125 \fBCan not change "ImageLength" when using separate planes\fP. Separate image
 126 planes are being used (\c
 127 .IR PlanarConfiguration =2),
 128 but the number of rows has not been specified before the first write. The
 129 library supports the dynamic growth of an image only when data are organized
 130 in a contiguous manner (\c
 131 .IR PlanarConfiguration =1).
 132 .PP
 133 .BR "%d: Sample out of range, max %d" .
 134 The
 135 .I sample
 136 parameter was greater than the value of the SamplesPerPixel tag.
 137 .PP
 138 .BR "%s: No space for strip arrays .
 139 There was not enough space for the arrays that hold strip offsets and byte
 140 counts.
 141 .SH BUGS
 142 Writing subsampled YCbCR data does not work correctly because, for
 143 .IR PlanarConfiguration =2
 144 the size of a scanline is not calculated on a per-sample basis, and for
 145 .IR PlanarConfiguration =1
 146 the library does not pack the block-interleaved samples.
 147 .SH "SEE ALSO"
 148 .BR TIFFOpen (3TIFF),
 149 .BR TIFFWriteEncodedStrip (3TIFF),
 150 .BR TIFFWriteRawStrip (3TIFF),
 151 .BR libtiff (3TIFF)
 152 .PP
 153 Libtiff library home page:
 154 .BR http://www.remotesensing.org/libtiff/