0) in the call to GRcreate. We refer the reader to Section 3.11 of Chapter 3, Scientific Data Sets (SD API), and to Chapter 14, HDF Performance Issues, for discussions of chunking concepts and performance related topics. The GR interface provides three routines, GRsetchunk, GRsetchunkcache, and GRgetchunkinfo, to create and maintain chunked raster images. The GR interface does not have special write/read routines similar to SDwritechunk/SDreadchunk; chunked raster images are written and read by GRwriteimage and GRreadimage.
8.11.1 Making a Raster Image a Chunked Raster Image: GRsetchunk
GRsetchunk makes the raster image, identified by the parameter ri_id, a chunked raster image according to the provided chunking and compression information. The syntax of GRsetchunk is as follows:C: status = GRsetchunk(ri_id, c_def, flags);
FORTRAN: status = mgschnk(ri_id, dim_length, comp_type, comp_prm)
The parameters c_def and flags in C or the parameters comp_type and comp_prm in FORTRAN-77 provide the chunking and compression information and are discussed below.c_def is a union of type HDF_CHUNK_DEF, which is defined as follows:
typedef union hdf_chunk_def_u
{
int32 chunk_lengths[2]; /* chunk lengths along each dim */
struct
{
int32 chunk_lengths[2];
int32 comp_type; /* compression type */
struct comp_info cinfo;
} comp;
struct
{
/* is not used in GR interface */
} nbit;
} HDF_CHUNK_DEF
Valid values of the parameter
flags are HDF_CHUNK for chunked and uncompressed data and (HDF_CHUNK | HDF_COMP) for chunked and compressed data. Data can be compressed using run-length encoding (RLE), Skipping Huffman, or GZIP compression algorithms.flags has a value of HDF_CHUNK, the chunk dimensions must be specified in the field c_def.chunk_lengths[]. If the parameter flags has a value of (HDF_CHUNK | HDF_COMP), the chunk dimensions must be specified in the field c_def.comp.chunk_lengths[] and the compression type in the field c_def.comp.comp_type. Valid values of compression type values are:
COMP_CODE_NONE (or 0) for uncompressed data
COMP_CODE_RLE (or 1) for data compressed using the RLE compression algorithm
COMP_CODE_SKPHUFF (or 3) for data compressed using the Skipping Huffman compression algorithm
COMP_CODE_DEFLATE (or 4) for data compressed using the GZIP compression algorithm
c_def.comp.cinfo.skphuff.skp_size. If using GZIP compression, the deflate level is specified in the field c_def.comp.cinfo.deflate.level. Valid deflate level values are integers from 1 to 9 inclusive. Refer to the discussion of SDsetcompress routine in Section 3.5.2 on page 45 for the definition of the structure comp_info.
In FORTRAN-77:
dim_length and the compression type in the parameter comp_type. Valid compression types and their values are defined in the "hdf.inc"file and are listed below:
COMP_CODE_NONE (or 0) for uncompressed data
COMP_CODE_RLE (or 1) for data compressed using the RLE compression algorithm
COMP_CODE_SKPHUFF (or 3) for data compressed using the Skipping Huffman compression algorithm
COMP_CODE_DEFLATE (or 4) for data compressed using the GZIP compression algorithm
comp_prm specifies the compression parameters for the Skipping Huffman and GZIP compression methods. It contains only one element which is set to the skipping size for Skipping Huffman compression or the deflate level for GZIP compression.GRsetchunk returns
SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The GRsetchunk parameters are discussed further in Table 8L on page 285.
8.11.2 Obtaining Information about a Chunked Raster Image: GRgetchunkinfo
GRgetchunkinfo is used to determine whether a raster image is chunked and how chunking is defined. The syntax of the GRgetchunkinfo routine is as follows: C: status = GRgetchunkinfo(ri_id, &c_def, &flag);
FORTRAN: status = mggichnk(ri_id, dim_length, flag)
GRgetchunkinfo retrieves chunking information about the raster image into the parameters c_def and flag in C and into the parameters dim_length and flag in FORTRAN-77. Note that only chunk dimensions are retrieved; compression information is not available.flag indicates whether the raster image is not chunked, chunked, or chunked and compressed. HDF_NONE (or -1) indicates that the raster image is not chunked. HDF_CHUNK (or 0) indicates that the raster image is chunked and not compressed. (HDF_CHUNK | HDF_COMP) (or 1) indicates that raster image is chunked and compressed with one of the allowed compression methods: RLE, Skipping Huffman, or GZIP.chunk_lengths in the union c_def with the values of the corresponding chunk dimensions. If the raster image is chunked and compressed, GRgetchunkinfo fills the array chunk_lengths in the structure comp of the union c_def with the values of the corresponding chunk dimensions. Refer to Section 8.11.1 on page 283 on GRsetchunk for specific information on the union HDF_CHUNK_DEF. In C, if the chunk length for each dimension is not needed, NULL can be passed in as the value of the parameter c_def.
In FORTRAN-77, chunk dimensions are retrieved into the array
dim_length.SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The GRgetchunkinfo parameters are discussed further in Table 8L.
8.11.3 Setting the Maximum Number of Chunks in the Cache: GRsetchunkcache
GRsetchunkcache sets the maximum number of chunks to be cached for chunked raster image. GRsetchunkcache has similar behavior to SDsetchunkcache. Refer to Section 3.11.2 on page 106 for specific information. The syntax of GRsetchunkcache is as follows:
C: status = GRsetchunkcache(ri_id, maxcache, flags);
FORTRAN: status = mgscchnk(ri_id, maxcache, flags)
The maximum number of chunks is specified by the parameter maxcache. Currently, the only valid value of the parameter flags is 0.
GRsetchunkcache returns the value of the parameter maxcache if successful and FAIL (or -1) otherwise. The GRsetchunkcache parameters are discussed further in Table 8L.
TABLE 8L - GRsetchunk, GRgetchunkinfo, and GRsetchunkcache Parameter Lists