FLDget_coord

Synopsis

get/set the coordinate values array within a Grid


int FLDget_coord (
OMobj_id field,
float **coord_array,
int *size,
int mode);

int FLDget_sub_coord (
OMobj_id field,
int ndim,
int *dims,
int *min_rng,
int *max_rng,
float *coord_array);

int FLDset_coord (
OMobj_id field,
float *coord_array,
int size,
int mode);

Description

These routines set and get the coordinate values array (float values[nvals][veclen]) in a Grid.

FLDget_sub_coord retrieves a subset of the values array, as would be necessary if you were, for example, cropping an irregular field.

The FLDget_sub_coord and FLDget_coord 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.

Note: These routines also get and set cylindrical and spherical coordinate arrays. Cylindrical coordinates are stored as radius, theta, z. Spherical coordinates are stored as angle, angle, radius.

Note: Coordinates can also be obtained as part of the omnibus FLDget_mesh_info routine.

Parameters

OMobj_id field

The OMobj_id of a field that contains a Grid.

float **coord_array
float *coord_array

In FLDset_coord, coord_array is the address of the coordinate data array that you want to set in the Object Manager. See mode below.

In FLDget_coord, the *coord_array is filled in on return with a pointer to the coordinate data. You must call ARRfree() on this pointer when you are done with it. See mode below.

In FLDget_sub_coord, coord_array is the address of an array of floats large enough to hold the subarray; FLDget_sub_coord copies the subarray into the specified memory. The caller must manage the memory in this case.

int size
int *size

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

In FLDget_coord, a pointer to an integer in which the total number of array values (nvals * veclen) in the coordinate values 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_coord:

Mode

 

Value

 

eaning

 

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

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

 

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_coord parameters

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

For examples of these three parameters in use, see the following reference. Look for the discussion and examples of the parameters of the same name for FLDget_sub_node_data.