src/tiff/man/TIFFRGBAImage.3tiff

   1 .\"
   2 .\" Copyright (c) 1991-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 TIFFRGBAImage 3TIFF "October 29, 2004" "libtiff"
  26 .SH NAME
  27 TIFFRGBAImageOK, TIFFRGBAImageBegin, TIFFRGBAImageGet, TIFFRGBAImageEnd
  28 \- read and decode an image into a raster
  29 .SH SYNOPSIS
  30 .B "#include <tiffio.h>"
  31 .sp
  32 .B "typedef unsigned char TIFFRGBValue;"
  33 .B "typedef struct _TIFFRGBAImage TIFFRGBAImage;"
  34 .sp
  35 .BI "int TIFFRGBAImageOK(TIFF *" tif ", char " emsg[1024] ")"
  36 .br
  37 .BI "int TIFFRGBAImageBegin(TIFFRGBAImage *" img ", TIFF* " tif ", int " stopOnError ", char " emsg[1024] ")"
  38 .br
  39 .BI "int TIFFRGBAImageGet(TIFFRGBAImage *" img ", uint32* " raster ", uint32 " width " , uint32 " height ")"
  40 .br
  41 .BI "void TIFFRGBAImageEnd(TIFFRGBAImage *" img ")"
  42 .br
  43 .SH DESCRIPTION
  44 The routines described here provide a high-level interface
  45 through which
  46 .SM TIFF
  47 images may be read into memory.
  48 Images may be strip- or tile-based and have a variety of different
  49 characteristics: bits/sample, samples/pixel, photometric, etc.
  50 Decoding state is encapsulated in a
  51 .I TIFFRGBAImage
  52 structure making it possible to capture state for multiple images
  53 and quickly switch between them.
  54 The target raster format can be customized to a particular application's
  55 needs by installing custom routines that manipulate image data
  56 according to application requirements.
  57 .PP
  58 The default usage for these routines is: check if an image can
  59 be processed using
  60 .IR TIFFRGBAImageOK ,
  61 construct a decoder state block using
  62 .IR TIFFRGBAImageBegin ,
  63 read and decode an image into a target raster using
  64 .IR TIFFRGBAImageGet ,
  65 and then
  66 release resources using
  67 .IR TIFFRGBAImageEnd .
  68 .I TIFFRGBAImageGet
  69 can be called multiple times to decode an image using different
  70 state parameters.
  71 If multiple images are to be displayed and there is not enough
  72 space for each of the decoded rasters, multiple state blocks can
  73 be managed and then calls can be made to
  74 .I TIFFRGBAImageGet
  75 as needed to display an image.
  76 .PP
  77 The generated raster is assumed to be an array of
  78 .I width
  79 times
  80 .I height
  81 32-bit entries, where
  82 .I width
  83 must be less than or equal to the width of the image (\c
  84 .I height
  85 may be any non-zero size).
  86 If the raster dimensions are smaller than the image, the image data
  87 is cropped to the raster bounds.
  88 If the raster height is greater than that of the image, then the
  89 image data are placed in the lower part of the raster.
  90 (Note that the raster is assume to be organized such that the pixel
  91 at location (\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP];
  92 with the raster origin in the
  93 .B lower-left
  94 hand corner.)
  95 .PP
  96 Raster pixels are 8-bit packed red, green, blue, alpha samples.
  97 The macros
  98 .IR TIFFGetR ,
  99 .IR TIFFGetG ,
 100 .IR TIFFGetB ,
 101 and
 102 .I TIFFGetA
 103 should be used to access individual samples.
 104 Images without Associated Alpha matting information have a constant
 105 Alpha of 1.0 (255).
 106 .PP
 107 .I TIFFRGBAImageGet
 108 converts non-8-bit images by scaling sample values.
 109 Palette, grayscale, bilevel,
 110 .SM CMYK\c
 111 , and YCbCr images are converted to
 112 .SM RGB
 113 transparently.
 114 Raster pixels are returned uncorrected by any colorimetry information
 115 present in the directory.
 116 .PP
 117 The parameter
 118 .I stopOnError
 119 specifies how to act if an error is encountered while reading
 120 the image.
 121 If
 122 .I stopOnError
 123 is non-zero, then an error will terminate the operation; otherwise
 124 .I TIFFRGBAImageGet
 125 will continue processing data until all the possible data in the
 126 image have been requested.
 127 .SH "ALTERNATE RASTER FORMATS"
 128 To use the core support for reading and processing
 129 .SM TIFF
 130 images, but write the resulting raster data in a different format
 131 one need only override the ``\fIput methods\fP'' used to store raster data.
 132 These methods are are defined in the
 133 .I TIFFRGBAImage
 134 structure and initially setup by
 135 .I TIFFRGBAImageBegin
 136 to point to routines that pack raster data in the default
 137 .SM ABGR
 138 pixel format.
 139 Two different routines are used according to the physical organization
 140 of the image data in the file:
 141 .IR PlanarConfiguration =1
 142 (packed samples),
 143 and
 144 .IR PlanarConfiguration =2
 145 (separated samples).
 146 Note that this mechanism can be used to transform the data before
 147 storing it in the raster.
 148 For example one can convert data
 149 to colormap indices for display on a colormap display.
 150 .SH "SIMULTANEOUS RASTER STORE AND DISPLAY"
 151 It is simple to display an image as it is being read into memory
 152 by overriding the put methods as described above for supporting
 153 alternate raster formats.
 154 Simply keep a reference to the default put methods setup by
 155 .I TIFFRGBAImageBegin
 156 and then invoke them before or after each display operation.
 157 For example, the
 158 .IR tiffgt (1)
 159 utility uses the following put method to update the display as
 160 the raster is being filled:
 161 .sp
 162 .nf
 163 .ft C
 164 static void
 165 putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
 166     uint32 x, uint32 y, uint32 w, uint32 h,
 167     int32 fromskew, int32 toskew,
 168     unsigned char* cp)
 169 {
 170     (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
 171     if (x+w == width) {
 172         w = width;
 173         if (img->orientation == ORIENTATION_TOPLEFT)
 174             lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
 175         else
 176             lrectwrite(0, y, w-1, y+h-1, raster);
 177     }
 178 }
 179 .ft R
 180 .fi
 181 .sp
 182 (the original routine provided by the library is saved in the
 183 variable
 184 .IR putContig .)
 185 .SH "SUPPORTING ADDITIONAL TIFF FORMATS"
 186 The
 187 .I TIFFRGBAImage
 188 routines support the most commonly encountered flavors of
 189 .SM TIFF.
 190 It is possible to extend this support by overriding the ``\fIget method\fP''
 191 invoked by
 192 .I TIFFRGBAImageGet
 193 to read
 194 .SM TIFF
 195 image data.
 196 Details of doing this are a bit involved, it is best to make a copy
 197 of an existing get method and modify it to suit the needs of an
 198 application.
 199 .SH NOTES
 200 Samples must be either 1, 2, 4, 8, or 16 bits.
 201 Colorimetric samples/pixel must be either 1, 3, or 4 (i.e.
 202 .I SamplesPerPixel
 203 minus
 204 .IR ExtraSamples ).
 205 .PP
 206 Palette image colormaps that appear to be incorrectly written
 207 as 8-bit values are automatically scaled to 16-bits.
 208 .SH "RETURN VALUES"
 209 All routines return
 210 1 if the operation was successful.
 211 Otherwise, 0 is returned if an error was encountered and
 212 .I stopOnError
 213 is zero.
 214 .SH DIAGNOSTICS
 215 All error messages are directed to the
 216 .IR TIFFError (3TIFF)
 217 routine.
 218 .PP
 219 .BR "Sorry, can not handle %d-bit pictures" .
 220 The image had
 221 .I BitsPerSample
 222 other than 1, 2, 4, 8, or 16.
 223 .PP
 224 .BR "Sorry, can not handle %d-channel images" .
 225 The image had
 226 .I SamplesPerPixel
 227 other than 1, 3, or 4.
 228 .PP
 229 \fBMissing needed "PhotometricInterpretation" tag\fP.
 230 The image did not have a tag that describes how to display
 231 the data.
 232 .PP
 233 \fBNo "PhotometricInterpretation" tag, assuming RGB\fP.
 234 The image was missing a tag that describes how to display it,
 235 but because it has 3 or 4 samples/pixel, it is assumed to be
 236 .SM RGB.
 237 .PP
 238 \fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP.
 239 The image was missing a tag that describes how to display it,
 240 but because it has 1 sample/pixel, it is assumed to be a grayscale
 241 or bilevel image.
 242 .PP
 243 .BR "No space for photometric conversion table" .
 244 There was insufficient memory for a table used to convert
 245 image samples to 8-bit
 246 .SM RGB.
 247 .PP
 248 \fBMissing required "Colormap" tag\fP.
 249 A Palette image did not have a required
 250 .I Colormap
 251 tag.
 252 .PP
 253 .BR "No space for tile buffer" .
 254 There was insufficient memory to allocate an i/o buffer.
 255 .PP
 256 .BR "No space for strip buffer" .
 257 There was insufficient memory to allocate an i/o buffer.
 258 .PP
 259 .BR "Can not handle format" .
 260 The image has a format (combination of
 261 .IR BitsPerSample ,
 262 .IR SamplesPerPixel ,
 263 and
 264 .IR PhotometricInterpretation )
 265 that can not be handled.
 266 .PP
 267 .BR "No space for B&W mapping table" .
 268 There was insufficient memory to allocate a table used to map
 269 grayscale data to
 270 .SM RGB.
 271 .PP
 272 .BR "No space for Palette mapping table" .
 273 There was insufficient memory to allocate a table used to map
 274 data to 8-bit
 275 .SM RGB.
 276 .SH "SEE ALSO"
 277 .BR TIFFOpen (3TIFF),
 278 .BR TIFFReadRGBAImage (3TIFF),
 279 .BR TIFFReadRGBAImageOriented (3TIFF),
 280 .BR TIFFReadRGBAStrip (3TIFF),
 281 .BR TIFFReadRGBATile (3TIFF),
 282 .BR libtiff (3TIFF)
 283 .PP
 284 Libtiff library home page:
 285 .BR http://www.remotesensing.org/libtiff/