Next: , Previous: bpipe_matrix_map_expand, Up: Internal Functions


A.5.25 bpipe_matrix_map_new

allocate a matrix map structure and its associated arrays.

Synopsis

     #include <bpipe/bpipe.h>
     
     
     
BPMatrixMap *bpipe_matrix_map_new( BPMatrix *src, size_t src_off[], BPMatrix *dst, size_t dst_off[], size_t extent[] );

Parameters

BPMatrix *src
source matrix spec
size_t src_off[]
offset of source submatrix to copy to destination. extent is equal to the dimensions of the source matrix.
BPMatrix *dst
destination matrix spec
size_t dst_off[]
offset of destination submatrix. extent is equal to the dimensions of the destination matrix.
size_t extent[]
the extents of the submatrix to copy. the extent of this array is equal to the dimensions of the source matrix.

Description

A matrix map structure is allocated and its associated arrays (source and destination offsets and copied submatrix extents) are constructed using the passed data (if available). It does not automatically create the new map's associated arrays if they are NULL.

Note that bpipe_matrix_map_new uses 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_matrix_map_new, it should not alter them in any fashion.

Returns

It returns a pointer to a newly create matrix map structure upon success. Upon error bpipe_errno is set and NULL is returned.

Errors

Upon error bpipe_errno is set to one of the following errors:

BPEBADARG
the passed argument is bogus or the matrix specification was illegal
BPENOMEM
a memory allocation failed