


IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



NAME
     ImFileRead, ImFileFRead - Read an image format input  stream
     into a Vfb
     ImFileWrite, ImFileFWrite - Write a Vfb onto an image format
     output stream

SYNOPSIS
     #include "im.h"

     int ImFileRead( fd, format, flagsTable, dataTable )
          int fd;
          char *format;
          TagTable *flagsTable;
          TagTable *dataTable;

     int ImFileFRead( fp, format, flagsTable, dataTable )
          FILE *fp;
          char *format;
          TagTable *flagsTable;
          TagTable *dataTable;

     int ImFileWrite( fd, format, flagsTable, dataTable )
          int fd;
          char *format;
          TagTable *flagsTable;
          TagTable *dataTable;

     int ImFileFWrite( fp, format, flagsTable, dataTable )
          FILE *fp;
          char *format;
          TagTable *flagsTable;
          TagTable *dataTable;


DESCRIPTION
     ImFileRead and ImFileFRead read image data  of  type  _f_o_r_m_a_t
     from  the  input  stream selected by _f_d or _f_p, respectively.
     Format-specific flags in _f_l_a_g_s_T_a_b_l_e may modify the  behavior
     of  the  read  operation.   Data  read  from  the  stream is
     appended to _d_a_t_a_T_a_b_l_e.

     ImFileWrite and ImFileFWrite write image data of type _f_o_r_m_a_t
     onto  the  output stream selected by _f_d or _f_p, respectively.
     Format-specific flags in _f_l_a_g_s_T_a_b_l_e may modify the  behavior
     of  the  write  operation.   Data to write is taken from the
     _d_a_t_a_T_a_b_l_e.

NOTES
     The image file I/O routines handle the input and  output  of
     image  data  in  a  variety of image file formats.  Read and
     write routines read or write using file descriptors  (unbuf-
     fered  I/O)  or  file pointers (buffered I/O), allowing both



SDSC              Last change: August 25, 1992                  1






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



     files and pipes to be handled identically.

  Image Formats
     Format names are NULL-terminated  character  strings  giving
     the  name,  or any of the equivalent names for any supported
     image file format.  The list of image file formats supported
     is  ever-growing.   As  of  this  writing,  the  format list
     includes the following:

          Primary   Equivalent
          Name      Names           Description
8          _____________________________________________________________________
          bmp       bmp             Microsoft Windows BitMaP file
          cur       cur             Microsoft Windows CURsor file
          gif       giff            CompuServe Graphics Image Format file
          hdf       df, ncsa        Hierarchical Data Format file
          ico       ico             Microsoft Windows ICOn file
          icon      cursor, pr      Sun Icon and Cursor file
          iff       suniff, taac    Sun TAAC Image File Format
          mpnt      macp, pntg      Apple Macintosh MacPaint file
          pbm       -               Portable Bit Map file
          pcx       pcc             ZSoft PC Paintbrush file
          pgm       -               Portable Grayscale Map file
          pic       picio, pixar    PIXAR PICture file
          pict      pict2           Apple Macintosh QuickDraw/PICT picture file
          pix       alias           Alias PIXel image file
          pnm       -               Portable aNy Map file
          ppm       -               Portable Pixel Map file
          ps        postscript      PostScript image file
          ras       sun, sr, scr    Sun RASterfile
          rgb       iris, sgi       Silicon Graphics RGB image file
          rla       rlb             Wavefront raster image file
          rle       -               Utah Run-Length-Encoded image file
          rpbm      -               Raw Portable Bit Map file
          rpgm      -               Raw Portable Grayscale Map file
          rpnm      -               Raw Portable aNy Map file
          rppm      -               Raw Portable Pixel Map file
          synu      -               Synu image file
          tga       tga, vda, ivb   Truevision Targa image file
          tiff      tif             Tagged Image File
          viff      viff, xv        Khoros Visualization Image File Format
          x         avs             Stardent AVS X image file
          xbm       bm              X11 Bit Map file
          xwd       x11             X11 Window Dump image file

     For a current list of image format names  supported  by  the
     library,  execute  the  imformats(1IM)  command, or scan the
     global ImFileFormats table of format information.

     Individual man pages are available for  each  of  the  above
     file formats.  The naming convention is primary name with _i_m
     prefix.  For instance, the man page on image library support
     of the Sun RASterfile format is imras(3IM).



2                 Last change: August 25, 1992               SDSC


9


IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



  Data Tag Table Entries
     Image file data read in  by  ImFileRead  or  ImFileFRead  is
     appended  to  the  _d_a_t_a_T_a_b_l_e  in  the  order  in which it is
     encountered in the file.  Each piece of information is given
     its own table entry and tagged with a standard or custom tag
     name.  Standard tags  are  given  below.   Custom  tags  are
     format-specific  and  are discussed in the individual format
     man pages.

     Data written by ImFileWrite or ImFileFWrite  is  written  in
     the  same order as tags encountered in the _d_a_t_a_T_a_b_l_e.  Table
     entries with tags applicable to the format are  used,  while
     the rest are ignored.

     The following standard _d_a_t_a_T_a_b_l_e tags are recognized by most
     file format read and write handlers:


     image vfb
          ImVfb pointer to an image.

          When reading multi-image files, each image is given its
          own  entry  in  the _d_a_t_a_T_a_b_l_e, in the same order as the
          images occur in the file.

          When writing multi-image _d_a_t_a_T_a_b_l_es, images are written
          to  the  file  in  the  same order as they occur in the
          _d_a_t_a_T_a_b_l_e.  If the format  does  not  support  multiple
          images  per  file,  the format handler returns an error
          and does not write the file.

     image clt
          ImClt pointer to a color lookup table.

          When reading a color lookup table (CLT) and image  from
          a  file,  both  the CLT and the image are listed in the
          _d_a_t_a_T_a_b_l_e; the CLT first and the image second.   If  it
          is  clear  from the format's specification that the CLT
          is to be associated with the image,  the  CLT  also  is
          attached  to  the  image  virtual  frame  buffer  using
          ImVfbSClt(3IM).

          When reading multi-image files, the CLT  (if  any)  for
          each  image  immediately precedes the image when placed
          into the _d_a_t_a_T_a_b_l_e.

          When writing a CLT and image from a _d_a_t_a_T_a_b_l_e, the  CLT
          (if any) associated with the image virtual frame buffer
          takes precedence over any in the _d_a_t_a_T_a_b_l_e.  image  clt
          tags are ignored.





SDSC              Last change: August 25, 1992                  3






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



  Format Flags
     The _f_l_a_g_s_T_a_b_l_e argument on read and write calls may  contain
     flags  that  select  format-specific  options.  A _f_l_a_g_s_T_a_b_l_e
     flag may request a particular image compression scheme,  may
     block  output  of an image's CLT, may request that the image
     be output without its alpha channel,  and  so  on.   In  all
     cases,  _f_l_a_g_s_T_a_b_l_e entries direct format output handlers how
     to output information.  What to output is the domain of  the
     _d_a_t_a_T_a_b_l_e.

     A NULL pointer for the _f_l_a_g_s_T_a_b_l_e  indicates  no  flags  are
     provided.

     Standard _f_l_a_g_s_T_a_b_l_e tags are given  below.   Custom  format-
     specific  tags  are  discussed  in the individual format man
     pages.  Examples and interdependency explanations follow  in
     later sections of this man page.


     error handler
          Integer function pointer for the function to be  called
          and passed an error message.  If not given, there is no
          error handler.

          See below for usage of the error handler.

     error stream
          FILE pointer for the stream  to  which  error  messages
          should  be output, such as stderr.  If not given, there
          is no error stream.  See below for usage of  the  error
          stream.

     file name
          Character string name of the input or output file.   If
          not given, the file name defaults to file.  If input or
          output is to a stream instead of a  file,  the  strings
          stdin or stdout should be used.

          File name is used when constructing error message  text
          to  be  printed  to  the error stream and passed to the
          error handler (see below).  File name has no other sig-
          nificance and is not opened directly.

     image alpha request
          Integer flag to block or force an  alpha  plane  to  be
          output.   If not given, an alpha plane is output if the
          image has one and the format can support  it.   If  the
          tag  forces output when a file format cannot support it
          or blocks output when a format must have it,  an  error
          is returned.

          This tag is only used by image write handlers.  A value



