[Top] [Prev] [Next]

8.10 Reading and Writing Palette Data Using the GR Interface

The GR API library includes routines that read, write, and access information about palette data attached to GR images. Although this functionality is also provided by the HDF Palette API library, it is not a recommended practice to use the Palette API to access and manipulate palette objects created by GR interface routines.

The routines are named GRgetlutid, GRluttoref, GRgetlutinfo, GRwritelut, GRreqlutil, and GRreadlut. Note that the routine names use the term LUT to refer to palettes; LUT stands for color lookup tables.

8.10.1 Obtaining a Palette ID: GRgetlutid

Given a palette index, the routine GRgetlutid is used to get the palette identifier for the specified palette.

The GRgetlutid function takes two arguments, ri_id, the raster image identifier of the image that has the palette attached to it, and lut_index, the index of the palette, and returns the value of the palette identifier corresponding to the specified image. The syntax of GRgetlutid is as follows:

C:		pal_id = GRgetlutid(ri_id, lut_index);
FORTRAN:	pal_id = mggltid(ri_id, lut_index)
GRgetlutid returns the value of the palette identifier if successful and FAIL (or -1) otherwise. The GRgetlutid parameters are further discussed in Table 8J.

8.10.2 Obtaining the Reference Number of a Specified Palette: GRluttoref

Given a palette identifier, GRluttoref can be used to obtain the reference number of the specified palette.

The GRluttoref routine takes one argument, pal_id, a palette identifier, and returns the reference number of the palette. GRluttoref is commonly used to annotate the palette or to include the palette within a vgroup. The syntax of GRgetlutid is as follows:

C:		pal_ref = GRluttoref(pal_id);
FORTRAN:	pal_ref = mglt2rf(pal_id)
GRluttoref returns the reference number of the palette if successful and 0 otherwise. The GRluttoref parameters are further discussed in Table 8J.

TABLE 8J - GRgetlutid, GRgetlutinfo, and GRluttoref Parameter Lists

Routine Name

[Return Type]

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

[int32]

(mggltid)
ri_id
int32
integer
Raster image identifier

lut_index
int32
integer
Palette index

GRluttoref

[uint16]

(mglt2rf)
pal_id
int32
integer
Palette identifier

8.10.3 Obtaining Palette Information: GRgetlutinfo

Given a palette identifier, GRgetlutinfo retrieves information about the palette and its components.

The GRgetlutinfo function takes one input argument, pal_id, the identifier of the palette, and several return parameters. The return parameters are n_comps, the number of components of the palette; data_type, the data type of the palette data; interlace_mode, the interlace mode of the stored palette data; and num_entries, the number of entries in the palette. The syntax of GRgetlutinfo is as follows:

C:		status = GRgetlutinfo(pal_id, &n_comps, &data_type, &interlace_mode, &num_entries);
FORTRAN:	status = mgglinf(pal_id, n_comps, data_type, interlace_mode, num_entries)
GRgetlutinfo returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The GRgetlutinfo parameters are further discussed in Table 8J.

8.10.4 Writing Palette Data: GRwritelut

GRwritelut writes palette data into the palette identified by the parameter pal_id. The syntax of GRwritelut is as follows:

C:		status = GRwritelut(pal_id, n_comps, data_type, interlace_mode, num_entries, pal_data);
FORTRAN:	status = mgwrlut(pal_id, n_comps, data_type, interlace_mode, num_entries, pal_data)
	OR	status = mgwclut(pal_id, n_comps, data_type, interlace_mode, num_entries, pal_data)
The parameter n_comps specifies the number of pixel components in the palette; it must have a value of at least 1. The parameter data_type specifies the data type of the palette data. Refer to Table 2E on page 13 for all data types supported by HDF.

The parameter interlace_mode specifies the interlacing in which the palette is to be written. The valid values of interlace_mode are: MFGR_INTERLACE_PIXEL (or 0), MFGR_INTERLACE_LINE (or 1) and MFGR_INTERLACE_COMPONENT (or 2). Refer to Section 8.5.1 on page 266 for further information.

