src/tiff/man/TIFFRGBAImage.3tiff

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