4                 Last change: August 25, 1992               SDSC






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



          of  IMALPHADUMP  forces alpha plane output.  A value of
          IMALPHANODUMP blocks output.

     image channel number request
          Integer number of image channels  to  output.   If  not
          given, each channel in each incoming image is output or
          the closest number supported by the output file format.
          If  this tag specifies a number of channels that cannot
          be supported by the image  file  format,  an  error  is
          returned.

          This tag is only used by image write handlers.

          Channel numbers are typically 1 or  3.   Channel  image
          number  1  corresponds  to  a monochrome, grayscale, or
          color index image where 1 integer per pixel is  stored.
          Channel  image  number  3  corresponds to an RGB image.
          Note that  an  alpha  channel  for  the  image  is  not
          included.   See  the separate tag "image alpha request"
          for control of alpha channel output.

     image channel depth request
          Integer number of bits per channel to output.   If  not
          given,  the  bit depth per channel is the one that most
          closely matches each image to be output and  is  avail-
          able to the image file format.

          This tag is only used by image write handlers.

          Bit depth values are typically between 1 and 32.  8-bit
          depths are the most common.

     image clt request
          Integer flag to block or force a color lookup table  to
          be  output.  If not given, a color lookup table is out-
          put, if the image has one and the  format  can  support
          it.  If the tag forces output when a file format cannot
          support it or blocks output when a format must have it,
          an error is returned.

          This tag is only used by image write handlers.  A value
          of IMCLTDUMP forces color lookup table output.  A value
          of IMCLTNODUMP blocks output.

     image compression request
          Integer compression mode to use.   If  not  given,  the
          most common or best compression scheme available to the
          format is used.  If the  tag  specifies  a  compression
          scheme  not  available  to  the  format,  an  error  is
          returned.

          This tag is only used by  image  write  handlers.   The



SDSC              Last change: August 25, 1992                  5






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



          compression scheme selects how pixel data is compressed
          in order to save space in the output  file.   Available
          compression schemes include:

               Value            Meaning
