Next: , Previous: bpipe_dpktf_resize_core, Up: Data Packet Field Manipulations


A.3.14 bpipe_dpktf_resize_output

Resize the output image of a data packet field.

Synopsis

     #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 );

Parameters

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

Description

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.

Returns

It returns zero upon success, non-zero upon failure.

Errors

Upon error bpipe_errno is set to one of the following:

BPEBADARG

BPENOMEM
a memory allocation failed