OMget_sub_barray and OMset_sub_barray

Synopsis

int  OMget_sub_barray (object_id,  ndim,  size,  min,  max,  bvalue);
int  OMget_sub_sarray (object_id,  ndim,  size,  min,  max,  svalue);
int  OMget_sub_iarray (object_id,  ndim,  size,  min,  max,  ivalue);
int  OMget_sub_farray (object_id,  ndim,  size,  min,  max,  fvalue);
int  OMget_sub_rarray (object_id,  ndim,  size,  min,  max,  rvalue);

int  OMset_sub_barray (object_id,  ndim,  size,  min,  max,  bvalue);
int  OMset_sub_sarray (object_id,  ndim,  size,  min,  max,  svalue);
int  OMset_sub_iarray (object_id,  ndim,  size,  min,  max,  ivalue);
int  OMset_sub_farray (object_id,  ndim,  size,  min,  max,  fvalue);
int  OMset_sub_rarray (object_id,  ndim,  size,  min,  max,  rvalue);

OMobj_id  object_id;
int  ndim,  *size,  *min,  *max;
unsigned char  *bvalue;
short  *svalue;
int  *ivalue;
float  *fvalue;
double  *rvalue;

Description

These routines get and set a subarray of an array object. With the ndim and size parameters, you specify the number of dimensions in the array and the size of each dimension. With the min and max parameters, you specify the range to retrieve or set in each dimension.

The routines get different types of arrays.

Arguments

object_id

The id of an array object.

ndim

The number of dimensions in the array object.

size

An array specifying the size of each dimension of the array object. The first value in this array is the fastest varying dimension in the array. This is the value that is the rightmost in the V specification for the dimensions.

min
max

Arrays specifying, respectively, the minimum and maximum indices to retrieve/set in each dimension of the array. The first value in each of these arrays is the rightmost index in the V specification. AVS/Express uses zero-based indexing; i.e., the index of the first value in a dimension is 0. Note that the value specified by the maximum dimension is not included in the values retrieved or set in the array. This is not the same as the ":" range operator in the V language which does include the maximum value. For example, to get the first value in a dimension, you would set the min to 0 and the max to 1.

barray
sarray
iarray
farray
rarray

An output argument for get routines, an input argument for set routines containing the specified subarray. The number of values returned or set is the product of the range ( max - min ) in each dimension.

Returned value

The status code (see Return Status ).

Example

In the V, array data is defined as follows:

group grp1 {
int h=400;
int w=300;
int ncomps=3;
byte data[h][w][ncomps] => read.data_out;
};

A program can access a subarray of data, as follows:

OMobj_id  grp1_id, data_id;
int h, w, ncomps;
unsigned char*subarray;
int ndim=3, size[3], min[3], max[3];
int status;
...
stat = OMget_name_int_val(grp1_id, OMstr_to_name("h"), &h);
stat += OMget_name_int_val(grp1_id, OMstr_to_name("w"), &w);
stat += OMget_name_int_val(grp1_id, OMstr_to_name("ncomps"),
&ncomps);
if (stat != 3) return(0);
size[0] = ncomps;
size[1] = w;
size[2] = h;
subarray = (unsigned char *) malloc (150 * 150 * ncomps);
min[0] = 0; /* Range for the ncomps dimension: 0-3. */
max[0] = ncomps;
min[1] = 0; /* Range for the w dimension: 0-150. */
max[1] = 150;
min[2] = 0; /* Range for the h dimension: 0-150. */
max[2] = 150;
data_id = OMfind_subobj(grp1_id, OMstr_to_name("data"),
OM_OBJ_RD);
status = OMget_sub_barray(data_id, 3, size, min, max,
subarray);
if (status == 0) {
return(0); /* value is not set */
}