| 1 | .\" $Id: TIFFReadRGBATile.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 TIFFReadRGBATile 3TIFF "December 10, 1998" "libtiff" |
| 27 | .SH NAME |
| 28 | TIFFReadRGBATile \- read and decode an image tile into a fixed-format raster |
| 29 | .SH SYNOPSIS |
| 30 | .B "#include <tiffio.h>" |
| 31 | .sp |
| 32 | .B "#define TIFFGetR(abgr) ((abgr) & 0xff)" |
| 33 | .br |
| 34 | .B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)" |
| 35 | .br |
| 36 | .B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)" |
| 37 | .br |
| 38 | .B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)" |
| 39 | .sp |
| 40 | .BI "int TIFFReadRGBATile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 *" raster ")" |
| 41 | .SH DESCRIPTION |
| 42 | .IR TIFFReadRGBATile |
| 43 | reads a single tile of a tile-based image into memory, storing the result in |
| 44 | the user supplied RGBA |
| 45 | .IR raster . |
| 46 | The raster is assumed to be an array of width times length 32-bit entries, |
| 47 | where width is the width of a tile (TIFFTAG_TILEWIDTH) and length is the |
| 48 | height of a tile (TIFFTAG_TILELENGTH). |
| 49 | |
| 50 | .PP |
| 51 | The |
| 52 | .IR x |
| 53 | and |
| 54 | .IR y |
| 55 | values are the offsets from the top left corner to the top left corner of the |
| 56 | tile to be read. They must be an exact multiple of the tile width and length. |
| 57 | |
| 58 | .PP |
| 59 | Note that the raster is assume to be organized such that the pixel at location |
| 60 | (\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the |
| 61 | raster origin in the |
| 62 | .I lower-left hand corner |
| 63 | of the tile. That is bottom to top organization. Edge tiles which partly fall |
| 64 | off the image will be filled out with appropriate zeroed areas. |
| 65 | |
| 66 | .PP |
| 67 | Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros |
| 68 | .IR TIFFGetR , |
| 69 | .IR TIFFGetG , |
| 70 | .IR TIFFGetB , |
| 71 | and |
| 72 | .I TIFFGetA |
| 73 | should be used to access individual samples. Images without Associated Alpha |
| 74 | matting information have a constant Alpha of 1.0 (255). |
| 75 | .PP |
| 76 | See the |
| 77 | .IR TIFFRGBAImage (3TIFF) |
| 78 | page for more details on how various image types are converted to RGBA values. |
| 79 | .SH NOTES |
| 80 | Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must |
| 81 | be either 1, 3, or 4 (i.e. |
| 82 | .I SamplesPerPixel |
| 83 | minus |
| 84 | .IR ExtraSamples ). |
| 85 | .PP |
| 86 | Palette image colormaps that appear to be incorrectly written as 8-bit values |
| 87 | are automatically scaled to 16-bits. |
| 88 | .PP |
| 89 | .I TIFFReadRGBATile |
| 90 | is just a wrapper around the more general |
| 91 | .IR TIFFRGBAImage (3TIFF) |
| 92 | facilities. It's main advantage over the similar |
| 93 | .IR TIFFReadRGBAImage() |
| 94 | function is that for large images a single buffer capable of holding the whole |
| 95 | image doesn't need to be allocated, only enough for one tile. The |
| 96 | .IR TIFFReadRGBAStrip() |
| 97 | function does a similar operation for stripped images. |
| 98 | .SH "RETURN VALUES" |
| 99 | 1 is returned if the image was successfully read and converted. |
| 100 | Otherwise, 0 is returned if an error was encountered. |
| 101 | .SH DIAGNOSTICS |
| 102 | All error messages are directed to the |
| 103 | .IR TIFFError (3TIFF) |
| 104 | routine. |
| 105 | .PP |
| 106 | .BR "Sorry, can not handle %d-bit pictures" . |
| 107 | The image had |
| 108 | .I BitsPerSample |
| 109 | other than 1, 2, 4, 8, or 16. |
| 110 | .PP |
| 111 | .BR "Sorry, can not handle %d-channel images" . |
| 112 | The image had |
| 113 | .I SamplesPerPixel |
| 114 | other than 1, 3, or 4. |
| 115 | .PP |
| 116 | \fBMissing needed "PhotometricInterpretation" tag\fP. |
| 117 | The image did not have a tag that describes how to display the data. |
| 118 | .PP |
| 119 | \fBNo "PhotometricInterpretation" tag, assuming RGB\fP. |
| 120 | The image was missing a tag that describes how to display it, but because it |
| 121 | has 3 or 4 samples/pixel, it is assumed to be |
| 122 | .SM RGB. |
| 123 | .PP |
| 124 | \fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. |
| 125 | The image was missing a tag that describes how to display it, |
| 126 | but because it has 1 sample/pixel, it is assumed to be a grayscale |
| 127 | or bilevel image. |
| 128 | .PP |
| 129 | .BR "No space for photometric conversion table" . |
| 130 | There was insufficient memory for a table used to convert |
| 131 | image samples to 8-bit |
| 132 | .SM RGB. |
| 133 | .PP |
| 134 | \fBMissing required "Colormap" tag\fP. |
| 135 | A Palette image did not have a required |
| 136 | .I Colormap |
| 137 | tag. |
| 138 | .PP |
| 139 | .BR "No space for tile buffer" . |
| 140 | There was insufficient memory to allocate an i/o buffer. |
| 141 | .PP |
| 142 | .BR "No space for strip buffer" . |
| 143 | There was insufficient memory to allocate an i/o buffer. |
| 144 | .PP |
| 145 | .BR "Can not handle format" . |
| 146 | The image has a format (combination of |
| 147 | .IR BitsPerSample , |
| 148 | .IR SamplesPerPixel , |
| 149 | and |
| 150 | .IR PhotometricInterpretation ) |
| 151 | that |
| 152 | .I TIFFReadRGBAImage |
| 153 | can not handle. |
| 154 | .PP |
| 155 | .BR "No space for B&W mapping table" . |
| 156 | There was insufficient memory to allocate a table used to map |
| 157 | grayscale data to |
| 158 | .SM RGB. |
| 159 | .PP |
| 160 | .BR "No space for Palette mapping table" . |
| 161 | There was insufficient memory to allocate a table used to map data to 8-bit |
| 162 | .SM RGB. |
| 163 | .SH "SEE ALSO" |
| 164 | .BR TIFFOpen (3TIFF), |
| 165 | .BR TIFFRGBAImage (3TIFF), |
| 166 | .BR TIFFReadRGBAImage (3TIFF), |
| 167 | .BR TIFFReadRGBAStrip (3TIFF), |
| 168 | .BR libtiff (3TIFF) |
| 169 | .PP |
| 170 | Libtiff library home page: |
| 171 | .BR http://www.remotesensing.org/libtiff/ |