[Top] [Prev] [Next]

8.5 Programming Model for the GR Interface

As with the SD interface, the GR interface relies on the calling program to initiate and terminate access to files and data sets to support multifile access. The GR programming model for accessing a raster image is as follows:

  1. Open an HDF file.
  2. Initialize the GR interface.
  3. Open an existing raster image or create a new raster image.
  4. Perform desired operations on the raster image.
  5. Terminate access to the raster image.
  6. Terminate access to the GR interface by disposing of the interface identifier.
  7. Close the HDF file.

To access a single raster image data set in an HDF file, the calling program must contain the following calls:

C:		file_id = Hopen(filename, access_mode, n_dds_block);
		gr_id = GRstart(file_id);
		ri_id = GRselect(gr_id, ri_index);
	OR	ri_id = GRcreate(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes);
		<Optional operations>
		status = GRendaccess(ri_id);
		status = GRend(gr_id);
		status = Hclose(file_id);
FORTRAN:	file_id = hopen(filename, access_mode, n_dds_block)
		gr_id = mgstart(file_id)
		ri_id = mgselct(gr_id, ri_index)
	OR	ri_id = mgcreat(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes)
		<Optional operations>
		status = mgendac(ri_id)
		status = mgend(gr_id)
		status = hclose(file_id)
To access several files at the same time, a calling program must obtain a separate interface identifier for each file to be opened. Similarly, to access more than one raster image, a calling program must obtain a separate data set identifier for each data set.

Because every file and raster image is assigned its own identifier, the order in which files and data sets are accessed is very flexible as long as all file and raster image identifiers are individually discarded before the end of the calling program.

8.5.1 Accessing Images and Files: GRstart, GRselect, and GRcreate

In the GR interface, Hopen opens the files and GRstart initiates the GR interface. Note the contrast to the SD interface, where SDstart performs both tasks. For information on the use of Hopen, refer to Chapter 2, HDF Fundamentals. For information on SDstart, refer to Chapter 3, Scientific Data Sets (SD API).

GRstart initializes the GR interface and must be called once after Hopen and before any other GR routines are called. It takes one argument, file_id, the file identifier returned by Hopen, and returns the interface identifier gr_id or FAIL (or -1) upon unsuccessful completion. Hopen and GRstart can be called several times to access more than one file.

GRselect specifies the given image as the current image to be accessed. It takes two arguments, the GR interface identifier gr_id and the raster image index ri_index, and returns the raster image identifier ri_id or FAIL (or -1) upon unsuccessful completion. The GR interface identifier is returned by GRstart. The raster image index specifies the position of the image relative to the beginning of the file; it is zero-based, meaning that the index of the first image in the file is 0. The index of a raster image can be obtained from the image's name using the routine GRnametoindex or from the image's reference number using GRreftoindex. These routines are discussed in Section 8.8.4 on page 275 and Section 8.8.5 on page 275. The index value must be less than the total number of raster images in the file; that number can be obtained using GRfileinfo, described in Section 8.8.1 on page 274.

The parameters for GRstart and GRselect are further defined in Table 8B on page 267.

GRcreate defines a new raster image using the arguments gr_id, name, n_comps, data_type, interlace_mode, and dim_sizes. Once a data set is created, you cannot change its name, data type, dimension, or number of components. GRcreate does not actually write the image to the file; this occurs only when GRendaccess is called. Thus, failing to call GRendaccess properly will cause a loss of data.

The buffer name contains the name of the image; it must not exceed MAX_GR_NAME (or 256). The parameter n_comps specifies the number of pixel components in the raster image; it must have a value of at least 1. The parameter data_type specifies the data type of the image data; it can be any of the data types supported by the HDF library. The HDF supported data type are defined in the header file "hntdefs.h" and listed in Table 2E on page 13.

The parameter interlace_mode specifies the interlacing in which the raster image is to be written; it can be set to either MFGR_INTERLACE_PIXEL (or 0), MFGR_INTERLACE_LINE (or 1), or MFGR_INTERLACE_COMPONENT (or 2). These definitions respectively correspond to pixel interlacing, line interlacing, and component interlacing. The first two interlacing modes are illustrated for the instance of 24-bit pixel representation in Figure 7c on page 249 of Chapter 7, 24-bit Raster Images (DF24 API). Component interlacing, as the name implies, describes interlacing raster data by color component.

The parameter dim_sizes specifies the size of the two dimensions of the image. The dimension sizes must be specified; their values must be at least 1.

GRcreate returns the value of the raster image identifier if successful or FAIL (or -1) otherwise. The parameters for GRstart, GRselect, and GRcreate are further defined in (See Table 8B.).

8.5.2 Terminating Access to Images and Files: GRendaccess and GRend

GRendaccess disposes of the raster image identifier ri_id and terminates access to the data set initiated by the corresponding call to GRselect or GRcreate. The calling program must make one GRendaccess call for every GRselect or GRcreate call made during its execution. Failing to call GRendaccess for each call to GRselect or GRcreate may result in a loss of data.

GRend disposes of the GR interface identifier gr_id and terminates access to the GR interface initiated by the corresponding call to GRstart. The calling program must make one GRend call for every GRstart call made during its execution; failing to call GRend for each GRstart may result in a loss of data.

GRendaccess and GRend return SUCCEED (or 0) or FAIL (or -1). The parameters of these routines are further defined in Table 8B.

Hclose terminates access to an HDF file and should only be called after GRend has been called properly. Refer to Chapter 2, HDF Fundamentals, for a description of Hclose.

TABLE 8B - GRstart, GRselect, GRcreate, GRendaccess, and GRend, Parameter Lists

Routine Name

[Return Type]

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

[int32]

(mgstart)
file_id
int32
integer
File identifier

GRselect

[int32]

(mgselct)
gr_id
int32
integer
GR interface identifier

ri_index
int32
integer
Position of the raster image within the file

GRcreate

[int32]

(mgcreat)
gr_id
int32
integer
GR interface identifier

name
char *
character*(*)
Name of the image

n_comps
int32
integer
Number of components in each pixel

data_type
int32
integer
Data type of the pixel component

interlace_mode
int32
integer
Interlace mode to be used when writing to the data set

dim_sizes
int32 [2]
integer (2)
Array defining the size of both dimensions

GRendaccess

[intn]

(mgendac)
ri_id
int32
integer
Raster image identifier

GRend

[intn]

(mgend)
gr_id
int32
integer
GR interface identifier



[Top] [Prev] [Next]

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