src/tiff/man/TIFFtile.3tiff

   1 .\" $Id: TIFFtile.3tiff,v 1.2 2005-11-02 11:07:19 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 TIFFTILE 3TIFF "February 14, 1992" "libtiff"
  27 .SH NAME
  28 TIFFTileSize, TIFFTileRowSize, TIFFVTileSize, TIFFDefaultTileSize,
  29 TIFFComputeTile, TIFFCheckTile, TIFFNumberOfTiles \- tile-related utility
  30 routines
  31 .SH SYNOPSIS
  32 .B "#include <tiffio.h>"
  33 .sp
  34 .BI "void TIFFDefaultTileSize(TIFF *" tif ", uint32 *" tw ", uint32 *" th ")"
  35 .br
  36 .BI "tsize_t TIFFTileSize(TIFF *" tif ")"
  37 .br
  38 .BI "tsize_t TIFFTileRowSize(TIFF *" tif ")"
  39 .br
  40 .BI "tsize_t TIFFVTileSize(TIFF *" tif ", uint32 " nrows ")"
  41 .br
  42 .BI "ttile_t TIFFComputeTile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")"
  43 .br
  44 .BI "int TIFFCheckTile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")"
  45 .br
  46 .BI "ttile_t TIFFNumberOfTiles(TIFF *" tif ")"
  47 .br
  48 .SH DESCRIPTION
  49 .I TIFFDefaultTileSize
  50 returns the pixel width and height of a reasonable-sized tile; suitable for
  51 setting up the
  52 .I TileWidth
  53 and
  54 .I TileLength
  55 tags.
  56 If the
  57 .I tw
  58 and
  59 .I th
  60 values passed in are non-zero, then they are adjusted to reflect any
  61 compression-specific requirements. The returned width and height are
  62 constrained to be a multiple of 16 pixels to conform with the
  63 .SM TIFF
  64 specification.
  65 .PP
  66 .I TIFFTileSize
  67 returns the equivalent size for a tile of data as it would be returned in a
  68 call to
  69 .I TIFFReadTile
  70 or as it would be expected in a call to
  71 .IR TIFFWriteTile .
  72 .PP
  73 .I TIFFVTileSize
  74 returns the number of bytes in a row-aligned tile with
  75 .I nrows
  76 of data.
  77 .PP
  78 .I TIFFTileRowSize
  79 returns the number of bytes of a row of data in a tile.
  80 .PP
  81 .IR TIFFComputeTile
  82 returns the tile that contains the specified coordinates. A valid tile is
  83 always returned; out-of-range coordinate values are clamped to the bounds of
  84 the image. The
  85 .I x
  86 and
  87 .I y
  88 parameters are always used in calculating a tile. The
  89 .I z
  90 parameter is used if the image is deeper than 1 slice (\c
  91 .IR ImageDepth >1).
  92 The
  93 .I sample
  94 parameter is used only if data are organized in separate planes (\c
  95 .IR PlanarConfiguration =2).
  96 .PP
  97 .IR TIFFCheckTile
  98 returns a non-zero value if the supplied coordinates are within the bounds of
  99 the image and zero otherwise. The
 100 .I x
 101 parameter is checked against the value of the
 102 .I ImageWidth
 103 tag. The
 104 .I y
 105 parameter is checked against the value of the
 106 .I ImageLength
 107 tag. The
 108 .I z
 109 parameter is checked against the value of the
 110 .I ImageDepth
 111 tag (if defined). The
 112 .I sample
 113 parameter is checked against the value of the
 114 .I SamplesPerPixel
 115 parameter if the data are organized in separate planes.
 116 .PP
 117 .IR TIFFNumberOfTiles
 118 returns the number of tiles in the image.
 119 .SH DIAGNOSTICS
 120 None.
 121 .SH "SEE ALSO"
 122 .BR TIFFReadEncodedTile (3TIFF),
 123 .BR TIFFReadRawTile (3TIFF),
 124 .BR TIFFReadTile (3TIFF),
 125 .BR TIFFWriteEncodedTile (3TIFF),
 126 .BR TIFFWriteRawTile (3TIFF),
 127 .BR TIFFWriteTile (3TIFF),
 128 .BR libtiff (3TIFF)
 129 .PP
 130 Libtiff library home page:
 131 .BR http://www.remotesensing.org/libtiff/