Previous: Data packet data fields, Up: The Data Stream
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
.