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. 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.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 273 and Section 8.8.5 on page 273. 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 272.
The parameters for GRstart and GRselect are further defined in Table 8B on page 265.
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.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 2F on page 14.
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 247 of Chapter 7, 24-bit Raster Images (DF24 API). Component interlacing, as the name implies, describes interlacing raster data by color component. (Images created with the GR interface are actually written to disk in pixel interlace mode; any user-specified interlace mode is stored in the file with the image and the image is automatically converted to that mode when it is read with a GR interface function.)
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.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.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. 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