[Top] [Prev] [Next]

9.5 Reading a Palette

 The DFP programming model for reading a palette is similar to that for writing a palette - only the palette read call is required.

9.5.1 Reading a Palette: DFPgetpal

DFPgetpal is the only function required to read a palette. If the file is being opened for the first time, DFPgetpal returns the first palette in the file. Subsequent calls will return successive palettes in the file. In this way palettes are read in the same order in which they were written to the file.

To read a palette from an HDF file, the calling program must contain the following routines:

C:		status = DFPgetpal(filename, palette);
FORTRAN:	status = dpgpal(filename,palette)
 DFPgetpal retrieves the next palette from the HDF file specified by filename. The space allocated for the palette is specified by palette and must be at least 768 bytes. When DFPgetpal is first called, it returns the first palette in the file. Subsequent calls to DFPgetpal will return successive palettes in the order in which they are stored in the file, including those stored via the DFR8 interface.

The parameters of DFPgetpal are defined in the following table.

TABLE 9D - DFPgetpal Parameter List

Routine Name

[Return Type]

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

[intn]

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

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

EXAMPLE 2. Reading a Palette

 The following examples demonstrate the method used to read a palette from the "Example1.hdf" HDF file created in Example 1.

C version

FORTRAN-77 version

9.5.2 Reading a Palette with a Given Reference Number: DFPreadref

 DFPreadref is used to access specific palettes stored in files containing multiple palettes. It is the optionally called before DFPgetpal to set the next palette to be accessed to be the specified palette. DFPreadref can be used in connection with vgroups, which identify their members by tag/reference number pair.

To access a specific palette, use the following calling sequence:

C:		true_false = DFPreadref(filename, ref);
		status = DFPgetpal(filename, palette);	
FORTRAN:	true_false = dprref(filename, ref)
 
		status = dpgpal(filename, palette)
 DFPreadref specifies the reference number for the next read operation performed on the HDF file filename to the reference number specified by ref.

The parameters of DFPreadref are further defined in the following table.

TABLE 9E - DFPreadref Parameter List

Routine Name

[Return Type]

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

[intn]

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

ref
uint16
integer
Reference number of the next palette to be read.

9.5.3 Specifying the Next Palette to be Accessed to be the First Palette: DFPrestart

 DFPrestart causes the next DFPgetpal to read from the first palette in the file, rather than the palette following the one that was most recently read. DFPrestart has the following syntax:

C:		status = DFPrestart( );
FORTRAN:	status = dprest( )

[Top] [Prev] [Next]

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