Next: bpipe_dpktf_resize_output, Previous: bpipe_dpktf_offset, Up: Data Packet Field Manipulations
Resize the core image of a data packet field.
#include <bpipe/bpipe.h>int bpipe_dpktf_resize_core( DpktField *dpktf, BPMatrix *matrix, size_t src_off[], size_t dst_off[], size_t extent[] );
DpktField *dpktf
- a pointer to the data packet field to resize
BPMatrix *matrix
- specification for the core site's storage description.
size_t src_off[]
- An array containing the offset coordinates of the source submatrix to copy to the new site. The number of elements is equal to the dimensions of the source matrix. If it's
NULL
, the origin is assumed.size_t dst_off[]
- An array containing the offset coordinates of the destination submatrix in the new site. The number of elements is equal to the dimensions of the target state's matrix. If it's
NULL
, the origin is assumed.size_t extent[]
- An array containing the extents of the submatrix to copy. The number of elements is equal to the dimensions of the source matrix. If it's
NULL
, the largest submatrix which will fit is copied.
This routine allows one to specify the size of a data packet field's core image and the mapping from its input image. The input state is mapped onto the core state by copying a submatrix of the input data. The default mapping is to simply duplicate the entirety of the input matrix, without changing its extents or dimensions.
The field's core image size is determined by the passed matrix
specification. It may be created with bpipe_matrix_new
or
bpipe_matrix_new_va
, or may be extracted from an existing
data packet field. The matrix specification may also by NULL
,
indicating that the core image should have the same size as the
input image.
The mapping is composed of specifications of the offset and extent
of the source submatrix and the offset of the destination submatrix.
These are passed as arrays. If an offset array is NULL
, the
offsets in each dimension are set to ‘0’. If the submatrix
extent is NULL
, the largest possible submatrix, as determined
by the sizes of the input and core matrices and the submatrix
offsets, is copied.
This routine may be called multiple times for the same data field;
previous mappings are replaced. To return to the default input to
core mapping, the matrix specification and the submatrix offsets
and extent should be passed as NULL
.
Note that bpipe_dpktf_resize_core
uses the matrix
specification structure and all of the offset and extent arrays
directly, directing the BPipe
cleanup code to take
responsibility for freeing them. The application should not
free them, nor should it pass them to any other BPipe
routine
which takes responsibility for freeing them. After passing them to
bpipe_dpktf_resize_core
, it should not alter them in any
fashion.
Note that this routine does not do the actual mapping, it just
stores the mapping specifications. bpipe_map
does the
mapping. Once a BPipe
is mapped with bpipe_map
,
resizing data packet fields has no effect.
It returns zero upon success, non-zero upon failure.
Upon error bpipe_errno
is set to one of the following:
BPEBADARG
BPENOMEM