FLDget_coord, FLDget_sub_coord, FLDset_coord
Synopsis
get/set the coordinate values array within a Grid
Common Version:
int FLDset_coord (
OMobj_id field,
float *coord_array,
xp_long size,
int mode);
Wide Version:
int FLDget_coord(
OMobj_id field,
float **coord_array,
xp_long *size,
int mode);
int FLDget_sub_coord (
OMobj_id field,
int ndim,
xp_long *dims,
xp_long *min_rng,
xp_long *max_rng,
float *coord_array);
Narrow Version:
int FLDget_coord_n(
OMobj_id field,
float **coord_array,
int *size,
int mode);
int FLDget_sub_coord_n (
OMobj_id field,
int ndim,
int *dims,
int *min_rng,
int *max_rng,
float *coord_array);
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.
xp_long size
xp_long *size
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.
FLDget_node_data
int ndim
FLDget_sub_coord 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_coord only. The address of 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_coord only. Addresses of two integer arrays that hold the beginning and end indices of the subarray that is being extracted. min_rng contains the start point for each ndim. max_rng contains the end point for each ndim.
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.
Examples
modules/advect.c
modules/contour.c
modules/crop.c
modules/cut_tet.c
modules/ext_edge.c
modules/iso.c
modules/pln_crop.c
modules/rd_geom.c
modules/scat_tet.c (and others)
Files
v/fld.v.
See Also