[Top] [Prev] [Next]

9.4 Writing Palettes

9.4.1 Writing a Palette: DFPaddpal and DFPputpal

To write a palette to an HDF file, the calling program must contain one of the following function calls:

C:		status = DFPaddpal(filename, palette);
FORTRAN:	status = dpapal(filename, palette)
	OR
C:		status = DFPputpal(filename, palette, overwrite, filemode);
FORTRAN:	status = dpppal(filename, palette, overwrite, filemode)
DFPaddpal and DFPputpal will write a palette to an HDF file named by filename. When given a new filename, DFPputpal and DFPaddpal creates a new file and writes the palette as the first object in the file. When given an existing filename, DFPaddpal appends the palette to the end of the file.

DFPputpal provides this functionality as well with additional options for how the data is handled, providing more control over how a palette is written to file than DFPaddpal. Specifically, the overwrite parameter determines whether or not to overwrite the last palette written to a file or to append a new palette onto the file. The filemode parameter determines whether to create a new file or to append the data to the previous file. Note the combination to overwrite a palette in a newly created file is invalid and will generate an error. To overwrite a palette, filename must be the same filename as the last file accessed through the DFP interface. The parameters for DFPaddpal and DFPputpal are more explicitly defined in the following table.

TABLE 9B DFPputpal and DFPaddpal Parameter List
Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFPputpal

[intn]

(dpppal)
filename

char *
character*(*)
Name of the HDF file.

palette

VOIDP
<valid numeric data type>
768-byte space for palette.

overwrite

intn
integer
Palette write specification.

filemode

char *
character*(*)
File write specification.

DFPaddpal

[intn]

(dpapal)
filename

char *
character*(*)
Name of the HDF file.

palette

VOIDP
<valid numeric data type>
768-byte space with palette.

Calling DFPaddpal or DFPputpal immediately after writing an 8-bit raster image will not group the palette with the preceding image. Palettes written to a file sequentially can be retrieved sequentially. However, to maintain a higher level of organization between multiple palettes and images stored in the same file, it's a good idea to explicitly group each palette with the image to which it belongs. To find out more about assigning a palette to an image, see Chapter 6, 8-Bit Raster Images (DFR8 API).

EXAMPLE 1. Writing a Palette

In the following code examples, DFPaddpal is used to write a palette to an HDF file named "Example1.hdf".

C version

FORTRAN-77 version

9.4.2 Specifying the Reference Number of a Palette: DFPwriteref

DFPwriteref specifies the reference number of the palette to be written on the next call to DFPaddpal or DFPputpal:

C:		status = DFPwriteref(filename, ref);
		status = DFPaddpal(filename, palette);
FORTRAN:	status = dpwref(filename, ref)
		status = dpapal(filename, palette)
DFPwriteref assigns the specified reference number to the next palette written to the file filename. If the value of ref is the same as the reference number of an existing palette, the existing palette will be overwritten.

The parameters of DFPwriteref are further described in the following table.

TABLE 9C - DFPwriteref Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFPwriteref

[intn]

(dpwref)
filename

char *
character*(*)
Name of the HDF file containing the palette.

ref

uint16
integer
Reference number for the next call to DFPaddpal or DFPputpal.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.