[Top] [Prev] [Next] [Bottom]

8.9 Reading and Writing Palette Data Using the GR API

The GR API library includes routines that read, write and access information about palette data attached to general raster 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 API routines.

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

8.9.1 Obtaining a Palette ID: GRgetlutid

The GRgetlutid function takes two arguments, the raster image identifier of the image that has the target palette attached to it and the index of the target palette, and returns the palette identifier corresponding to the specified image as its return value.

The syntax of the GRgetlutid function is:

C:		pal_id = GRgetlutid(ri_id, lut_index);

FORTRAN:	pal_id = mggltid(ri_id, lut_index)

8.9.2 Obtaining Palette Information: GRgetlutinfo

The GRgetlutinfo function takes one input argument, the identifier of the palette, and returns the number of components of the palette, the type of data contained in the palette, the interlace mode of the stored palette data and the number of entries in the palette in the ncomp, data_type, interlace_mode and num_entries arguments respectively. It returns a status code of 0 on successful completion and -1 if an error occurred.

The syntax of the GRgetlutinfo function is:

C:		status = GRgetlutinfo(pal_id, &ncomp, &data_type, &interlace_mode,
			num_entries);

FORTRAN:	 status = mgglinf(pal_id, ncomp, data_type, interlace_mode,
			num_entries)

8.9.3 Retrieving the Reference Number of the Specified Palette: GRluttoref

The GRluttoref routine takes one argument, a palette identifier, and returns the reference number of the palette. GRluttoref is commonly used to annotate the palette or including the palette within a vgroup

There is currently no Fortran-77 version of the GRluttoref.

TABLE 8L GRluttoref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRluttoref

pal_id

int32

None

Image identifier.

8.9.4 Writing Palette Data: GRwritelut

The GRwritelut function takes six input arguments, the identifier of the palette, the number of components of the palette, the type of data contained in the palette, the interlace mode of the stored palette data, the number of entries in the palette and the buffered palette data to be written in the pal_id, ncomp, data_type, interlace_mode, num_entries and pal_data arguments respectively. It writes the palette data into the palette that is attached to the image specified by the given image identifier and returns a status code of 0 on successful completion and -1 if an error occurred.

The syntax of the GRwritelut function is:

C:		status = GRwritelut(pal_id, ncomp, data_type, interlace_mode,
		num_entries, pal_data);

FORTRAN:	status = mgwrlut(pal_id, ncomp, data_type, interlace_mode,
		num_entries, pal_data)

There are two Fortran-77 versions of GRwritelut: mgwrlut and mgwclut. The mgwrlut routine writes buffered numeric palette data and mgwclut writes buffered character palette data.

8.9.5 Reading Palette Data: GRreadlut

The GRreadlut function takes two arguments, a palette identifier and a buffer large enough to store the read palette data. It reads the data into the buffer pointed to by the pal_data argument and returns a status code of 0 on successful completion and -1 if an error occurred. The palette data is read according to the interlacing mode set by the last call to GRreqlutil.

The syntax of the GRreadlut function is:

C:		status = GRreadlut(pal_id, pal_data);

FORTRAN:	status = mgrdlut(pal_id, pal_data)

There are two Fortran-77 versions of GRreadlut: mgrdlut and mgrclut. The mgrdlut routine reads numeric palette data and mgrclut reads character palette data.

TABLE 8M GRgetlutid, GRgetlutinfo, GRwritelut and GRreadlut Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRgetlutinfo

(mgglinf)

pal_id

int32

integer

Palette identifier.

ncomp

int32*

integer (*)

Buffer for the number of components in each palette element.

data_type

int32*

integer (*)

Buffer for the data type of the palette data.

interlace

int32*

integer (*)

Buffer for the interlace type of the palette data.

num_entries

int32*

integer (*)

Buffer for the size of the palette.

GRwritelut

(mgwrlut/

mgwclut)

pal_id

int32

integer

Palette identifier.

ncomp

int32

integer

Number of components in each palette element.

data_type

int32

integer

Type of the palette data.

interlace

int32

integer

Interlace type of the palette data.

num_entries

int32

integer

Number of entries in the palette.

pal_data

VOIDP

<valid numeric data type>

Palette data to be written.

GRgetlutid

(mggltid)

ri_id

int32

integer

General raster image identifier.

index

int32

integer

Image index.

GRreadlut

(mgrdlut/

mgrclut)

pal_id

int32

integer

Palette identifier.

pal_data

VOIDP

<valid numeric data type>

Buffer for the palette data to be read.

EXAMPLE 11. Reading and Writing a Palette and Obtaining Palette Information

In the following code examples, GRgetlutid, GRgetlutinfo, GRwritelut and GRreadlut are used to write a palette to an HDF file named "Example12.hdf", then read it into a buffer and retrieve information about it.

