3
FLD data access library
This chapter describes the FLD data access library, which is used to access field data objects in AVS/Express:
This chapter discusses:
- Introduction, Section 3.1
- Node_Data access summary, Section 3.2
- Cell_Data access summary, Section 3.3
- Cells access summary, Section 3.4
- Cell_Set access summary, Section 3.5
- Cell_Set (specific cell types) access summary, Section 3.6
- Grid access summary, Section 3.7
- Grid_Struct access summary, Section 3.8
- Node_Data_Struct access summary, Section 3.9
- Node_Data_Struct access summary, Section 3.9
- Grid_Unif access summary, Section 3.10
- Grid_Rect access summary, Section 3.11
The AVS/Express Field Data Access Library (FLD) provides an API between the Object Manager and other AVS/Express objects (for example, visualization objects and display objects). It consists of a set of functions that provide access to AVS/Express Fields, by getting and setting values and arrays of their subobjects.
The Field data that DV base modules manipulate is stored in the Object Manager. When the method (C function) that underlies a base module is called, the function must get its input Field data from the Object Manager, perform its operation, then store the resulting output Field data back into the Object Manager so that base modules downstream in the network (or a Graphics Display Kit renderer) can find it. (A base module can copy the data back and forth from the Object Manager, but more commonly it merely gets and returns pointers to large arrays of data.)
The FLD data access library is a library (written in C) of some 140 routines that, for each subobject in the Field data type, get and set that subobject's values in the Object Manager. The FLD library is tailored to the Field data schema, making it a convenient mid-level interface to the Object Manager that is simpler to use in visualization applications than the low-level OM Object Manager library from which it is written.
There are five major types of routines in the FLD library:
- Routines that get/set Node_Data subobjects. These are generally prefixed FLDget|set_node_data_xxx, where xxx is the particular subobject (label, minmax, type, veclen, etc.) in question.
- Routines that get/set Cell_Data subobjects. These are generally prefixed FLDget|set_cell_data_xxx, where xxx is the particular subobject (label, minmax, type, veclen, etc.) in question.
- Routines that get/set Grid subobjects. These are generally prefixed FLDget|set_xxx, where xxx is the particular subobject (coord, ndim, nnodes, nspace, etc.) in question.
- Routines that get/set Cell_Set subobjects. These are generally prefixed FLDget|set_cell_set_xxx, where xxx is the particular subobject (name, nfaces, null_data, etc.) in question.
- Routines that allow you to construct, then get, set or modify your own Field data structures within a program. These routines do not have a particular prefix, for example, FLDadd_xxx, or just FLDdestroy, FLDdelete, FLDcreate, etc.
This manual does not describe each routine on a separate reference page. Rather, related routines that all get, set, copy, or otherwise access the same subobject are described on one reference page. Alphabetically, this is almost always the "FLDget" routine in the family. For example, FLDget_node_data, FLDset_node_data, FLDcopy_node_Data, and FLDget_sub_node_data are all documented under FLDget_node_data.
The above rules for finding a particular routine hold some 90% of the time. As a further aid, consult the various lookup tables that follow this section. The tables show the V definitions for the major Field subobjects beside the routines that access them.
Where a routine gets or sets an array, such as the Node_Data values array or the Grid coordinates array, it is important to understand the interaction between the array's mode, and whether you will be manipulating a copy of the array or just a pointer to the array within the Object Manager.
It is also important to understand when you must use the ARRfree routine to decrement the Object Manager's reference count for the array.
See Chapter 1.38,
OMget_array" in the
Developer's Reference manual.
See Chapter 1.9,
ARRfree" in the
Developer's Reference manual.
Include these header files to call FLD routines:
#include <avs/dtype.h>
#include <avs/om.h>
#include <avs/fld.h>
3.1.4 Compiling and linking
Link with the file $(XP_ROOT)/lib/$(MACHINE)/libfld.a.
For general information on compiling and linking modules, including how to link with the OM library, see the "Projects, Libraries and Processes" chapter in the Developer's Reference.
The FLD data access library largely follows the OM library's return code conventions.
Most routines return a status code:
|
|
|
|
|
The routine completed successfully.
|
|
|
The routine attempted to get a value from an object that exists, but that has no defined value.
|
|
|
The routine failed for any other reason (for example, the object does not exist).
|
Routines returning OMobj_id
Several routines, like OMfind_subobj, return an object id. If the routine fails, the returned value is OMnull_obj. You can test for this value with the routine OMis_null_obj. The following example attempts to get the OMobj_id of object x:
OMobj_id parent_id, x_id;
...
x_id = OMfind_subobj(parent_id, OMstr_to_name("x"), OM_OBJ_RD);
if (OMis_null_obj(x_id))
printf("Error searching for x\n");
The module source code in the modules directory shows numerous examples of the FLD library routines in use.
The source to the FLD library is included in the AVS/Express release. See src/fld. Most routines are defined in src/fld/access.c. The FLDget/free_mesh_info routines are defined in src/fld/fld_util.c.
3.2 Node_Data access summary
|
To access these subobjects...
|
|
group Node_Data { /* data at nodes */
|
int FLDget_nnodes ( OMobj_id field, int *nnodes); int FLDset_nnodes ( OMobj_id field, int nnodes);
|
int nnodes; /* number of nodes */
|
int FLDget_node_data_ ncomp ( OMobj_id field, int *nnode_comp); int FLDset_node_data_ ncomp ( OMobj_id field, int nnode_comp);
|
int nnode_data; /* number of data components */
|
int FLDset_node_data_ comp ( OMobj_id field, int comp, int veclen, char *label, char *units);
|
Data_Array node_data[nnode_data] { /* data component descriptions*/
|
|
|
|
|
|
|
3.2.1 Node_Data Data_Array access
|
To access these subobjects...
|
|
group Data_Array { /* general representation of data array */
|
|
int nvals; /*number of objects */
|
int FLDget_node_data_ veclen ( OMobj_id field, int comp, int *veclen); int FLDset_node_data_ veclen ( OMobj_id field, int comp, int veclen);
|
int veclen; /* vector length of each object */
|
int FLDget_node_data_id ( OMobj_id field, int comp, int *id); int FLDset_node_data_id ( OMobj_id field, int comp, int id);
|
int id; /* normals, pressure, coordinates, color, etc.*/
|
int FLDget_node_data_type ( OMobj_id field, int comp, int *type); 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, float *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);
|
prim values[nvals][veclen]; /* the actual data array */
|
int FLDset_node_null_flag ( OMobj_id field, int comp, int null_flag);
|
int+opt null_flag = 0; /* indicates presence of NULL data */
|
int FLDget_node_null_data ( OMobj_id field, int comp, int *null_flag, char *null_value); int FLDset_node_null_data ( OMobj_id field, int comp, char *null_value, int type);
|
prim+opt null_value; /* value assumed to be NULL data */
|
int FLDget_node_data_ minmax ( OMobj_id field, int comp, char *min, char *max); int FLDset_node_data_ minmax ( OMobj_id field, int comp, char *min, char *max, int dtype); int FLDcopy_node_minmax ( OMobj_id in_field, OMobj_id out_field, int in_comp, int out_comp); int FLDreset_node_minmax ( OMobj_id in_field, int comp);
|
prim min => cache(min_array(magnitude(values), null_flag, null_value)); /* min value of the data in each array */ prim max => cache(max_array(magnitude(values), null_flag, null_value)); /* max value of the data in each array */
|
int FLDget_node_data_ minmax_vec ( OMobj_id field, int comp, char **min, char **max, int *type, int mode); int FLDcopy_node_minmax_ vec ( OMobj_id in_field, OMobj_id out_field int in_comp, int out_comp);
|
prim min_vec[veclen] => cache(min_array(values, null_flag, null_value)); /* min extent of the data in each array */ prim max_vec[veclen] => cache(max_array(values, null_flag, null_value)); /* max extent of the data in each array */
|
int FLDget_node_data_ label ( OMobj_id field, int comp, char *label, int size); (Use FLDset_node_ data_comp to set)
|
string+nonotify labels; /* ascii strings for the labels */
|
int FLDget_node_data_ units ( OMobj_id field, int comp, char *label, int size); int FLDget_coord_units ( OMobj_id field, char *units, int size); int FLDset_coord_units ( OMobj_id field, char *units); To set Use FLDset_node_data_comp
|
string+nonotify units; /* ascii strings for the labels */
|
|
|
3.3 Cell_Data access summary
|
To access these subobjects...
|
|
group Cell_Data { /* data at cells */
|
int FLDget_ncell_sets ( OMobj_id field, int *ncell_sets); int FLDset_ncell_sets ( OMobj_id field, int ncell_sets);
|
int ncell_sets; /* number of different cell sets */
|
int FLDget_cell_set ( OMobj_id field, int i, OMobj_id *cell_set);
|
group cell_set[ncell_sets] { /* cell set descriptions */
|
int FLDget_ncells ( OMobj_id cell_set, int *ncells); int FLDset_ncells ( OMobj_id cell_set, int ncells);
|
int ncells; /* number of primitive cells */
|
int FLDget_cell_data_ncomp ( OMobj_id cell_set, int *ncell_comp); int FLDset_cell_data_ncomp ( OMobj_id cell_set, int ncell_comp);
|
int ncell_data; /* number of cell data components */
|
|
Data_Array cell_data[ncell_data] { / * data component descriptions */
|
|
|
|
|
|
|
|
|
3.3.1 Cell_Data_Poly access summary
|
To access these subobjects...
|
|
group Cell_Data_Poly { /* data at cells */
|
|
int ncell_sets; /* number of different cell sets */
|
|
group cell_set[ncell_sets] { /* cell set descriptions */
|
int FLDget_npolys( OMobj_id cell_set, int *npolys); int FLDset_npolys( OMobj_id cell_set, int npolys);
|
int npolys; /* number of polylines, polytris or polygons */ /* Note: use FLDget_ncells to get the number of primitive
(i.e., triangular) cells */
|
int FLDget_cell_data_ncomp ( OMobj_id cell_set, int *ncell_comp); int FLDset_cell_data_ncomp ( OMobj_id cell_set, int ncell_comp);
|
int ncell_data; /* number of cell data components */
|
|
Data_Array cell_data[ncell_data] { / * data component descriptions */
|
|
|
|
|
|
|
|
|
3.3.2 Cell_Data Data_Arrays
|
To access these subobjects...
|
int FLDset_cell_data_comp ( OMobj_id cell_set, int comp. int veclen, char *label, char *units);
|
group Data_Array { /* general representation of data array */
|
|
int nvals => ncells; /*number of objects */
|
int FLDget_cell_data_ veclen ( OMobj_id cell_set, int comp, int *veclen);
|
int veclen; /* vector length of each object */
|
int FLDget_cell_data_id ( OMobj_id cell_set, int comp, int *id); int FLDset_cell_data_id ( OMobj_id cell_set, int comp, int id);
|
int id; /* normals, pressure, coordinates, color, etc.*/
|
int FLDget_cell_data ( OMobj_id cell_set, int comp, int *type, char **cell_data, int *size, int mode); int FLDset_cell_data ( OMobj_id cell_set, int comp, char *cell_data, int type, int size, int mode);
|
prim values[nvals][veclen]; /* the actual data array */
|
int FLDset_cell_null_flag ( OMobj_id cell_set, int comp, int null_flag);
|
int+opt null_flag = 0; /* indicates presence of NULL data */
|
int FLDget_cell_null_data ( OMobj_id cell_set, int comp, int *null_flag, char *null_value); int FLDset_cell_null_data ( OMobj_id cell_set, int comp, char *null_value, int type);
|
prim+opt null_value; /* value assumed to be NULL data */
|
int FLDget_cell_data_ minmax ( OMobj_id cell_set, int comp, char *min, char *max); int FLDset_cell_data_ minmax ( OMobj_id cell_set, int comp, char *min, char *max, int dtype); int FLDcopy_cell_minmax ( OMobj_id in_cell_set, OMobj_id out_cell_set, int in_comp, int out_comp);
|
prim min => cache(min_array(magnitude(values), null_flag, null_value)); /* min value of the data in each array */ prim max => cache(max_array(magnitude(values), null_flag, null_value)); /* max value of the data in each array */
|
int FLDget_cell_data_ minmax_vec ( OMobj_id cell_set, int comp, char **min, char **max, int *type, int mode); int FLDcopy_cell_minmax_ vec ( OMobj_id in_cell_set, OMobj_id out_cell_set, int in_comp, int out_comp);
|
prim min_vec[veclen] => cache(min_array(values, null_flag, null_value)); /* min extent of the data in each array */ prim max_vec[veclen] => cache(max_array(values, null_flag, null_value)); /* max extent of the data in each array */
|
int FLDget_cell_data_label ( OMobj_id cell_set, int comp, char *label, int size); To set, use: int FLDset_cell_data_comp
|
string+nonotify labels; /* ascii strings for the labels */
|
int FLDget_cell_data_units ( OMobj_id cell_set, int comp, char *units, int size); To set, use: int FLDset_cell_data_comp
|
string+nonotify units; /* ascii strings for the labels */
|
|
|
|
To access these subojects...
|
|
group Cells { /* contains different cell sets */
|
int FLDget_ncell_sets ( OMobj_id field, int *ncell_sets); int FLDset_ncell_sets ( OMobj_id field, int ncell_sets);
|
int ncell_sets; /* number of cell sets */
|
int FLDget_cell_set ( OMobj_id field, int i, OMobj_id *cell_set);
|
Cell_Set cell_set[ncell_sets]; /* array of cell sets */
|
|
|
3.5 Cell_Set access summary
|
To access these subobjects...
|
int FLDadd_cell_set ( OMobj_id field, char *cell_set_name); int FLDset_cell_set ( OMobj_id cell_set, char *cell_set_name); int FLDdel_cell_set ( OMobj_id field, OMobj_id cell_set);
|
group Cell_Set { /* cell set description */
|
int FLDget_ncells ( OMobj_id cell_set, int *ncells); int FLDset_ncells ( OMobj_id cell_set, int ncells);
|
int ncells; /* number of cells */
|
int FLDget_cell_ndim ( OMobj_id cell_set, int *ndim);
|
int cell_ndim; /* cell dimensionality */
|
int FLDget_cell_set_nnodes ( OMobj_id cell_set, int *cell_nnodes);
|
int cell_nnodes; /* number of nodes per cell*/
|
int FLDget_cell_corner_ nnodes ( OMobj_id cell_set, int *cell_nnodes);
|
int cell_corner_nnodes => cell_nnodes; /*number of corner nodes per cell*/
|
|
int cell_order; /* cells' order */
|
(set by rendering routines)
|
int poly_flag; /* flag used for polylines, polytriangles */
|
int FLDget_node_connect ( OMobj_id cell_set, int **node_conn_array, int *size, int mode); int FLDset_node_connect ( OMobj_id cell_set, int *node_conn_array, int size, int mode);
|
int node_connect_list[ncells*cell_nnodes]; /* connectivity array */
|
int FLDget_cell_set_user_ name ( OMobj_id cell_set, char *name, int size); int FLDset_cell_set_user_ name ( OMobj_id cell_set, char *name);
|
|
int FLDget_cell_nprops ( OMobj_id cell_set, int *nprops); int FLDset_cell_nprops ( OMobj_id cell_set, int nprops);
|
|
int FLDget_cell_props ( OMobj_id cell_set, int **props, int *size, int mode);
|
|
|
|
3.6 Cell_Set (specific cell types) access summary
|
To access these subobjects...
|
|
Cell_Set celltype /* where celltype is Point, Line, Tri, etc. */
|
int FLDget_cell_set_nnodes ( OMobj_id cell_set, int *cell_nnodes);
|
cell_nnodes = n; /* number of nodes per cell */
|
int FLDget_cell_corner_ nnodes ( OMobj_id cell_set, int *cell_nnodes);
|
int cell_corner_nnodes = q; /*for cell_order =2 only. # corner nodes per cell*/
|
int FLDget_cell_ndim ( OMobj_id cell_set, int *ndim);
|
cell_ndim = m; /*cell dimensionality */
|
|
cell_order = p; /* cell's order: 1=nodes only, 2=mid-edge nodes */
|
int FLDget_poly_flag( OMobj_id cell_set; int *poly_flag); int FLDset_poly_flag( OMobj_id cell_set; int poly_flag);
|
poly_flag = 0; /* flag used for polylines, polytriangles, polyhedra*/
|
int FLDget_cell_type ( OMobj_id cell_set, int *cell_type); int FLDset_cell_type ( OMobj_id cell_set, int cell_type);
|
int+virtual cell_type = q; /* 1=Point, 2=Line, 3=Polyline, 4=Tri, 5=Quad, 6=Tet, 7=Hex, 8=Prism, 9=Pyr, 10=Polytri */
|
int FLDget_cell_set_name ( OMobj_id cell_set, char *name, int size); To set, use: FLDadd_cell_set or FLDset_cell_set
|
string+virtual cell_name = cell_name; /* "Point", "Line", etc. */
|
int FLDget_cell_node_uvw ( OMobj_id cell_set, float **uvw);
|
float+virtual node_uvw[ s][ t];
|
|
2D Cells end here. 3D cells include the fields below:
|
int FLDget_cell_set_nfaces ( OMobj_id cell_set, int *cell_nfaces);
|
int+virtual cell_nfaces = r; /* number of faces: Tet=4, Pyr=5, Hex=6, Prism=5 */
|
int FLDget_cell_faces ( OMobj_id cell_set, int *nfaces, int **face_nnodes, int **face_corner_ nnodes, int **node_list, int *size);
|
int+virtual cell_face_nnodes[cell_faces] = { nodes_per_face}; /*A 1D array that defines how many nodes per cell face */ int+virtual cell_face_connect[sum(cell_face_nnodes)] = { order of nodes}; /* a 1D array that defines the face connectivity */
int+virtual cell_face_corner_nnodes[nfaces]] = { corner nodes per face}; /* a 1D array that defines the corner nodes per face */
|
|
Regular cells end here. Poly cells (Polyline, Polytri, Polyhedron) include the fields below:
|
int FLDget_npolys( OMobj_id cell_set; int *npolys); int FLDset_npolys( OMobj_id cell_set; int npolys);
|
|
int FLDget_poly_connect ( OMobj_id cell_set, int **poly_conn_array, int *size, int mode); int FLDset_poly_connect ( OMobj_id cell_set, int *poly_conn_array, int size, int mode);
|
int poly_connect_list[npolys*2]; /* node connectivity array */
|
|
|
|
To access these subobjects...
|
|
group Grid { /* grid description */
|
int FLDget_nnodes ( OMobj_id field, int *nnodes); int FLDset_nnodes ( OMobj_id field, int nnodes);
|
int nnodes; /* number of nodes */
|
int FLDget_nspace ( OMobj_id field, int *nspace); int FLDset_nspace ( OMobj_id field, int nspace);
|
int nspace; /* coordinates dimension */
|
|
Data_Array coordinates { /* node coordinates (see Data_Array) */
|
|
|
|
|
int FLDget_coord ( OMobj_id field, float **coord_array, int *size, int mode); int FLDset_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);
|
float values[nvals][veclen];
|
|
float min => min_array(magnitude(values), null_flag, null_value); float max => max_array(magnitude(values), null_flag, null_value);
|
int FLDget_coord_extent ( OMobj_id field, float *min_extent, float *max_extent); int FLDset_coord_extent ( OMobj_id field, float *min_extent, float *max_extent, int nspace);
|
float min_vec[veclen] => min_array(values, null_flag, null_value); float max_vec[veclen] => max_array (values, null_flag, null_value);
|
int FLDget_coord_units ( OMobj_id field, char *units, int size); int FLDset_coord_units ( OMobj_id field, char *units);
|
|
|
|
int FLDget_xform ( OMobj_id field, float *xform); int FLDset_xform ( OMobj_id field, float *xform);
|
|
|
}; /* end of grid description */
|
3.8 Grid_Struct access summary
|
To access these subobjects...
|
|
Grid Grid_Struct { /* structured grid */
|
int FLDget_ndim ( OMobj_id field, int *ndim); int FLDset_ndim ( OMobj_id field, int ndim);
|
int ndim; /*number of dimensions */
|
int FLDget_dims ( OMobj_id field, int **dims, int *size); int FLDset_dims ( OMobj_id field, int *dims);
|
int dims[ndim]; /* dimensions */
|
int FLDget_nnodes ( OMobj_id field, int *nnodes); int FLDset_nnodes ( OMobj_id field, int nnodes);
|
int nnodes => prod(dims); /* number of nodes */
|
int FLDget_npoints ( OMobj_id field, int *npoints); int FLDset_npoints ( OMobj_id field, int npoints);
|
int npoints; /* number of points, defining grid */
|
int FLDget_points ( OMobj_id field, float **points, int *size, int mode); int FLDset_points ( OMobj_id field, float *points, int mode);
|
float points[npoints][nspace]; /* points (extents) defining grid */
|
int FLDget_grid_type ( OMobj_id field, int *grid_type); int FLDset_grid_type ( OMobj_id field, int grid_type);
|
|
|
|
3.9 Node_Data_Struct access summary
|
To access these subobjects...
|
|
Node_Data Node_Data_Struct { /* structured data*/
|
int FLDget_ndim ( OMobj_id field, int *ndim); int FLDset_ndim ( OMobj_id field, int ndim);
|
int ndim; /*number of dimensions */
|
int FLDget_dims ( OMobj_id field, int **dims, int *size); int FLDset_dims ( OMobj_id field, int *dims);
|
int dims[ndim]; /* dimensions */
|
int FLDget_nnodes ( OMobj_id field, int *nnodes); int FLDset_nnodes ( OMobj_id field, int nnodes);
|
int nnodes => prod(dims); /* number of nodes */
|
|
|
3.10 Grid_Unif access summary
|
To access these subobjects...
|
|
Grid_Struct Grid_Unif { /* uniform grid */
|
int FLDget_grid_type ( OMobj_id field, int *grid_type); int FLDset_grid_type ( OMobj_id field, int grid_type);
|
|
int FLDget_npoints ( OMobj_id field, int *npoints); int FLDset_npoints ( OMobj_id field, int npoints);
|
|
int FLDget_coord ( OMobj_id field, float **coord_array, int *size, int mode); int FLDset_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);
|
coordinates.values => get_coords_unif(ndim, dims, nspace, points);
|
|
coordinates.min => cache(min_array(magnitude(points), 0, 0));
|
|
coordinates.max => cache(max_array(magnitude(points), 0, 0));
|
int FLDget_coord_extent ( OMobj_id field, float *min_extent, float *max_extent); int FLDset_coord_extent ( OMobj_id field, float *min_extent, float *max_extent, int nspace);
|
coordinates.min_vec[veclen] => cache(min_array(points, 0, 0)); coordinates.max_vec[veclen] => cache(max_array(points, 0, 0));
|
|
|
3.11 Grid_Rect access summary
|
To access these subobjects...
|
|
Grid_Struct Grid_Rect { /* rectilinear grid */
|
int FLDget_grid_type ( OMobj_id field, int *grid_type); int FLDset_grid_type ( OMobj_id field, int grid_type);
|
|
int FLDget_npoints ( OMobj_id field, int *npoints); int FLDset_npoints ( OMobj_id field, int npoints);
|
int npoints => sum(dims);
|
int FLDget_coord ( OMobj_id field, float **coord_array, int *size, int mode); int FLDset_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);
|
coordinates.values => get_coords_rect(ndim, dims, nspace,points);
|
|
coordinates.min => cache(min_array(magnitude(points), 0, 0));
|
|
coordinates.max => cache(max_array(magnitude(points), 0, 0));
|
int FLDget_coord_extent ( OMobj_id field, float *min_extent, float *max_extent); int FLDset_coord_extent ( OMobj_id field, float *min_extent, float *max_extent, int nspace);
|
coordinates.min_vec[veclen] => cache(min_array(points, 0, 0)); coordinates.max_vec[veclen] => cache (max_array(points, 0, 0));
|
|
|