NAME

       TIFFWriteScanline - write a scanline to an open TIFF file

SYNOPSIS

          #include <tiffio.h>

       int TIFFWriteScanline(TIFF *tif, tdata_t buf, uint32_t row, tsample_t sample)

DESCRIPTION

       Write  data  to a file at the specified row. The sample parameter is used only if data are
       organized in separate planes (PlanarConfiguration =  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  TIFF
       directory  (see  further  below).  If  the current scanline is past the end of the current
       subfile, the ImageLength field is automatically increased to include the scanline  (except
       for  PlanarConfiguration  = 2, where the ImageLength cannot be changed once the first data
       are written). If the ImageLength is increased, the StripOffsets and StripByteCounts fields
       are similarly enlarged to reflect data written past the previous end of image.

NOTES

       The  library  writes  encoded  data  using  the  native  machine  byte  order.   Correctly
       implemented TIFF 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.

       In C++ the sample parameter defaults to 0.

       Once  data are written to a file for the current directory, the values of certain tags may
       not be altered; see TIFFSetField() for more information.

       It is not possible to write scanlines to a file  that  uses  a  tiled  organization.   The
       routine  TIFFIsTiled()  can  be  used  to  determine  if the file is organized as tiles or
       strips.

RETURN VALUES

       TIFFWriteScanline() returns -1 if it immediately detects an error and 1 for  a  successful
       write.

DIAGNOSTICS

       All error messages are directed to the TIFFErrorExtR() routine.

       %s: File not open for writing:
          The file was opened for reading, not writing.

       "Can not write scanlines to a tiled image":
          An  attempt  was  made to write a scanline to a tiled image. The image is assumed to be
          organized in tiles because the  TileWidth  and  TileLength  tags  have  been  set  with
          TIFFSetField().

       "Compression algorithm does not support random access":
          Data  was written in a non-sequential order to a file that uses a compression algorithm
          and that has RowsPerStrip 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 RowsPerStrip should be set to
          one.

       %s: Must set "ImageWidth" before writing data:
          The image's width has not be set  before  the  first  write.   See  TIFFSetField()  for
          information on how to do this.

       %s: Must set "PlanarConfiguration" before writing data:
          The organization of data has not be defined before the first write.  See TIFFSetField()
          for information on how to do this.

       Can not change "ImageLength" when using separate planes:
          Separate image planes are being used (PlanarConfiguration = 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 (PlanarConfiguration  =
          1).

       "%d: Sample out of range, max %d":
          The sample parameter was greater than the value of the SamplesPerPixel tag.

       %s: No space for strip arrays:
          There was not enough space for the arrays that hold strip offsets and byte counts.

BUGS

       Writing 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
       PlanarConfiguration = 1 the library does not pack the block-interleaved samples.

SEE ALSO

       TIFFOpen   (3tiff),  TIFFWriteEncodedStrip  (3tiff),  TIFFWriteRawStrip  (3tiff),  libtiff
       (3tiff)

AUTHOR

       LibTIFF contributors

COPYRIGHT

       1988-2023, LibTIFF contributors