The parameter num_entries specifies the number of entries in the palette. The buffer pal_data contains the palette data.

Note that the FORTRAN-77 version of GRwritelut has two routines; mgwrlut writes buffered numeric palette data and mgwclut writes buffered character palette data.

GRwritelut returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 8K on page 282.

8.10.5 Setting the Interlace Mode for a Palette: GRreqlutil

GRreqlutil sets the interlace mode for the next palette to be read. The syntax of GRreqlutil is as follows:

C:		status = GRreqlutil(pal_id, interlace_mode);
FORTRAN:	status = mgrltil(pal_id, interlace_mode)
The parameter interlace_mode specifies the interlacing that will be in effect for the next palette read operation. The valid values of interlace_mode are: MFGR_INTERLACE_PIXEL (or 0), MFGR_INTERLACE_LINE (or 1) and MFGR_INTERLACE_COMPONENT (or 2). Refer to Section 8.5.1 on page 266 for further information.

GRreqlutil may be called at anytime before the read operation of the specified palette. In addition, it may be called more than once; the interlace mode setting specified by the last call to the routine will be used for the next read operation.

GRreqlutil returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 8K on page 282.

8.10.6 Reading Palette Data: GRreadlut

GRreadlut reads data from the palette identified by the parameter pal_id. The syntax of GRreadlut is as follows:

C:		status = GRreadlut(pal_id, pal_data);
FORTRAN:	status = mgrdlut(pal_id, pal_data)
	OR	status = mgrclut(pal_id, pal_data)
The read data will be stored in the buffer pal_data, which is assumed to be sufficient to store the read palette data. The sufficient amount of space needed can be determined using the routine GRgetlutinfo. The palette data is read according to the interlacing mode set by the last call to GRreqlutil.

Note that the FORTRAN-77 version of GRreadlut has two routines; mgrdlut reads numeric palette data and mgrclut reads character palette data.

GRreadlut returns either SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 8K.

TABLE 8K - GRgetlutid, GRwritelut, GRreqlutil, and GRreadlut Parameter Lists

Routine Name

[Return Type]

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

[intn]

(mgglinf)
pal_id
int32
integer
Palette identifier

n_comps
int32*
integer
Number of components in each palette element

data_type
int32*
integer
Data type of the palette data

interlace_mode
int32*
integer
Interlace mode of the palette data

num_entries
int32*
integer
Buffer for the size of the palette

GRwritelut

[intn]

(mgwrlut/
mgwclut)
pal_id
int32
integer
Palette identifier

n_comps
int32
integer
Number of components in each palette element

data_type
int32
integer
Type of the palette data

interlace_mode
int32
integer
Interlace mode of the palette data

num_entries
int32
integer
Number of entries in the palette

pal_data
VOIDP
<valid numeric data type>(*)/ character*(*)
Buffer for the palette data to be written

GRreqlutil

[intn]

(mgrltil)
pal_id
int32
integer
Palette identifier

interlace_mode
intn
integer
Interlace mode for the next palette read operation

GRreadlut

[intn]

(mgrdlut/
mgrclut)
pal_id
int32
integer
Palette identifier

pal_data
VOIDP
<valid numeric data type>(*)/ character*(*)
Buffer for the palette data to be read

EXAMPLE 7. Writing a Palette.

This example illustrates the use of the routines GRgetlutid/mggltid and GRwritelut/mgwclut to attach a palette to a raster image and write data to it.

In this example, the program creates an image named "Image with Palette" in the file "Image_with_Palette.hdf". A palette is then attached to the image and data is written to it.

C version

FORTRAN-77 version

EXAMPLE 8. Reading a Palette.

This example illustrates the use of the routines GRgetlutinfo/mgglinf and GRreadlut/mgrclut to obtain information about a palette and to read palette data.

In this example, the program finds and selects the image named "Image with Palette" in the file "Image_with_Palette.hdf". Then the program obtains information about the palette and reads the palette data.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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