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


A.3.13 bpipe_dpktf_resize_core

Resize the core image of a data packet field.

Synopsis

     #include <bpipe/bpipe.h>
     
     
     
int bpipe_dpktf_resize_core( DpktField *dpktf, BPMatrix *matrix, size_t src_off[], size_t dst_off[], size_t extent[] );

Parameters

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.

Description

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.

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