8               __________________________________________
               IMCOMPNONE       Don't compress
               IMCOMPRLE        Run-length encode
               IMCOMPLZW        Lempel-Ziv Welsh encoding
               IMCOMPPACKBITS   Apple PackBits

          Uncompressed  images  store  each  image  pixel  as   a
          separate value in the file.

          Run-length encoded images denote runs of adjacent  pix-
          els  with  the  same color.  Such runs are reduced to a
          run length and a run  value  (the  pixel's  color)  and
          write  these  two  values  to  the  file instead of the
          (potentially) much longer  run  itself.   This  usually
          gains  about  a  30%  reduction in storage space.  Most
          image file formats  support  some  form  of  run-length
          encoding, but they differ in the exact mechanics.

          Lempel-Ziv Welsh and Apple PackBits encoding  are  bit-
          wise  run-length  encoding  schemes that are more time-
          consuming to process but achieve even  higher  compres-
          sion ratios.  Both schemes are available for only a few
          image file formats.

     image interlace request
          Integer RGB image interlace mode to use.  If not given,
          the most common or most easily compressed RGB interlac-
          ing scheme is used.   If  the  tag  specifies  that  an
          interlace  mode be used that the image file format can-
          not support, an error is returned.

          This tag is only used by image write handlers, and only
          if the image to be written is an RGB image.  The inter-
          lace mode specifies how RGB images should be stored  in
          the file.  Available interlace modes include

               Value          Meaning
8               _________________________________
               IMINTERNONE    Don't interlace
               IMINTERLINE    Scanline interlace
               IMINTERPLANE   Plane interlace

          Non-interlaced RGB images are stored with each  pixel's
          red, green, and blue components as adjacent data in the
          file.  For instance, an RGB image would be  stored  as:
          RGBRGBRGBRGB.

          Scanline interlaced images store all of the  scanline's



6                 Last change: August 25, 1992               SDSC






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



          red  components  first, then the scanline's green, then
          blue components.  The next scanline starts  over  again
          with just its red components, and so on.

          Plane interlaced images store the  red  components  for
          all  of the image pixels, followed by all of the green,
          then all of the blue.

          When compressing images, plane interlacing usually pro-
          duces the best compression.

     image mono threshold
          Integer pixel value threshold  beyond  which  grayscale
          pixel  values  are  considered  black,  and below which
          pixel values are considered white when  mapping  grays-
          cale  images  to monochrome.  If not given, the default
          is 127.

          This tag is only used by  image  write  handlers.   The
          monochrome  threshold is used only if the output of the
          image into the selected file format  requires  reducing
          it from color or grayscale to monochrome.  Color images
          are converted to grayscale prior to  monochrome  thres-
          holding.

          See also ImVfbToMono(3IM).

     image type request
          Integer image type to output.  If not given, the  image
          type is that of the image being written or one as close
          to it as supported by the selected  output  image  file
          format.  If this tag is given and the requested type is
          not available to the format, an error is returned.

          This tag is only used by image write handlers.   Avail-
          able image types include

               Value         Meaning
8               ___________________________________
               IMTYPEINDEX   Color index per pixel
               IMTYPERGB     RGB color per pixel

          Color index images correspond to IMVFBINDEX8,  IMVFBIN-
          DEX16, and IMVFBMONO virtual frame buffer field values.
          RGB  images  correspond  to  IMVFBRGB   virtual   frame
          buffers.

          If the selected image type  differs  from  that  of  an
          image to be written, the image is converted into a tem-
          porary virtual frame buffer before being output.

          See   also   ImVfbToIndex8(3IM),   ImVfbToIndex16(3IM),
          ImVfbToRgb(3IM),          ImVfbToGray(3IM),         and



SDSC              Last change: August 25, 1992                  7


9


IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



          ImVfbToMono(3IM).

     program name
          Character string name of the program, such as the value
          in  _a_r_g_v[_0] passed into main. If not given, the program
          name defaults to "program."

          Program name is used when  constructing  error  message
          text  to  be  printed to the error stream passed to the
          error handler (see below).

  Error Handling
     Upon encountering an error, the image file  read  and  write
     routines use the following algorithm to decide how to report
     the error and whether or not to return or try and continue:

          if an error handler has been defined in the _f_l_a_g_s_T_a_b_l_e,
              if the error is fatal,
                  call the error handler with the error message text
                  set ImErrNo and return an error
              call the error handler with the error message text
              if the error handler returned a -1,
                  set ImErrNo and return an error
          else if an error stream has been defined in the _f_l_a_g_s_T_a_b_l_e,
              print the error message text to the stream
              if the error is fatal,
                  set ImErrNo and return an error
          else if the error is fatal or a warning,
                  set ImErrNo and return an error

     Fatal errors are errors that cannot be recovered from.  If a
     handler  has  been given, it is called before the read/write
     routine returns.  If a stream has been defined  instead,  it
     is printed to before returning.  Otherwise, the routine just
     returns an error code.

     Warning errors are errors that somebody should see but don't
     require  aborting the read or write operation.  If a handler
     has been given, it is called and its return  value  checked.
     If  it returns a -1, the read/write routine returns.  Other-
     wise it tries to continue.  If a  stream  has  been  defined
     instead,  the error text is printed without returning.  Oth-
     erwise, the warning reverts to a fatal error and the routine
     returns with an error code.

     Information errors are messages that  should  be  displayed,
     but  don't require aborting the operation.  If a handler has
     been given, it is called and its return value  checked.   If
     it  returns  -1, the operation is aborted.  Otherwise, it is
     continued.  If a stream has been defined instead, the infor-
     mation text is printed out.




8                 Last change: August 25, 1992               SDSC






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



     Error handlers may be declared as follows:

       int MyHandler( severity, errno, message )
                  int severity;
                  int errno;
                  char *message;


     _s_e_v_e_r_i_t_y can be one of these three error severity types:

          _s_e_v_e_r_i_t_y         Meaning
8          _________________________________
          IMERRORFATAL     Fatal error
          IMERRORWARNING   Warning error
          IMERRORINFO      Information only

     The _e_r_r_n_o argument to the handler gives the ImErrNo code for
     the  error.   See  ImErrNo(3IM)  for  information  on  error
     numbers and generic error message texts for each.

     The _m_e_s_s_a_g_e argument to the handler  is  the  same  as  that
     printed to the error stream, if any, and has the form:

       program_name: file_name: text


     The _p_r_o_g_r_a_m__n_a_m_e and _f_i_l_e__n_a_m_e are those specified by  flags
     in  the  _f_l_a_g_s_T_a_b_l_e  (if  given).   The  _t_e_x_t of the message
     describes the error and may or may not be  more  informative
     than  the generic message available based on the _e_r_r_n_o error
     code.  The error message is not terminated with  a  carriage
     return.

     The error handler should return -1  if  the  read  or  write
     operation  is  to be aborted because of the error or 0 if it
     should  be  continued.   A  typical  error  handler   in   a
     windowing-based  application  would use the _s_e_v_e_r_i_t_y code to
     decide how to display a dialog box on the screen:

     IMERRORFATAL
          Dialog box containing the error  message  text  and  an
          "Abort"  button  is  displayed.  Pressing "Abort" takes
          down the dialog box and returns -1 from the handler.

     IMERRORWARNING and IMERRORINFO
          Dialog  box  containing  the  error  message  text  and
          "Abort" and "Continue" buttons are displayed.  Pressing
          "Abort" takes down the dialog box and returns  -1  from
          the  handler; pressing "Continue" takes down the dialog
          box and returns 0 from the handler.


9


SDSC              Last change: August 25, 1992                  9






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



  Automatic Conversions
     Most of the _f_l_a_g_s_T_a_b_l_e flags  having  names  beginning  with
     "image"  direct  how automatic image conversions should take
     place when writing an image file.  In most cases,  the  pro-
     grammer  need  never use any of these.  Automatic conversion
     takes place and does the "right thing." These flags are only
     necessary  if  the  programmer  wishes  to  steer  automatic
     conversion a particular way.

     Automatic image conversion is necessary when an image to  be
     written out is not in a format acceptable for the image file
     format.  For instance, if an RGB image is to be written  out
     as  a  MacPaint  file,  the image must first be converted to
     monochrome.  This is an automatic image conversion.

     Image conversions could be done by the user prior to calling
     ImFileWrite  or  ImFileFWrite, but the added hassle makes it
     convenient for the write routines themselves to handle image
     conversion.

     Image conversion must alter an image's attributes  to  match
     those of the output file format.  An image has a type (color
     index or RGB), a number of channels of color data per  pixel
     (usually 1 or 3), and a bit depth for each of those channels
     (usually 8 bits).  The three _f_l_a_g_s_T_a_b_l_e  flags  "image  type
     request," "image channel number request," and "image channel
     depth request" allow you to constrain  automatic  conversion
     to a particular value for these attributes.

     If an attribute is  not  constrained,  automatic  conversion
     chooses values that most closely match the image to be writ-
     ten.  If those values specify an image that the output image
     file  format cannot support (such as an RGB image in a mono-
     chrome MacPaint file), then automatic conversion  makes  the
     closest  match  to  what  the  file format can support.  The
     image to be written is then converted (in a  temporary  vir-
     tual frame buffer) to that match and output.

     If an attribute is constrained,  automatic  conversion  res-
     tricts its matching algorithm to require the image attribute
     match the user's request.  If this  prevents  the  algorithm
     from  creating a match between an image to be written and an
     output image file  format's  supported  abilities,  then  an
     error is returned and the image is not output.

     For instance, an RGB image is to be output into  a  MacPaint
     file.   With  no constraints, automatic conversion will con-
     vert the image to 1-bit monochrome and output it.  If  image
     type  is  constrained  to  be RGB, then automatic conversion
     cannot make a  match  (RGB  cannot  be  stored  in  MacPaint
     files), and an error is returned.




10                Last change: August 25, 1992               SDSC






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



     Automatic conversion contraints are most useful when a  par-
     ticular  variant  of  an output file format is desired.  For
     instance, a Sun rasterfile can support 1-bit monochrome,  8-
     bit color index, and 24-bit RGB image storage.  Without con-
     traints, an incomming RGB image will be written  out  as  an
     RGB  rasterfile  (the closest automatic match).  If the user
     wishes to display the image on an 8-bit  frame  buffer,  the
     "image  type request" flag could be used to constrain output
     conversion to a IMTYPEINDEX, color index image.  This  would
     force  automatic  conversion  to output an 8-bit color index
     Sun rasterfile.

  Output Constraints
     Many image file formats support multiple variants  on  image
     compression,  RGB  image  interlacing,  and the inclusion of
     color lookup tables and alpha channels.  Many of  the  _f_l_a_g_-
     _s_T_a_b_l_e flags having names beginning with "image" direct for-
     mat output to use a particular variant of the file format.

     If not given, these flags  default  to  the  "right  thing."
     Image  compression  defaults  to  the  best  or  most common
     compression scheme.  RGB image  interlace  defaults  to  the
     most common or most easily compressed interlace mode.  Color
     lookup tables are written if the image has one and the  for-
     mat can store it.  The same applies to alpha plane output.

  Pipe Handling
     When reading from or writing to pipes, some image file  for-
     mats  require  that  the data be stored in a temporary file.
     Such a file is created and later  destroyed.   If  there  is
     insufficient  space  in  /usr/tmp for this file, an error is
     returned.

EXAMPLES
     The following code opens and reads in a Sun  RASterfile  and
     retrieves the new virtual frame buffer image from the _d_a_t_a_T_-
     _a_b_l_e.  Note that a NULL pointer is given instead of a  _f_l_a_g_-
     _s_T_a_b_l_e.

       #include <stdio.h>
       #include "im.h"

       main( )
       {
            FILE *rasFile;
            ImVfb *image;
            TagTable *dataTable;
            TagEntry *imageEntry;

            /* Get space for the data list. */
            dataTable = TagTableAlloc( );




SDSC              Last change: August 25, 1992                 11






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



            /* Open the Sun rasterfile. */
            rasFile = fopen( "myfile.ras", "r" );

            /* Read in its images. */
            ImFileFRead( rasFile, "ras", NULL, dataTable );

            /* Get the virtual frame buffer. */
            imageEntry = TagTableQDirect( dataTable, "image vfb", 0 );
            TagEntryQValue( imageEntry, &image );

            /* Do something with it. */
            ...
       }


     The following code accepts command-line arguments to specify
     an  input format name and filename and an output format name
     and filename.  The input file is opened and read in  as  the
     selected  image  file format.  The output file is opened and
     the image data written back out in the new format.

       #include <stdio.h>
       #include "im.h"

       main( argc, argv )
            int argc;
            char *argv[ ];
       {
            FILE *file;
            TagTable *dataTable;

            /* Get space for the data list. */
            dataTable = TagTableAlloc( );

            /* Open the input file and read it in. */
            file = fopen( argv[2], "r" );
            ImFileFRead( file, argv[1], NULL, dataTable );
            fclose( file );

            /* Open the output file and write it out. */
            file = fopen( argv[4], "w" );
            ImFileFWrite( file, argv[3], NULL, dataTable );
            fclose( file );
       }


     The above program is a complete generic image file converter
     that  can  read  in any selected image file and output a new
     one in any desired format.  The above code is the basis  for
     the SDSC image conversion tool imconv(1IM).





12                Last change: August 25, 1992               SDSC






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



     The following code outputs an  image  stored  in  a  virtual
     frame  buffer  and  constrains  it  to be RGB and include an
     alpha plane.

       writeImage( image, fileName )
            ImVfb *image;
            char *fileName;
       {
            FILE *file;
            TagTable *dataTable;
            TagTable *flagsTable;
            int tmp;

            /* Get space for the data and flags tables. */
            dataTable = TagTableAlloc( );
            flagsTable = TagTableAlloc( );

            /* Add image to data table. */
            TagTableAppend( dataTable,
                 TagEntryAlloc( "image vfb", POINTER, &image ) );

            /* Add constraint flags. */
            tmp = IMTYPERGB;
            TagTableAppend( flagsTable,
                 TagEntryAlloc( "image type request", INT, &tmp ) );
            tmp = IMALPHADUMP;
            TagTableAppend( flagsTable,
                 TagEntryAlloc( "image alpha request", INT, &tmp ) );

            /* Open the output file and write the data. */
            file = fopen( fileName, "w" );
            ImFileFWrite( file, "rlb", flagsTable, dataTable );
            fclose( file );

            /* Clean up. */
            TagTableFree( dataTable );
            TagTableFree( flagsTable );
       }


RETURNS
     On successful completion, the read calls return  the  number
     of entries added to the _d_a_t_a_T_a_b_l_e and the write calls return
     the number of entries used from the _d_a_t_a_T_a_b_l_e.

     On failure, the read calls return -1 and set _I_m_E_r_r_N_o to

          IMESYS      System call error
          IMEMALLOC   Cannot allocate memory
          IMEFORMAT   Bad format
          IMENOREAD   Read not supported on format
          IMEMAGIC    Bad magic number in image file



SDSC              Last change: August 25, 1992                 13






IMFILEREAD(3IM)        SDSC IMAGE LIBRARY         IMFILEREAD(3IM)



          IMEDEPTH    Unknown image depth

     On failure, the read calls return -1 and set _I_m_E_r_r_N_o to

          IMESYS       System call error
          IMEMANYVFB   Too many VFBs for image write
          IMENOVFB     No VFB given for image write
          IMEMALLOC    Cannot allocate memory

FILES
     /usr/tmp/im._X_X_X_X_X_X  _T_e_m_p_o_r_a_r_y _f_i_l_e _f_o_r _p_i_p_e _h_a_n_d_l_i_n_g

SEE ALSO
     ImIntro  (3IM),  ImErrNo  (3IM),  ImFileFormatEquivs  (3IM),
     ImFileFormatOptions (3IM), ImFileQFFormat (3IM), ImFileQFor-
     mat (3IM), TagIntro (3TAG)

AUTHOR
     Dave Nadeau
     San Diego Supercomputer Center

CONTACT
     SDSC consultants, (619)534-5100, consult@y1.sdsc.edu
































14                Last change: August 25, 1992               SDSC



