FLDget_node_data

Synopsis

get/set the values array within one component of a Node_Data Data_Array


int FLDget_node_data (
OMobj_id field,
int comp,
int *type,
char **node_data,
int *size,
int mode);

int FLDset_node_data (
OMobj_id field,
int comp,
char *node_data,
int type,
int size,
int mode);

int FLDget_sub_node_data (
OMobj_id field,
int comp,
int *type,
int ndim,
int *dims,
int *min_rng,
int *max_rng,
char *node_data);

Description

These routines set and get the values array (prim values[nvals][veclen]) in the Data_Array associated with one component of a Node_Data.

FLDget_sub_node_data will retrieve a subset of the values array, as would be necessary if you were, for example, cropping a field.

The FLDget_sub_node_data and FLDget_node_data routines can be used for both getting and setting the values array. When setting with a "get" routine (mode = OM_GET_ARRAY_WR or OM_GET_ARRAY_RW), these routines return a pointer to a pre-allocated array, and the developer just needs to fill in the values.

Parameters

OMobj_id field

The OMobj_id of a field that contains a Node_Data subobject.

int comp

An integer that sets which component [0-n] of the Node_Data to get/set.

int *type
int type

In FLDset_node_data, type is an integer that sets the values array's primitive data type. Constants for the possible values are defined in avs/dtype.h as follows:

Constant

 

Value

 

DTYPE_CHAR

0

DTYPE_BYTE

1

DTYPE_SHORT

2

DTYPE_INT

3

DTYPE_FLOAT

4

DTYPE_DOUBLE

5

DTYPE_UNSET

DNTYPES+1

 

In FLDget_node_data and FLDget_sub_node_data, type is a pointer to an integer in which the primitive data type will be returned.

In FLDget_node_data, the routine returns the type, except for the case where the array was first created with the FLDget_node_data routine (mode = OM_GET_ARRAY_WR). In this case, type has to be specified by the caller.

char *node_data
char **node_data

In FLDset_node_data, *node_data is a pointer to an array argument that contains the node data array you want to set in the Object Manager. See mode below.

In FLDget_node_data, node_data is a pointer to a pointer which will be filled in with the address of an array that contains the node data. You must call ARRfree() on the resulting pointer when you are done with it. See mode below.

In FLDget_node_sub_data, node_data is returned as a pointer to an array that will contain a copy of the subarray. The caller has to allocate memory of sufficient size to hold this subarray. The caller also has to free it.

int size
int *size

In FLDset_node_data, an integer that sets the total number of array values (nvals * veclen) to create. A [100][3] array would have size=300.

In FLDget_node_data, a pointer to an integer in which the total number of array values (nvals * veclen) in the node data array will be returned.

int mode

An integer constant that establishes the access mode for the array subobject. Constants for the possible values are defined in avs/om.h as follows.

For FLDset_node_data:

Mode

 

Value

 

Meaning

 

OM_SET_ARRAY_COPY

0

Copy the array into the Object Manager

OM_SET_ARRAY_FREE

1

If possible, do not copy the array. Instead, set the object's array pointer to node_data. AVS/Express copies the array anyway if the function is running in an external process or if data type conversion is required.

AVS/Express manages the array and will determine when the array can be freed.

You must allocate space for the array with a call to ARRalloc.

OM_SET_ARRAY_STATIC

2

If possible, do not copy the array. Instead, set the object's array pointer to node_data. AVS/Express copies the array anyway if the function is running in an external process or if data type conversion is required.

AVS/Express does not manage the array. You must ensure that the array is valid for the life of the object or until the object replaces the array.

 

For FLDget_node_data:

Mode

 

Value

 

Meaning

 

OM_GET_ARRAY_RD

0

The program intends to read the array, but not write to it.

OM_GET_ARRAY_WR

1

The program intends to write to the array, completely replacing it, but not read it.

OM_GET_ARRAY_RW

2

The program intends to both read and write to the array.

OM_GET_ARRAY_RD_
COPY

3

The program requires a copy of the array for its own, private use (reading or writing).

 

FLDget_sub_node_data parameters

The following parameters are used only by FLDget_sub_node_data and allow you to place an arbitrary "offset mask" over the values array, which is stored in the Object Manager as a 1D array, so that you can extract nearly any subset of a Data_Array values array. See the examples after the parameter listings for clarification.

int ndim

FLDget_sub_node_data only. An integer that specifies the number of dimensions to impose upon the array. To view the array as 2D, specify
ndim=2. To view it as 3D, specify ndim=3, etc.

int *dims

FLDget_sub_node_data only. A pointer to an integer array that contains the dimensions of the array that is being subsetted. This array should have
length = ndim.

int *min_rng
int *max_rng

FLDget_sub_node_data only. Pointers to two integer arrays of length ndim that hold the beginning and ending indices of the subarray that is being extracted. min_rng contains the start point for each dimension. max_rng contains the end point for each dimension.

