Next: bpipe_dpktf_type, Previous: bpipe_dpktf_resize_core, Up: Data Packet Field Manipulations
Resize the output image of a data packet field.
#include <bpipe/bpipe.h>int bpipe_dpktf_resize_output( DpktField *dpktf, BPMatrix *matrix, size_t src_off[], size_t dst_off[], size_t extent[], BPipeOutput *bpo );
DpktField *dpktf
- a pointer to the data packet field to resize
BPMatrix *matrix
- specification for storage description at destination site.
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.BPipeOutput *bpo
- the output channel
This routine allows one to specify the size of a data packet field's output image and the mapping from its core image. The core state is mapped onto the output state by copying a submatrix of the core data. The default mapping is to simply duplicate the entirety of the core matrix, without changing its extents or dimensions.
The field's output image size is determined by the passed matrix
specification, which is duplicated. 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 output
image should have the same size as the core 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 core and output 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 core to
output mapping, the matrix specification and the submatrix offsets
and extent should be passed as NULL
.
This routine should be called after all calls to
bpipe_dpktf_resize_core
for this data packet field have been
made. The sizes of the core and output images must be known in
in order to validate the mapping between them.
Note that bpipe_dpktf_resize_output
uses the matrix
specification structure and all of the offset and extent arrays as
is, 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_output
, 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