Previous: Data packet data fields, Up: The Data Stream


3.3 Data fields

Fields may have more than one dimension. A matrix-spec encapsulates the dimensionality and extents which fully qualify the size and shape of an N-dimensional matrix. Since creating a matrix-spec is a bit of a pain, the field addition and manipulation routines provide default behaviors which preclude most matrix-spec manipulation.

A matrix-spec is specified via the C structure BPMatrix which is defined in bpipe.h:

     typedef struct
     {
       size_t nd;            /* number of dimensions */
       size_t *extent;       /* nd length array with extents */
       size_t ne;            /* the total number of elements */
     } BPMatrix;

The extent array is ordered such that lower dimensions' extents come first. This similar to Fortran's array ordering, and opposite to C's. Note that the ne field is filled in by the bpipe library when verifying the matrix-spec; it should not be filled in by the application.

Fields may be resized, either by changing their extents or changing their dimensions. In addition to specifying the size of the new matrix, one must specify how the original matrix is mapped onto the new matrix. This is done by specifying the origin, dimensionality, and extents of the sub-matrix of the original data which is to be copied into the new matrix.

There are a number of utility routines which ease manipulation of BPMatrix structures: bpipe_matrix_new, bpipe_matrix_new_va, bpipe_matrix_dup, and bpipe_matrix_delete. Copies of fields' matrix-specs may be created with bpipe_hdrf_matrix or bpipe_dpktf_matrix, depending upon the type of the field.

Extent and offset arrays are simple arrays of type size_t, and can be created and deleted with malloc and free. However, a few convenience routines are provided: bpipe_extent_new, bpipe_extent_new_va, bpipe_offset_new, bpipe_offset_new_va.