home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0040 - 0049 / ibm0040-0049 / ibm0040.tar / ibm0040 / IMGPROC.ZIP / C6TIFF.ZIP / TIFFINFO.DOC < prev    next >
Encoding:
Text File  |  1990-04-06  |  8.8 KB  |  173 lines
  1.         Copyright 1990 by John Wiley & Sons, Inc.
  2.         All Rights Reserved.
  3.  
  4.                              TIFF Library Functions
  5.         
  6.         DESCRIPTION
  7.         
  8.              This  file format is suitable for archiving multi-color  and 
  9.         monochromatic image data. Directory information may be in  either 
  10.         little- or big-endian byte order. Byte swapping is  automatically 
  11.         done by the library. Data may not have more than four samples per 
  12.         pixel.  Finally, the library does not support files in which  the 
  13.         BitsPerSample,  Compression,  MinSampleValue  or   MaxSampleValue 
  14.         fields are defined differently on a per-sample basis (in Rev. 5.0 
  15.         the Compression tag is not defined on a per-sample basis, so this 
  16.         is immaterial).
  17.         
  18.         Function Summary
  19.         
  20.              This section gives a brief summary of the functions included 
  21.         in the library. For more detail see the code.
  22.         
  23.         TIFF *TIFFOpen(filename, mode)
  24.         
  25.              Open a TIFF file whose name is filename and return a  handle 
  26.         to  be used in subsequent calls to functions in libtiff  (if  the 
  27.         operation  fails,  then  a null handle  is  returned).  The  mode 
  28.         parameter  specifies if the file is to be opened for reading  "r" 
  29.         or   writing "w". If an existing file is opened for writing,  all 
  30.         previous data is overwritten.
  31.         
  32.              If a file is opened for reading, the first TIFF directory in 
  33.         the  file  is  automatically read (also  see  below  for  reading 
  34.         directories  other  than  the first). If a  file  is  opened  for 
  35.         writing, a default directory is automatically created for writing 
  36.         subsequent  data.  This  directory has  all  the  default  values 
  37.         specified in TIFF Revision 5.0: 
  38.         
  39.         a.   BitsPerSample =1,
  40.         b.   ThreshHolding "=bilevel art scan,"
  41.         c.   FillOrder  =1  (most significant bit of  the  byte  are 
  42.              filled first),
  43.         d.   Orientation  =1 (the 0th row represents the visual  top 
  44.              of the image, and the 0th column represents the  visual 
  45.              left hand side),
  46.         e.   SamplesPerPixel =1,
  47.         f.   RowsPerStrip =infinity,
  48.         g.   GrayResponseUnit =2 (hundredths of a unit),
  49.         h.   ColorResponseUnit =2 (hundredths of a unit),
  50.         i.   ResolutionUnit =2 (inches), and
  51.         j.   Compression =1 (no compression).
  52.         
  53.         To alter these values, or to define values for additional fields, 
  54.         the "TIFFSetField" function must be used.
  55.  
  56.         void TIFFClose(tif)
  57.         
  58.              Close a file previously opened with "TIFFOpen". Any buffered 
  59.         data  is  flushed  to the file, including  the  contents  of  the 
  60.         current directory (if modified) and all resources are reclaimed.
  61.         
  62.         CompletionCode TIFFSetField(tif, tag, va_alist)
  63.         
  64.              Set the value of a field in the current directory associated 
  65.         with  tif.  The  field is identified by tag, one  of  the  values 
  66.         defined  in  the  include  file "tiff.h".  The  actual  value  is 
  67.         specified  using a variable argument list, as prescribed  by  the 
  68.         varargs  interface.  TRUE  is  returned  if  the  operation   was 
  69.         successful, FALSE if an error was detected.
  70.         
  71.         CompletionCode TIFFGetField(tif, tag, va_alist)
  72.         
  73.              Return  the  value  of the field in  the  current  directory 
  74.         associated  with tif. If the field is not recognized, or  is  not 
  75.         defined,  then a FALSE is returned. Otherwise, TRUE  is  returned 
  76.         and  the  value  associated with the field is  returned  in  data 
  77.         area(s) supplied in the variable argument list.
  78.         
  79.         CompletionCode TIFFReadDirectory(tif)
  80.         
  81.              Read  the next directory in the specified file and  make  it 
  82.         the  current  directory.  If  the  current  directory  has   been 
  83.         modified,  and the file is opened for writing, first the  current 
  84.         directory is written out. "TIFFReadDirectory" returns TRUE if the 
  85.         next  directory  was  successfully  read.  Otherwise,  FALSE   is 
  86.         returned  if  an error was encountered, or if there are  no  more 
  87.         directories   to  be  read.  Applications  only  need   to   call 
  88.         "TIFFReadDirectory"  to read multiple subfiles in a  single  TIFF 
  89.         file.  Normally  the first directory in a file  is  automatically 
  90.         read when "TIFFOpen" is called.
  91.         
  92.         CompletionCode TIFFWriteDirectory(tif)
  93.         
  94.              Write the contents of the current directory to the file  and 
  95.         setup to create a new subfile in the same file. Applications only 
  96.         need to call "TIFFWriteDirectory" when writing multiple  subfiles 
  97.         to  a  single TIFF file.  "TIFFWriteDirectory"  is  automatically 
  98.         called  by "TIFFClose" to write a modified directory if the  file 
  99.         is open for writing.
  100.         
  101.         CompletionCode TIFFSetDirectory(tif, dirnum)
  102.         
  103.              Seek   to  a  specific  directory  in  file  and  read   the 
  104.         directory's  contents  with  "TIFFReadDirectory".  The  parameter 
  105.         dirnum specifies the subfile/directory as an integer number, with
  106.              the first directory numbered zero. 
  107.         
  108.         CompletionCode TIFFScanlineSize(tif)
  109.  
  110.              Return  the size (in bytes) of a row of data that  would  be 
  111.         returned  in  a  call to "TIFFReadScanline",  or  that  would  be 
  112.         expected in a call to "TIFFWriteScanline". This size is typically 
  113.         used when dynamically allocating I/O buffers.
  114.         
  115.         CompletionCode TIFFReadScanline(tif, buf, row, sample)
  116.         
  117.              Return  the  data for the specified row in the  data  buffer 
  118.         buf. The data is returned decompressed but otherwise packed.  The 
  119.         buffer  must be large enough to hold an entire scanline of  data. 
  120.         Applications should call the function "TIFFScanlineSize" to  find 
  121.         out  the size (in bytes) of a scanline buffer. The row  parameter 
  122.         is  always  used by "TIFFReadScanline". The sample  parameter  is 
  123.         used   only   if   data   is   organized   in   separate   planes 
  124.         (PlanarConfiguration =2). "TIFFReadScanline" returns FALSE if  it 
  125.         detects an error; otherwise TRUE is returned.
  126.         
  127.         CompletionCode TIFFWriteScanline(tif, buf, row, sample)
  128.         
  129.              Write  data  to  a file at the  specified  row.  The  sample 
  130.         parameter  is used only if data is organized in  separate  planes 
  131.         (PlanarConfiguration  = 2). The data is compressed  according  to 
  132.         the   compression   scheme  of  the   current   TIFF   directory. 
  133.         TIFFWriteScanline  returns FALSE if it detects an error and  TRUE 
  134.         for  a successful write. If the current scanline is past the  end 
  135.         of  the current subfile, the ImageLength field  is  automatically 
  136.         increased to include the scanline (except for PlanarConfiguration 
  137.         = 2, where the ImageLength can not be changed once the first data 
  138.         is  written). If the ImageLength is increased,  the  StripOffsets 
  139.         and StripByteCounts fields are similarly enlarged to reflect data 
  140.         written past the previous end of image.
  141.         
  142.         CompletionCode TIFFFlush(tif)
  143.         
  144.              Flush  any pending writes for the specified file  (including 
  145.         writes for the current directory). FALSE is returned if an  error 
  146.         is encountered, otherwise TRUE. In normal operation this call  is 
  147.         never   needed  the  library  automatically  does  any   flushing 
  148.         required.
  149.         
  150.         CompletionCode TIFFFlushData(tif)
  151.         
  152.              Flush any pending data writes for the specified file.  FALSE 
  153.         is returned if an error is encountered, otherwise TRUE. In normal 
  154.         operation  this  call is never needed the  library  automatically 
  155.         does any flushing required.
  156.         
  157.         void TIFFError(module, fmt, arguments)
  158.         
  159.              Write  an  error message to stderr. The fmt parameter  is  a 
  160.         printf  format  string,  and  any  number  of  arguments  can  be 
  161.         supplied.  The module parameter is interpreted as a string  that, 
  162.         if  non-zero, should be printed before the message; it  typically 
  163.         is  used  to identify the software module in which  an  error  is 
  164.         detected.
  165.         
  166.         void TIFFWarning(module, fmt, arguments)
  167.         
  168.              Write  an warning message to the stderr. The parameters  are 
  169.         treated as described above under "TIFFError".
  170.  
  171.  
  172.  
  173.