Note: Although it may not seem intuitive, the first value in each of these arrays is the rightmost index in the V specification. AVS/Express uses zero-based indexing (that is, the index of the first value in a dimension is 0).

All "extracted" data values must be logically contiguous. That is, it is possible to extract the first and second veclen subcomponents, but not the second and fourth. Similarly, it is possible to extract the 20th through 100th node data values, but not the 20th through 30th, plus the 40th through 100th.

FLDget_sub_node_data
examples

All of these examples use the same field. It is a 2D field. It has dims = {10, 20}, and its values array has veclen = 3. It has nnodes = 200 (10x20).

This array is stored in the OM as a 1D array. The indices into this array look like this:

dims[0] = x dimension
dims[1] = y dimension
veclen

So, the array is stored in "row major" order, where the veclen axis varies fastest as you go through memory, then the dims[0], then dims[1], and so on.

Or, re-written to use the specific example: [20] [10] [3]

For example, a 1D array 600 elements long in this order:

0,0,a
0,0,b
0,0,c
0,1,a
0,1,b
0,1,c
0,2,a
0,2,b
0,2,c
...
0,9,a
0,9,b
0,9,c
1,0,a
1,0,b
1,0,c
...
19,9,a
19,9,b
19,9,c

#1: Cropping

In this first example, we will crop the 2D field. The field will be cropped from 5 to 8 inclusive in x, and from 12 to 18 inclusive in y. We want all of the data at each node. These are the values for the FLDget_sub_node_data ndim, dims, min_range and max_range parameters that will extract the correct subset of the input field's Node_Data for the output field:

 

FH298341.gif

ndim = 3

because we want to view the 1D array as a 3D indexed array.

dims = {3, 10, 20}

because these are the 3D dimensions we want to impose on this array.

min_range = {0, 5, 12}
max_range = {3, 8, 18}

because we want to extract from 0-3 in the first "dimension" (the complete veclen), from 5-8 in x, and from 12 to 18 in y.

#2 extract scalar

In the second example, we will perform an extract scalar operation on this same field. We want to extract just the second subcomponent.

There are two structures we could impose upon the same 1D array. Either solution would achieve the same effect.

Solution #1--View it as a 3D indexed array:

ndim = 3

view the 1D array as a 3D indexed array.

dims = {3, 10, 20]

because these are the correct 3D dimensions to impose on this array.

min_range = {1, 0, 0}
max_range = {2, 10, 20}

because we want to extract just the 1-2 in the first "dimension" (the second vector subcomponent), from 0 to 10 in x, and from 0 to 20 in y (i.e., from the whole array.

Solution #2--View it as 2D indexed array:

ndim = 2

view the 1D array as 2D indexed array (veclen x nnodes).

dims = {3, 200}

because these are the correct 2D dimensions to impose on this array.

min_range = {1, 0}
max_range = {2, 200}

because we want to extract just the 1-2 in the first "dimension" (the second vector subcomponent), from 0 to 200 (i.e., from the whole array).

#3 extract first 10 nodes

In the third example, will want to take just the first ten nodes from the field. We want the complete vector at each node.

Like example #2, this could be done by treating the array as either 2D or 3D. This is the 2D solution:

ndim = 2

view the 1D array as 2D indexed array (veclen x nnodes).

dims = {3, 200}

because these are the correct 2D dimensions to impose on this array.

min_range = {0, 0}
max_range = {3, 10}

because we want to extract from 0-3 in the first "dimension" (all three vector subcomponents, and just the 0-10 nodes in the second "dimension."

Examples

FLDget_node_data

This example, a fragment from modules/thresh.c, shows threshold retrieving the values array from its input field.


int FUNCthreshold (in, check_vec, check_comp, thresh_vec,
below, min_val, above, max_val, new_null_value, out)
OMobj_id in, out;
int check_vec, check_comp, thresh_vec;
...
{
int nnodes, size, check_veclen, thresh_veclen, data_id;
int data_type, data_type1, null_flag;
char *check_data, *thresh_data, *out_node_data;
double null_value, new_nv;
...
if (FLDget_nnodes(in, &nnodes)!= 1) {
ERR_RETURN("cannot get nnodes");
}
...
if (FLDget_node_data_veclen(in, thresh_vec, &thresh_veclen)!= 1) {
ERR_RETURN("Error getting veclen");
}
if (FLDget_node_data_veclen(in, check_vec, &check_veclen)!= 1) {
ERR_RETURN("Error getting veclen");
}
...
if (FLDget_node_data(in, check_vec, &data_type, &check_data,
&size, OM_GET_ARRAY_RD)!= 1) {
ERR_RETURN("cannot get node data");
}
...

FLDget_node_data

This example, a fragment from modules/orthoslc.c, shows orthoslice using FLDget_node_data to set the type and establish pointers to its output field. In supplied modules, FLDget_node_data is usually used instead of FLDset_node_data to essentially prepare the empty array for the data that the UTIL utility function will later calculate.