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.
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.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
|
|
|
|
| |
|
|
| |||
|
|
|
Raster image identifier
| |
|
|
|
Palette index
| |
|
|
|
Palette identifier
| |
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.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.
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.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
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
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.