FLDFget_node_data, FLDFset_node_data, FLDFget_sub_node_data

Synopsis

get/set the values array within one component of a node data

INTEGER FLDFget_node_data (field, comp, type, node_data, size, mode)
INTEGER field(OIDSIZ)
INTEGER comp
INTEGER type
INTEGER node_data
INTEGER size
INTEGER mode

INTEGER FLDFset_node_data (field, comp, type, node_data, size, mode)
INTEGER field(OIDSIZ)
INTEGER comp
INTEGER node_data
INTEGER type
INTEGER size
INTEGER mode

INTEGER FLDFget_sub_node_data (field, comp, type, ndim, min_rng, max_rng, node_data, size, mode)
INTEGER field(OIDSIZ)
INTEGER comp
INTEGER type
INTEGER ndim
INTEGER dims
INTEGER min_rng
INTEGER max_rng
REAL node_data(...)

Description

These routines set and get the values array (prim values[nvals][veclen]) in the specified node data component.

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

The FLDFget_sub_node_data and FLDFget_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 an integer representing a pointer to a pre-allocated array, and the developer just needs to fill in the values.

Parameters

field

The integer id of a field that contains node data.

comp

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

type

In FLDFset_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:

In FLDFget_node_data and FLDFget_sub_node_data, type is an integer representing a pointer to an integer in which the primitive data type will be returned.

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

node_data

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

In FLDFget_node_data, node_data is an integer representing a pointer to an integer representing 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 an integer representing a pointer when you are done with it. See mode below.

In FLDFget_node_sub_data, node_data is returned as a 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.

To access data array you will need to use ARRFoffset function described in Appendix D of Developers Reference.

size

In FLDFset_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 FLDFget_node_data, an integer in which the total number of array values (nvals * veclen) in the node data array will be returned.

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 FLDFset_node_data:

For FLDFget_node_data:

FLDFget_sub_node_data parameters

The following parameters are used only by FLDFget_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.

ndim

FLDFget_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.

dims

FLDFget_sub_node_data only. An integer representing a pointer to an integer array that contains the dimensions of the array that is being subsetted. This array should have length = ndim.

max_rng

FLDFget_sub_node_data only. An integer representing a pointer 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.

Example 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 FLDFget_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:

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.

Example 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).

Example 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."