home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / viff / spec / viff.h < prev   
C/C++ Source or Header  |  1994-06-20  |  17KB  |  420 lines
  1. Copyright 1990, 1991, 1992 (c) Khoral Research, Inc.
  2.  
  3. All rights reserved.
  4.  
  5. The viff.h file is a plain ascii C include file.  It is a copy of the
  6. file in KHOROS_HOME/include/viff.h, but with a less restrictive
  7. copyright.  The purpose of this file is allow others to build in 
  8. interoperability to their software, without having to get a Khoros license to
  9. distribute their software.   Redistribution of any other component of
  10. Khoros still needs a separate license that is available via the Khoros
  11. Consortium.
  12.  
  13. For further information, contact: 
  14.  
  15. khoros-request@khoros.unm.edu 
  16.  
  17.  
  18. /*
  19.   * Khoros: $Id$
  20.   */
  21.  
  22.  /*
  23.   * $Log$
  24.   */ 
  25.  
  26. /*
  27.  *----------------------------------------------------------------------
  28.  *
  29.  * Copyright 1990, University of New Mexico.  All rights reserved.
  30.  * 
  31.  * Permission to copy, modify, and use this include file is hereby
  32.  * granted, provided that this notice is retained thereon and
  33.  * on all copies.  UNM makes no representations as too the sui-
  34.  * tability and operability of this software for any purpose.
  35.  * It is provided "as is" without express or implied warranty.
  36.  * 
  37.  * UNM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  38.  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT-
  39.  * NESS.  IN NO EVENT SHALL UNM BE LIABLE FOR ANY SPECIAL,
  40.  * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY OTHER DAMAGES WHAT-
  41.  * SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  42.  * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  43.  * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER-
  44.  * FORMANCE OF THIS SOFTWARE.
  45.  * 
  46.  *----------------------------------------------------------------------
  47.  */
  48.  
  49. #ifndef _viff_h_
  50. #define _viff_h_
  51.  
  52. /* >>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  53.    >>>>                                                                   <<<<
  54.    >>>>      file: viff.h                              <<<<
  55.    >>>>                                                                   <<<<
  56.    >>>>      contains:  Khoros Visualization/Image File Format.           <<<<
  57.    >>>>                 Design considerations included the need           <<<<
  58.    >>>>            for portability, expandability and simplicity.    <<<<
  59.    >>>>                                                                   <<<<
  60.    >>>>      written by: John Rasure                          <<<<
  61.    >>>>                                                                   <<<<
  62.    >>>>      date: 5/5/88                              <<<<
  63.    >>>>                                                                   <<<<
  64.    >>>>      modifications:  Scott R. Wilson 1/13/88                  <<<<
  65.    >>>>                      Scott R. Wilson 5/3/88 - Version 2, Release 0<<<<
  66.    >>>>                      Scott Wilson, John Rasure, Tom Sauer, and    <<<<
  67.    >>>>                 Mark Young:  2/18/89 - Version 3 Release 0   <<<<
  68.    >>>>                 Scott Wilson - Version 3.1                   <<<<
  69.    >>>>                 Tom Sauer - 7/12/89 removed the #defines for <<<<
  70.    >>>>                     location dimension                  <<<<
  71.    >>>>                 Scott Wilson - Correct comment for           <<<<
  72.    >>>>                 subrow_size 5/9/90                   <<<<
  73.    >>>>                 Scott Wilson - Deleted unneeded include of   <<<<
  74.    >>>>              vdefines.h 18-Jan-91                         <<<<
  75.    >>>>                                                                   <<<<
  76.    >>>>                                                                   <<<<
  77.    >>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/
  78.  
  79.  
  80. /*
  81. ******************************************************************
  82.     Khoros Visualization/Image File Format                 
  83.                                      
  84.     A Khoros data file is organized as a 1Kbyte header     
  85.     followed by additional information.  The first two       
  86.     bytes of the header tell what kind of stuff the          
  87.     additional information is.  For Khoros image files,     
  88.     the additional information consists of the maps,   
  89.     the location data, and then the image or vector data.    
  90.                                                                 
  91.     There is a supporting document for this file called      
  92.     "The Khoros Visualization/Image File Format" that will help to        
  93.     expalin the various fields, see $KHOROS_HOME/manual/viff_format.
  94.  
  95.     The header fields where carefully selected to            
  96.     prevent contradictions between categories, i.e. they     
  97.     were chosen to be orthogonal to each other.  However,
  98.     in several situations this causes the fields to supply
  99.     redundant information.
  100.                                  
  101.     Note that the structure contains pointers to the various 
  102.     chunks of data.  These will make sense ONLY when the 
  103.     data is in memory.  
  104.  
  105.     *imagedata - points to a sequence of images, an image is
  106.     made up of bands, and the bands are in a sequence; or
  107.     it can point to vectors, where the vector dimension is
  108.     the number of bands.
  109.  
  110.     *maps - points to a sequence of 2-dimensional maps, a map 
  111.     is organized as stacked columns.  A data value indexes map rows.
  112.  
  113.     *location - points to bands of coordinate values, ie if
  114.     two dimensional locations, then there would be a band
  115.     of x's followed by a band of y's.
  116.                                  
  117.     The Khoros convention for the image orientarion is     
  118.     with the image origin in the upper left hand corner.     
  119.                                      
  120. ******************************************************************
  121. */
  122.  
  123.  
  124. /* 
  125.  * The VIFF header size for a Cray is 4096 because of the
  126.  * word size on a cray. So, set the headersize to be 4096
  127.  * for the cray and 1024 of all other machines.
  128.  */
  129.  
  130. #if defined(CRAY)
  131. #   define VIFF_HEADERSIZE 4096
  132. #else
  133. #   define VIFF_HEADERSIZE 1024
  134. #endif
  135.  
  136.  
  137. /* image structure definition */
  138.  
  139. struct xvimage    {
  140.  
  141. /*  Administrative or file management information */
  142.  
  143.     char    identifier;    /* a magic number that tells
  144.                    the world that this is an
  145.                    Khoros file */
  146.  
  147.     char    file_type;    /* tells if this file is a VIFF file */
  148.  
  149.     char     release;    /* release number */
  150.  
  151.     char    version;    /* version number */
  152.  
  153.         char    machine_dep;    /* indicates peculiarities of */
  154.                 /* machine architecture */
  155.     
  156.     char    trash[3];    /* preserves word boundaries */
  157.                                 /* groups of 4 bytes */
  158.  
  159.     char    comment[512];    /* text for image commentary */
  160.  
  161. /* Things that specify the spatial properties of the image, pixel
  162.    organization, and data storage arrangement.  */
  163.  
  164.     unsigned long    row_size;    /* length of row in pixels,
  165.                        i.e. number of columns */
  166.  
  167.     unsigned long    col_size;    /* length of column in pixels,
  168.                           i.e. number or rows */
  169.                     
  170.     unsigned long    subrow_size;    /* Length of subrows. This is useful
  171.                                            when one wants pixel vectors to
  172.                                            represent 2D objects (images).
  173.                                            The size of each pixel "image"
  174.                                            would be subrow_size (columns)
  175.                                            by num_data_bands/subrow_size (rows).
  176.                                            This field may be ignored except
  177.                                            by routines that need the 2D
  178.                                            interpretation. */
  179.  
  180. /* The product of row_size and col_size is used to indicate 
  181.    the number of locations when the location type is explicit,
  182.    the product also indicates the number of pixels in a band,
  183.    or the number of vectors.  */
  184.  
  185.     long    startx, starty;    /* subimage starting position (upper
  186.                    left hand corner), negative indicates
  187.                    that it is not a subimage */
  188.  
  189.     float     pixsizx, pixsizy;    /* Actual size of pixel at time of
  190.                        digitization in meters */
  191.  
  192.     unsigned long    location_type;    /* implied or explicit location
  193.                        data    (implied locations are
  194.                        derived from row_size and
  195.                        col_size */
  196.  
  197.     unsigned long    location_dim;    /* explicit locations can be of
  198.                        any dimension  */
  199.  
  200.     unsigned long    num_of_images;     /* number of images
  201.                        pointed to by *imagedata,
  202.                        do not confuse with number of
  203.                        bands */
  204.  
  205.         unsigned long    num_data_bands;    /* Number of bands per data pixel,
  206.                        or number of bands per image, or
  207.                        dimension of vector data, or
  208.                        number of elements in a vector */
  209.  
  210.     unsigned long    data_storage_type;  /* storage type for disk data */
  211.  
  212.     unsigned long    data_encode_scheme; /* encoding scheme of disk data */
  213.  
  214. /* Things that determine how the mapping (if any) of data bands is 
  215.    to be done to obtain the actual "image" or data.  */
  216.  
  217.         unsigned long    map_scheme;     /* How mapping (if any) is to occur */
  218.  
  219.     unsigned long    map_storage_type;/* Storage type of cells in the maps */
  220.  
  221.     unsigned long    map_row_size; /* number of columns in map array */
  222.  
  223.     unsigned long    map_col_size;    /* number of entries in map (rows) */
  224.  
  225.     unsigned long    map_subrow_size; /* Length of subrows. This is useful
  226.                             when using the output vector from
  227.                                             the map as a 2-D image, rather
  228.                         than just a vector. The size of
  229.                         the 2-D image would be:
  230.                         map_subrow_size (columns) by
  231.                         map_row_size/map_subrow_size
  232.                                             (rows). This field may be ignored
  233.                                             except by routines that need the 2D
  234.                                             interpretation */
  235.  
  236.     unsigned long    map_enable;    /* Tells if the disk data is valid
  237.                        with or without being sent thru the
  238.                        map. Some data MUST be mapped to be
  239.                        valid. */
  240.  
  241.     unsigned long    maps_per_cycle;    /* number of maps to constitue a "cycle"
  242.                         for VFF_MS_CYCLE */
  243.  
  244. /* Specification of the particular color model in use when working with a
  245.    color image. This just tells what the coordinate system and axis orientation
  246.    of the color space is.  */
  247.  
  248.         unsigned long    color_space_model;
  249.  
  250. /* Extra fields for use by the user as needed. These are NOT SUPPORTED
  251.    in any way, except for being read and written correctly with respect
  252.    to machine dependencies.  */
  253.  
  254.     unsigned long     ispare1,ispare2;    /* Spare long ints */
  255.  
  256.     float        fspare1,fspare2;    /* Spare floats */
  257.  
  258. /* Pointers to the actual data - these are valid only when in memory! */
  259.  
  260.     char    reserve[VIFF_HEADERSIZE - (21*sizeof(long))  
  261.                  - (520*sizeof(char)) 
  262.                      - (2*sizeof(char *)) - (4*sizeof(float))
  263.                      - (sizeof(float *))];
  264.                 /* maximum header information is 
  265.                    1024 bytes, what is not currently
  266.                    used is saved in reserve */
  267.  
  268.     char *maps;        /* a pointer to the maps, must be cast into 
  269.                    the proper type */
  270.  
  271.     float *location;    /* a pointer to the location data (for
  272.                    explicit locations, each location is
  273.                    paired with data pointed to by 
  274.                    *imagedata,  all locations are 
  275.                    in float  */
  276.  
  277.     char *imagedata;    /* a pointer to the input data (straight off
  278.                    of disk, must be cast into the proper type */
  279.  
  280.     } ;
  281.  
  282. /* definitions for version number,
  283.    char release; */
  284. #define XV_IMAGE_VER_NUM    3    /* Version 3 (3.1) */
  285.  
  286. /* definitions for release number,
  287.    char version; */
  288. #define XV_IMAGE_REL_NUM    1    /* Release 1   */
  289.  
  290. /* definitions for subimage information,
  291.    long startx, starty; */
  292. #define    VFF_NOTSUB           ~0    /* a negative number indicates that
  293.                        the image is not a subimage    */
  294.  
  295. /* definitions for machine dependencies,
  296.    char machine_dep; */
  297. #define    VFF_DEP_IEEEORDER       0x2    /* IEEE byte ordering */
  298. #define    VFF_DEP_DECORDER        0x4    /* DEC (VAX) byte ordering */
  299. #define VFF_DEP_NSORDER        0x8    /* NS32000 byte ordering */
  300. #define VFF_DEP_CRAYORDER    0xA    /* Cray byte size and ordering */
  301.  
  302. #define    VFF_DEP_BIGENDIAN    VFF_DEP_IEEEORDER
  303. #define    VFF_DEP_LITENDIAN    VFF_DEP_NSORDER
  304.  
  305.  
  306. /* definitions for data storage type,
  307.    unsigned long data_storage_type; */
  308. #define    VFF_TYP_BIT        0    /* pixels are on or off (binary image)*/
  309.                                         /* Note: This is an X11 XBitmap 
  310.                        with bits packed into a byte and
  311.                        padded to a byte */
  312. #define    VFF_TYP_1_BYTE        1    /* pixels are byte (unsigned char) */
  313. #define    VFF_TYP_2_BYTE        2    /* pixels are two byte (short int) */
  314. #define    VFF_TYP_4_BYTE        4    /* pixels are four byte (integer) */
  315. #define    VFF_TYP_FLOAT        5    /* pixels are float (single precision)*/
  316. #define    VFF_TYP_COMPLEX        6    /* pixels are complex float */
  317. #define VFF_TYP_DOUBLE        9    /* pixels are float (double precision)*/
  318.  
  319. #define VFF_TYP_DCOMPLEX    10    /* double complex */
  320.  
  321. /* definitions for data encoding scheme on disk - i.e. it may be
  322.    compressed using RLE, or uncompressed (RAW).
  323.    unsigned long data_encode_scheme; */
  324. #define    VFF_DES_RAW        0    /* Raw - no compression */
  325. #define VFF_DES_COMPRESS    1    /* Compressed using ALZ */
  326. #define VFF_DES_RLE        2    /* Compressed using RLE */
  327. #define VFF_DES_TRANSFORM    3    /* Transform based compression */
  328. #define VFF_DES_CCITT        4    /* CCITT standard compression */
  329. #define VFF_DES_ADPCM        5    /* ADPCM compression */
  330. #define VFF_DES_GENERIC        6    /* User-specified compression */
  331.  
  332. /* definitions for map data or cells storage type,
  333.    unsigned long map_storage_type; */
  334. #define VFF_MAPTYP_NONE        0    /* No cell type is assigned  */
  335. #define    VFF_MAPTYP_1_BYTE    1    /* cells are byte (unsigned char)    */
  336. #define    VFF_MAPTYP_2_BYTE    2    /* cells are two byte (short int) */
  337. #define    VFF_MAPTYP_4_BYTE    4    /* cells are four byte (integer) */
  338. #define    VFF_MAPTYP_FLOAT    5    /* cells are float (single precision) */
  339. #define    VFF_MAPTYP_COMPLEX    6    /* cells are complex FLOAT */
  340. #define    VFF_MAPTYP_DOUBLE    7    /* cells are float (double precision) */
  341.  
  342. /* definitions for mapping schemes,
  343.    unsigned long map_scheme; */
  344. #define VFF_MS_NONE        0    /* No mapping is to be done, and no
  345.                        maps are to be stored. */
  346. #define    VFF_MS_ONEPERBAND    1    /* Each data band has its own map */
  347. #define VFF_MS_CYCLE        2    /* An array of maps is selected in order
  348.                        by groups of maps_per_cycle, allowing
  349.                        "rotating the color map" */
  350. #define    VFF_MS_SHARED        3    /* All data band share the same map */
  351. #define VFF_MS_GROUP        4    /* All data bands are "grouped" 
  352.                        together to point into one map */
  353. /* definitions for enabling the map,
  354.    unsigned long map_enable; */
  355. #define VFF_MAP_OPTIONAL    1    /* The data is valid without being
  356.                        sent thru the color map. If a
  357.                        map is defined, the data may 
  358.                        optionally be sent thru it. */
  359. #define    VFF_MAP_FORCE        2    /* The data MUST be sent thru the map
  360.                        to be interpreted */
  361.  
  362. /* definitions for color map models,
  363.    unsigned long color_space_model; */
  364.  
  365. /*  the models use the following convention:
  366.     ntsc: national television systems committee
  367.     cie:  Commission Internationale de L'Eclairage
  368.     ucs:  universal chromaticity scale
  369.     RGB:  red band, green band, blue band
  370.     CMY:  cyan band, magenta band, yellow band
  371.     YIQ:  luminance, I and Q represent chrominance
  372.     HSV:  hue, saturation, value
  373.     IHS:  intensity, hue, saturation
  374.     XYZ:
  375.     UVW:  
  376.     SOW:  
  377.     Lab:
  378.     Luv:
  379.  
  380. For more information on how to interpret the combined meaning of the
  381. colorspace fields, see the document in $KHOROS_HOME/manual/viff_format,
  382. which contains detailed descriptions on the fields along with numerous
  383. examples of proper use.  */
  384.  
  385. #define VFF_CM_NONE    0
  386. #define    VFF_CM_ntscRGB    1
  387. #define    VFF_CM_ntscCMY    2
  388. #define    VFF_CM_ntscYIQ    3
  389. #define    VFF_CM_HSV    4
  390. #define    VFF_CM_HLS    5
  391. #define    VFF_CM_IHS    6
  392. #define    VFF_CM_cieRGB    7
  393. #define    VFF_CM_cieXYZ    8
  394. #define    VFF_CM_cieUVW    9
  395. #define    VFF_CM_cieucsUVW    10
  396. #define    VFF_CM_cieucsSOW    11
  397. #define    VFF_CM_cieucsLab    12
  398. #define    VFF_CM_cieucsLuv    13
  399. #define    VFF_CM_GENERIC        14    /* the color space is user defined */
  400. #define VFF_CM_genericRGB    15    /* an RGB image but not conforming
  401.                        to any standard */
  402.  
  403. /* definitions for location type,
  404.    unsigned long location_type; */
  405. #define    VFF_LOC_IMPLICIT    1    /*  The location of image pixels
  406.                         or vector data is given by using
  407.                         the implied 2D array given by
  408.                         row_size and col_size.  */
  409. #define    VFF_LOC_EXPLICIT    2    /*  The location of the image pixels
  410.                         or the vectors is explicit */
  411.  
  412.  
  413. /* The following are a couple of defines that make it easier
  414.    to use the image size data */
  415. #define number_of_rows col_size
  416. #define number_of_cols row_size
  417.  
  418. #endif /* _viff_h_ */
  419. /* Don't add after the endif */
  420.