C:

#include "hdf.h"
#include "mfgr.h"

#define X_LENGTH 20
#define Y_LENGTH 20

main( )
{
	int32 gr_id, ri_id, file_id, pal_id, status, num_entries;
	int32 data_type, ncomp, num_comp, interlace_mode; 
	int32 r_num_entries, r_data_type, r_ncomp, r_interlace_mode; 
	uint8 palette_data[256*3];
	uint8 r_palette_data[256*3];
	intn i, j;
	int32 dims[2];

	/* Create and open the file. */
	file_id = Hopen("Example11.hdf", DFACC_CREATE, 0);

	/* Initiate the GR interface. */
	gr_id = GRstart(file_id);

	/* Define the number of components and dimensions of the image. */
	ncomp = 1;
	dims[0] = X_LENGTH;
	dims[1] = Y_LENGTH;
	interlace_mode = MFGR_INTERLACE_PIXEL;

	/* Create the image. */
	ri_id = GRcreate(gr_id, "Image_12", ncomp, DFNT_UINT8, 
						interlace_mode, dims);

	/* Initialize the palette to grayscale. */
	for (i = 0; i < 256; i++) {
	 	palette_data[i * 3] = i;
	 	palette_data[i * 3 + 1] = i;
	 	palette_data[i * 3 + 2] = i;
	}

	/* Set palette characteristics. */
	data_type = DFNT_UINT8;
	num_entries = 256;
	num_comp = 3;

	/* Get the id for the palette. */
	pal_id = GRgetlutid(ri_id, 0);

	/* Write the palette to file. */
	status = GRwritelut(pal_id, num_comp, data_type, 
							interlace_mode, num_entries, 
						(VOIDP)palette_data);

	/* Read the palette information. */
	status = GRgetlutinfo(pal_id, &r_ncomp, &r_data_type, 
							&r_interlace_mode, &r_num_entries); 

	/* Read the palette data. */
	status = GRreadlut(pal_id, (VOIDP)r_palette_data);

	/* Terminate access to the image. */
	status = GRendaccess(ri_id);

	/* Terminate access to the GR interface. */
	status = GRend(gr_id);

	/* Close the file. */
	status = Hclose(file_id);

}

FORTRAN:

	 PROGRAM READ WRITE PALETTE

      integer*4 gr_id, ri_id, file_id, pal_id, status
      integer*4 num_entries, data_type, ncomp, interlace_mode
      integer*4 r_interlace_mode, r_num_entries, r_data_type
      integer*4 r_ncomp, ncomp, num_comp, dims(2)
      character palette_data(256*3)
      character r_palette_data(256*3)
      integer i
      integer*4 MFGR_INTERLACE_PIXEL, DFNT_CHAR8, X_LENGTH
      integer*4 Y_LENGTH
      parameter(MFGR_INTERLACE_PIXEL = 0, DFNT_CHAR8 = 4,
     +          X_LENGTH = 20, Y_LENGTH = 20)
      integer hopen, hclose, mgstart, mgcreat, mgwrlut
      integer mggltid, mgglinf, mgrdlut, mgendac, mgend

C     Create and open the file.
      file_id = hopen(`Example11.hdf', DFACC_CREATE, 0)

C     Initiate the GR interface.
      gr_id = mgstart(file_id)

C     Define the Number of components and dimensions of the image
C     and palette to be created.
      ncomp = 1
      num_entries = 256
      num_comp = 3
      dims(1) = X_LENGTH
      dims(2) = Y_LENGTH
      interlace_mode = MFGR_INTERLACE_PIXEL
      data_type = DFNT_CHAR8

C     Create the image.
      ri_id = mgcreat(gr_id, `Image_12', ncomp, data_type,
     +                interlace_mode, dims)

C     Initialize the palette to greyscale.
      do 10, i = 1, 256
        palette_data((i - 1) * 3 + 1) = char(i - 1)
        palette_data((i - 1) * 3 + 2) = char(i - 1)
        palette_data((i - 1) * 3 + 3) = char(i - 1)
10    continue

C     Get the identifier for the palette.
      pal_id = mggltid(ri_id, 0)

C     Write the palette to the HDF file.
      status = mgwrlut(pal_id, num_comp, data_type,
     +                 interlace_mode, num_entries,
     +                 palette_data)

C     Read the palette information.
      status = mgglinf(pal_id, ncomp, data_type,
     +                 interlace_mode, num_entries)

C     Read the palette data.
      status = mgrdlut(pal_id, r_ncomp, r_data_type,
     +                 r_interlace_mode, r_num_entries,
     +                 r_palette_data)

C     Terminate access to the image.
      status = mgendac(ri_id)

C     Terminate access to the GR interface.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)

      end




[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.