GRfileinfo retrieves the number of images and file attributes in a file. GRgetiminfo provides information about individual images. To retrieve information about all images in a file, a calling program can use GRfileinfo to determine the number of images, followed by repeated calls to GRgetiminfo to obtain information about each image.
GRnametoindex or GRreftoindex can be used to obtain the index of a raster image in a file knowing its name or reference number, respectively. Refer to Section 8.2.1 on page 262 for a description of the raster image index and reference number. GRidtoref is used when the reference number of an image is required by another routine and the raster image identifier is available.
These routines are described individually in the following subsections.
8.8.1 Obtaining Information about the Contents of a File: GRfileinfo
GRfileinfo retrieves the number of raster images and the number of file attributes contained in a file. This information is often useful in index validation, sequential searches, or memory allocation. The syntax of GRfileinfo is as follows:C: status = GRfileinfo(gr_id, &n_images, &n_file_attrs);
FORTRAN: status = mgfinfo(gr_id, n_images, n_file_attrs)
The number of images in the file and the total number of file attributes will be stored in the arguments n_images and n_file_attrs, respectively. SUCCEED (or 0) if successful or FAIL (or -1) otherwise. The parameters for GRfileinfo are further described in Table 8G on page 275.
8.8.2 Obtaining Information about an Image: GRgetiminfo
It is impossible to allocate the proper amount of memory to buffer the image data when the number of components, dimension sizes, and/or data type of the image are unknown. The routine GRgetiminfo retrieves this required information. To access information about an image, the calling program must contain the following:C: status = GRgetiminfo(ri_id, name, &n_comps, &data_type, &interlace_mode, dim_sizes, &n_attrs);
FORTRAN: status = mggiinf(ri_id, name, n_comps, data_type, interlace_mode, dim_sizes, n_attrs)
GRgetiminfo takes a raster image identifier as input, and returns the name, number of components, data type, interlace mode, dimension size, and number of attributes for the corresponding image in the arguments name, n_comps, data_type, interlace_mode, dim_sizes, and n_attrs respectively. The number of components of an image array element corresponds to the order of a vdata field, therefore this implementation of image components in the GR interface is flexible enough to accommodate any representation of pixel data. The calling program determines this representation; the GR interface recognizes only the raw byte configuration of the data. The attribute count will only reflect the number of attributes assigned to the image array; file attributes are not included.SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are further defined in Table 8G.
TABLE 8G - GRfileinfo and GRgetiminfo Parameter Lists
ri_id, or FAIL (or -1) upon unsuccessful completion. The syntax of GRidtoref is as follows:
C: ref = GRidtoref(ri_id);
FORTRAN: ref = mgid2rf(ri_id)This routine is further defined in Table 8H on page 276.
8.8.4 Obtaining the Index of a Raster Image from Its Reference Number: GRreftoindex
GRreftoindex returns either the index of the raster image specified by its reference number, ref, or FAIL (or -1) upon unsuccessful completion. The syntax of GRreftoindex is as follows:C: ri_index = GRreftoindex(gr_id, ref);
FORTRAN: ri_index = mgr2idx(gr_id, ref)
This routine is further defined in Table 8H.
8.8.5 Obtaining the Index of a Raster Image from Its Name: GRnametoindex
GRnametoindex returns the index of the raster image specified by its name or FAIL (or -1) upon unsuccessful completion. The syntax of GRnametoindex is as follows:C: ri_index = GRnametoindex(gr_id, name);
FORTRAN: ri_index = mgr2idx(gr_id, name)
This routine is further defined in Table 8H.
TABLE 8H - GRidtoref, GRreftoindex, and GRnametoindex Parameter Lists
In this example, the program gets the number of images in the file using the routine GRfileinfo/mgfinfo. For each image, the program then obtains and displays its name, number of components, data type, interlace mode, dimension sizes, and number of attributes using the routine GRgetiminfo/mggiinf.
C version