[Top] [Prev]

8.11 Chunked Raster Images

The GR interface also supports chunking in a manner similar to that of the SD interface. There is one restriction on a raster image: it must be created with MFGR_INTERLACE_PIXEL (or 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.

In C:

The parameter 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.

If the parameter 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
If using Skipping Huffman compression, the skipping size is specified in the field 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:

Chunk dimensions are specified in the array 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
The parameter 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.

The value returned in the parameter 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.

In C, if the raster image is chunked and not compressed, GRgetchunkinfo fills the array 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.

GRgetchunkinfo returns 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.

If GRsetchunkcache is not called, the maximum number of chunks in the cache is set to the number of chunks along the fastest-changing dimension. Since GRsetchunkcache is similar to the routine SDsetchunkcache, refer to Section 3.11.2 on page 106 for more detailed discussion of the routine's behavior.

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

Routine Name

[Return Type]

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

[intn]

(mgschnk)
ri_id
int32
integer
Raster image identifier

c_def
HDF_CHUNK_DEF
N/A
Chunk definition

flags
int32*
N/A
Compression flags

dim_length
N/A
integer
Chunk dimensions array

comp_type
N/A
integer
Type of compression

comp_prm
N/A
integer
Compression parameters array

GRgetchunkinfo

[intn]

(mggichnk)
ri_id
int32
integer
Raster image identifier

c_def
HDF_CHUNK_DEF
N/A
Chunk definition

dim_length
N/A
integer
Chunk dimensions array

flag
int32
integer
Compression flag

GRsetchunkcache

[intn]

(mgscchnk)
ri_id
int32
integer
Raster image identifier

maxcache
int32
integer
Maximum number of chunks to cache

flags
int32
integer
Flags determining routine behavior



[Top] [Prev]

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