home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / hdf / spec / hdf3_2_3.txt < prev    next >
Text File  |  1994-06-01  |  8KB  |  295 lines
  1. 3.1    NCSA HDF Calling Interfaces and Utilities
  2.  
  3. Storing Palettes    3.1
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. March 1993
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13. 3.1    NCSA HDF Calling Interfaces and Utilities
  14.  
  15. Storing Palettes    3.1
  16.  
  17. National Center for Supercomputing Applications
  18.  
  19. March 1993
  20.  
  21.                                                                 
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29. Chapter 3    Storing Palettes
  30.  
  31.  
  32.  
  33. Chapter Overview
  34. HDF 8-Bit Palettes
  35. Writing Palettes to a File
  36. Reading Palettes from a File
  37. Other Palette Routines
  38.  
  39. Chapter Overview
  40.  
  41. This chapter describes the routines that are available for storing 
  42. and retrieving 8-bit palettes.
  43.  
  44.  
  45. HDF 8-Bit Palettes
  46.  
  47. An 8-bit palette is a lookup table with 256 entries that tell the 
  48. system hardware which color to associate with each of the 256 
  49. possible pixel values. Each entry in the palette is chosen from a 
  50. master palette of 224 RGB colors.
  51.  
  52. In HDF files, 8-bit palettes are assumed to be organized as 
  53. follows. Each palette entry consists of 3 bytes╤one each for red, 
  54. green, and blue. The first three bytes represent the R, G, and B 
  55. values of the first color in the palette; the next three the R, G, and 
  56. B values of the second color; and so forth. The total size of a 
  57. palette is 768 bytes. 
  58.  
  59. The HDF library contains routines for storing and retrieving 
  60. palettes. These routines are callable from C and FORTRAN 
  61. programs that have access to the library. All of the callable 
  62. palette routines in the library begin with the letters DFP.
  63.  
  64. The functions, DFPaddpal and DFPgetpal, are the primary routines 
  65. for palette I/O and should be sufficient for most palette I/O 
  66. operations. The other six palette functions╤DFPputpal, DFPnpals, 
  67. DFPwriteref, DFPreadref, DFPrestart, and DFPlastref╤provide 
  68. greater control of the I/O process and are available to you if more 
  69. control is needed.
  70.  
  71. Table 2.1 lists the long and short names and the functions of the 
  72. palette routines currently contained in the HDF library. The 
  73. following sections provide descriptions and examples of these 
  74. calling routines.
  75.  
  76. Table 3.1    Palette I/O Routines in the HDF Library
  77.  
  78. C        FORTRAN
  79. Name        Name    Function
  80.  
  81. DFPaddpal    dpapal    appends a palette to a file.
  82.  
  83. DFPgetpal    dpgpal    reads in the next palette in the file.
  84.  
  85. DFPputpal    dpppal    writes a palette to a file.
  86.  
  87. DFPnpals    dpnpals    indicates number of palettes in a file.
  88.  
  89. DFPwriteref    dpwref    sets the reference number of the next palette 
  90.             to be written.
  91.  
  92. DFPreadref    dprref    sets the reference number of the next palette 
  93.             to be retrieved.
  94.  
  95. DFPrestart    dprest    specifies that the next call to DFPgetpal reads the 
  96.             first palette in the file, rather than the next.
  97.  
  98. DFPlastref    dplref    returns the value of the reference number most 
  99.             recently read or written.
  100.  
  101.  
  102. Writing Palettes to a File
  103.  
  104. DFPaddpal
  105.  
  106. FORTRAN:
  107. INTEGER FUNCTION dpapal(filename, pal)
  108. CHARACTER*(*) filename    -    name of HDF file
  109. CHARACTER*(*) pal    -    768-byte space with palette
  110.  
  111. C:
  112. int DFPaddpal(filename, palette)
  113. char *filename;    /* name of HDF file */
  114. void *palette;    /*768-byte space with palette */
  115.  
  116. Purpose:  To append the palette stored in the array palette to an 
  117. HDF file.
  118.  
  119. Returns:  0 on success; ╨1 on failure.
  120.  
  121. If file does not exist, it is created and the palette written to it.
  122.  
  123. DFPaddpal is often sufficient for adding the palette that you want 
  124. to an HDF file. Other palette routines, which provide more refined 
  125. access to palettes, are described next.
  126.  
  127.  
  128. Example: Writing a Palette to a File  with DFPaddpal
  129.  
  130. Figure 3.1 shows a C code segment for writing a palette to an HDF file.
  131.  
  132. Figure 3.1    Writing a Palette to a File 
  133.  
  134. C:
  135.    char    pal[768];
  136.    
  137.    DFPaddpal("myfile.hdf",pal);
  138.    ...
  139.  
  140.  
  141. DFPputpal
  142.  
  143. FORTRAN:
  144. INTEGER FUNCTION dpppal(filename, pal, ow, filemode)
  145. CHARACTER*(*) filename    -    name of HDF file
  146. CHARACTER*(*) pal    -    768╨byte space for palette
  147. INTEGER ow        -    if 1, overwrite last palette read 
  148.             or written 
  149.             if 0, write it as a fresh palette 
  150. INTEGER filemode    -    if "a", append palette to file 
  151.             if "w", create new file
  152.  
  153. C:
  154. int DFPputpal(filename, palette, overwrite, filemode)
  155. char *filename;    /* name of HDF file */
  156. void *palette;    /* 768╨byte space for palette */
  157. int overwrite;    /* if 1, overwrite last palette read or 
  158.         written */
  159.     /* if 0, write it as a fresh palette */
  160. char *filemode;    /* if "a", append palette to file */
  161.     /* if "w", create new file */
  162.  
  163.  
  164. Purpose:  To write a palette to file.
  165.  
  166. Returns:  0 on success; ╨1 on failure.
  167.  
  168. This routine provides more control than DFPaddpal. Note that the 
  169. combination filemode="w" and overwrite=1 has no meaning and 
  170. will generate an error.
  171.  
  172.  
  173. Reading Palettes from a File
  174.  
  175. DFPgetpal
  176.  
  177. FORTRAN:
  178. INTEGER FUNCTION dpgpal(filename, pal)
  179. CHARACTER*(*) filename    -    name of HDF file
  180. CHARACTER*(*) pal    -    768╨byte space for palette
  181.  
  182. C:
  183. int DFPgetpal(filename, palette)
  184. char *filename;        /* name of HDF file */
  185. void *palette;    /* 768╨byte space for palette */
  186.  
  187. Purpose:  To get the next palette from file and store it in the 
  188. array palette.
  189.  
  190. Returns:  0 on success; ╨1 on failure.
  191.  
  192. The array palette is assumed to be allocated at least 768 bytes. 
  193. Successive additional calls to DFPgetpal retrieve the palettes in 
  194. the file in the sequence in which they are stored.
  195.  
  196. DFPgetpal is often sufficient for getting the palette that you want 
  197. from an HDF file. Other palette routines, which provide more 
  198. refined access to palettes are described below.
  199.  
  200.  
  201. Example: Reading the First Available Palette
  202.  
  203. Figure 3.2 shows a C code segment that reads the first available 
  204. palette from an HDF file. 
  205.  
  206. Figure 3.2    Reading the First Available Palette
  207.  
  208. C:
  209.    char    pal[768];
  210.    
  211.    DFPgetpal("myfile.hdf",pal);
  212.    ...
  213.  
  214.  
  215. Other Palette Routines
  216.  
  217. DFPnpals
  218.  
  219. FORTRAN:
  220. INTEGER FUNCTION dpnpals(filename)
  221. CHARACTER*(*) filename
  222.  
  223. C:
  224. int DFPnpals(filename)
  225. char *filename;    /* name of HDF file */
  226.  
  227. Purpose:  To tell how many palettes are present in a file.
  228.  
  229. Returns:  Number of palettes on success; ╨1 on failure.
  230.  
  231. DFPwriteref
  232.  
  233. FORTRAN:
  234. INTEGER FUNCTION dpwref(filename, ref)
  235. CHARACTER*(*) filename    -    name of HDF file
  236. INTEGER ref        -    ref number to be used in next
  237.             palette write
  238.  
  239. C:
  240. int DFPwriteref(filename, ref)
  241. char *filename;    /* name of HDF file */
  242. uint16 ref;    /* ref number to be used in next palette write */
  243.  
  244. Purpose:  To set the reference number of the next palette to be 
  245. written.
  246.  
  247. Returns:  0 on success; ╨1 on failure.
  248.  
  249.  
  250. DFPreadref
  251.  
  252. FORTRAN:
  253. INTEGER FUNCTION dprref(filename, ref)
  254. CHARACTER*(*) filename    -    name of HDF file
  255. INTEGER ref        -    ref number to be used in next read
  256.  
  257. C:
  258. int DFPreadref(filename, ref)
  259. char *filename;    /* name of HDF file */
  260. uint16 ref;    /* ref number to be used in next DFPgetpal */
  261.  
  262. Purpose:  To set the reference number of the palette that 
  263. DFPgetpal will retrieve next.
  264.  
  265. Returns:  0 on success; ╨1 if a palette with this reference number 
  266. does not exist or if an error occurs.
  267.  
  268.  
  269. DFPrestart
  270.  
  271. FORTRAN:
  272. INTEGER FUNCTION dprest()
  273.  
  274. C:
  275. int DFPrestart()
  276.  
  277. Purpose:  To cause the next call to DFPgetpal to read the first 
  278. palette in the file.
  279.  
  280. Returns:  0 on success.
  281.  
  282.  
  283. DFPlastref
  284.  
  285. FORTRAN:
  286. INTEGER FUNCTION dplref()
  287.  
  288. C:
  289. int DFPlastref()
  290.  
  291. Purpose:  To determine the value of the reference number most 
  292. recently read or written by a palette function call.
  293.  
  294. Returns:  The reference number on success; ╨1 on failure.
  295.