diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.05 b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.05 new file mode 100644 index 0000000000..b92bb1c988 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.05 @@ -0,0 +1,4543 @@ +README_USERD_2.05 +================= +-------------------------------------- +EnSight User Defined Reader Capability ===> (API 2.05) +-------------------------------------- +A user defined reader capability is included in EnSight which can allow +otherwise unsupported structured or unstructured data to be read. The user +defined reader capability utilizes dynamic shared libraries composed of +routines defined in this document but produced by you, the user, (or some +third party). This capability is currently available for dec, ibm, hp, sgi, +sun, linux, alpha linux, and NT servers. + +You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0 +for a discussion of the differences between API 1.0 and API 2.*. + +***>> API 2.05 additional capabilities (beyond API 2.04): +Routines to handle material species. + USERD_get_number_of_species + USERD_get_matsp_info + +Routines to handle variable extraction parameters after a read, and then +update the variables accordingly. Similar to the extra GUI capabilities +(which are processed before a read). (Can actually be added to pre-2.05 readers) + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + +Routines to obtain rigid body values from a reader. +(Routines were added - EnSight is now using for Nastran and STL readers + with Dynasty rigid body motion data file) + USERD_rigidbody_existence + USERD_rigidbody_values + +Routine that lets reader know when EnSight is getting the right side of a time +interval for variable interpolation between steps. Not generally needed for +most readers - however, may be needed for those that implement rigid body, and +wish to cache left and right timespan information for interpolation within the +reader itself. (Can actually be added to pre-2.05 readers) + USERD_set_right_side + + +***>> API 2.04 additional capabilities (beyond API 2.03): +Routines to handle failed elements. Basically +a.One routine to return a flag indicating the existence of + failed elements in at least one part in at least one + timestep in the model. +b.A second routine to return a matrix of flags indexed by part and + element type indicating which parts and element types have failed + elements at the current time step. +c.Finally a third routine to return an array of flags for a given + part and element type that is number of elements of that type long + indicating which elements have failed, and which have not failed. + + +***>> API 2.03 additional capabilities (beyond API 2.01): +1. Routines to handle materials +2. Routines to handle nsided and nfaced elements +3. Modified routine to handle structured ranges + + +**************************************************************************** +Note: The dummy_gold reader, the Ensight Gold example reader, the + ABAQUS_ODB reader and the LS-DYNA reader have been moved to + this 2.04 API level. +**************************************************************************** + + +The process for producing a user defined reader is: +--------------------------------------------------- +1. Write code for all pertinent routines in the library (Unless someone else + has done this for you). + + This is of course where the work is done by the user. The word + "pertinent" is used because depending on the nature of the data, some + of the routines in the library may be dummy routines. + + The source code for a dummy_gold library and for various other + working or sample libraries is copied from the installation CD during + installation. These will be located in directories under: + + $CEI_HOME/ensight76/user_defined_src/readers + + examples: + -------- + Basic dummy_gold routines provide skeleton for a new reader + $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold + + Sample library which reads unstructured binary EnSight Gold data + $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold + + You may find it useful to place your library source in this area as + well, but are not limited to this location. + + * ===> The descriptions of each library routine and the order that the + routines are called, which is provided in this file, along with + the example libraries, should make it possible for you to produce + code for your own data reader. + + +2. Produce the dynamic shared library. + + This is a compiling and loading process which varies according to + the type of machine you are on. In the user-defined-reader source + tree we have tried to isolate the machine dependent parts of the + build process using a set of files in the 'config' directory. In this + directory there is a configuration file for each platform on which + EnSight is supported. Before you can compile the installed readers + you should run the script called 'init' in the config directory. + + i.e. (for UNIX) + cd config + ./init sgi_6.5_n64 + cd .. + make + + If you are compiling for Windows NT, there are two options. If you + have the Cygwin GNU utilities installed, you can use GNU make as for + Unix. Otherwise, there is a script called makeall.cmd which will + build all of the readers using nmake. The Makefiles in each reader + directory will work using either make or nmake. + + i.e. (WIN32 Cygwin) (using nmake) + cd config cd config + sh init win32 cp win32 config + cd .. cd .. + mkdir lib + make makeall.cmd + + If you have platform-specific portions of code in your reader, the + build system defines a set of flags which can be used within + #ifdef ... #endif regions in your source, as shown in the table + below. + + Because the readers are now dynamically opened by EnSight, you may + have to include dependent libraries on your link-line to avoid having + unresolved symbols. If you are having problems with a reader, start + ensight as "ensight7 -readerdbg" and you will get feedback on any + problems encountered in loading a reader. If there are unresolved + symbols, you need to find the library which contains the missing + symbols and link it into your reader by adding it to the example + link commands below. + + If you choose to use a different build environment for your reader, + you should take care to use compatible compilation flags to ensure + compatibilty with the EnSight executables, most notably on the SGI + and HP-UX 11.0 platforms, which should use the following flags: + + sgi_6.2_o32: -mips2 + sgi_6.2_n64: -mips4 -64 + sgi_6.5_n32: -mips3 + sgi_6.5_n64: -mips4 -64 + hp_11.0_32: +DA2.0 + hp_11.0_64: +DA2.0W + + ______________________________________________________________________ + | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED | + | TYPE |------------------------------------------------------------| + | | LD COMMAND USED IN MAKEFILE | + ====================================================================== + ______________________________________________________________________ + | sgi | -DSGI | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | hp | -DHP | libuserd-X.sl | + | |------------------------------------------------------------| + | | ld -b -o libuserd-X.sl libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | sun | -DSUN | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | dec | -DDEC | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | linux | -DLINUX | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | alpha | -DALINUX | libuserd-X.so | + | linux |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | ibm | -DIBM | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc | + ---------------------------------------------------------------------- + + Once you have created your library, you should place it in a directory + of your choice or in the standard reader location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + For example, if you created a reader for "mydata", you should create + the reader libuserd-mydata.so and place the file in your own reader + directory (see section 3 below) or in the standard location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so + + +3. By default EnSight will load all readers found in the directory: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + Files with names "libuserd-X.so" (where X is a name unique to the reader) + are assumed to be user-defined readers. + + There are two methods which can be used to supplement the default + behavior. + + (1) A feature which is useful for site-level or user-level configuration + is the optional environment variable $ENSIGHT7_READER. This + variable directs EnSight to load all readers in the specified reader + directory (you should probably specify a full path) before loading + the built-in readers. If the same reader exists in both directories + (as determined by the name returned by USERD_get_name_of_reader(), + NOT by the filename), the locally configured reader will take + precedence. + + (2) A useful feature for end-users is the use of the libuserd-devel + reader. EnSight will search for a reader named libuserd-devel.so + (.sl for HP or .dll for NT). This reader can exist anywhere in the + library path (see below) of the user. This is useful for an + individual actively developing a reader because the existence of a + libuserd-devel library will take precedence over any other library + which returns the same name from USERD_get_name_of_reader(). + + As an example, a site may install commonly used readers in a common + location, and users can set the ENSIGHT7_READER variable to access them: + + setenv ENSIGHT7_READER /usr/local/lib/e7readers + + A user working on a new reader may compile the reader and place it in + a directory specified by the library path: + + cp libuserd-myreader.so ~/lib/libuserd-devel.so + setenv ~/lib:$ + + The user is responsible for correctly configuring the library path + variable in order to make use of the libuserd-devel feature. The + library environment variables used are: + + Machine type Environment variable to set + ------------ --------------------------- + sgi LD_LIBRARY_PATH + dec LD_LIBRARY_PATH + sun LD_LIBRARY_PATH + linux LD_LIBRARY_PATH + alpha linux LD_LIBRARY_PATH + hp SHLIB_PATH + ibm LIBPATH + +As always, EnSight support is available if you need it. + +------------------------------- +Quick Index of Library Routines +------------------------------- + +Generally Needed for UNSTRUCTURED data +-------------------------------------- +USERD_get_part_coords part's node coordinates +USERD_get_part_node_ids part's node ids +USERD_get_part_elements_by_type part's element connectivites +USERD_get_part_element_ids_by_type part's element ids + + +Generally Needed for BLOCK data +-------------------------------------- +USERD_get_block_coords_by_component block coordinates +USERD_get_block_iblanking block iblanking values +USERD_get_ghosts_in_block_flag block ghost cell existence? +USERD_get_block_ghost_flags block ghost cell flags + + These routines, which formerly were only for unstructured data, will now + also be called for structured data if you specify that ids will be given + in the USERD_get_node_label_status and USERD_get_element_label_status rotuines + ------------------------------------------------------------------------------ + USERD_get_part_node_ids part's node ids + USERD_get_part_element_ids_by_type part's element ids + + +Generally needed for either or both kinds of data +------------------------------------------------- +USERD_get_name_of_reader name of reader for GUI +USERD_get_reader_version provide reader version number +USERD_get_reader_descrip provide GUI more description (optional) + +USERD_set_filenames filenames entered in GUI +USERD_set_server_number server which of how many + +USERD_get_number_of_timesets number of timesets +USERD_get_timeset_description description of timeset +USERD_get_geom_timeset_number timeset # to use for geom + +USERD_get_num_of_time_steps number of time steps +USERD_get_sol_times solution time values +USERD_set_time_set_and_step current timeset and time step + +USERD_get_gold_part_build_info Gets the info needed for part building process +USERD_get_changing_geometry_status changing geometry? +USERD_get_node_label_status node labels? +USERD_get_element_label_status element labels? +USERD_get_model_extents provide model bounding extents +USERD_get_number_of_files_in_dataset number of files in model +USERD_get_dataset_query_file_info info about each model file +USERD_get_descrip_lines file associated description lines +USERD_get_number_of_model_parts number of model parts +USERD_get_part_build_info part/block type/descrip etc. +USERD_get_maxsize_info part/block allocation maximums +USERD_get_ghosts_in_model_flag model contains ghost cells? +USERD_get_nsided_conn Gets the element connectivities for nsided + elements. (utilizes the number of nodes + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced + elements (utilizes the number of faces + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_conn Gets the element connectivities for nfaced + elements (utilizes the number of nodes + per face obtained in + USERD_get_nfaced_nodes_per_face) + + +USERD_get_border_availability part border provided? +USERD_get_border_elements_by_type part border conn and parent info + +USERD_get_number_of_variables number of variables +USERD_get_gold_variable_info variable type/descrip etc. +USERD_get_var_by_component part or block variable values +USERD_get_constant_val constant variable's value +USERD_get_var_value_at_specific node's or element's variable value over time +USERD_stop_part_building cleanup after part build routine + +USERD_get_number_of_material_sets Gets the number of material sets +USERD_get_matf_set_info Gets the material set indices and names +USERD_get_number_of_materials Gets the number of materials +USERD_get_matf_var_info Gets the material indices and descriptions +USERD_size_matf_data Gets the length of either the + material ids list, + mixed-material ids list, or + mixed-material values list +USERD_load_matf_data Gets the material ids list, + mixed-material ids list, or + mixed-material values list + +USERD_bkup archive routine + +USERD_exit_routine cleanup upon exit routine + + +--------------------------- +Optional Extra GUI Info +Adds Toggle(s), Pulldown(s) Field(s) +that can be used for additonal input +--------------------------- +USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields +USERD_get_extra_gui_defaults Gets the default values for the GUI members +USERD_set_extra_gui_data Returns the answers provided by the user + +USERD_rigidbody_existence Returns whether rigid body transformation + data exists for the model. +USERD_rigidbody_values Returns the euler and location values for a + given part + +USERD_set_right_side Simply informs the reader when the time set + is for the right side of a time span during + variable interpolation between time steps. + +New at 2.04 +----------- + +/* ---------------------------------------------------------- + * + * Failure criteria in LS-DYNA + * if fail flag == threshold_val1 (0.0) then element fails + * logic_criteria2 not used + * threshold_val2 not used + * threshold_operator2 not used + * Return (Z_ERR) if this is not used. + * Return Z_OK if failed element feature should be used + * + * threshold_operator1 & 2 can be one of the following + * Z_ELE_FAILED_NONE, - disables checking + * Z_ELE_FAILED_GREATER, - greater than + * Z_ELE_FAILED_LESS, - less than + * Z_ELE_FAILED_EQUAL, - equal + * Z_ELE_FAILED_NOT_EQUAL, - not equal + * Z_ELE_FAILED_MANY - not used + * + * logic_criteria2 + * Z_ELE_FAILED_LOGIC_NONE, + * Z_ELE_FAILED_LOGIC_AND, + * Z_ELE_FAILED_LOGIC_OR, + * Z_ELE_FAILED_LOGIC_MANY + * + * ---------------------------------------------------------- */ + +int USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + +------------------------- +Order Routines are called +------------------------- + +The various main operations are given basically in the order they will +be performed. Within each operation, the order the routines will be +called is given. + +1. Setting name in the gui, and specifying one or two input fields + + USERD_get_name_of_reader + USERD_get_reader_descrip (optional) + USERD_get_extra_gui_numbers (optional) + USERD_get_extra_gui_defaults (optional) + +2. Getting the reader version (also distinguishes between API's) + + USERD_get_reader_version + +3. Setting filenames and getting timeset and time info + + USERD_set_server_number + USERD_set_extra_gui_data (optional) + USERD_set_filenames + USERD_get_number_of_timesets + USERD_get_geom_timeset_number + + for each timeset: + USERD_get_timeset_description + USERD_get_num_of_time_steps + USERD_get_sol_times + + USERD_set_time_set_and_step + +4. Gathering info for part builder + + USERD_set_time_set_and_step + USERD_get_changing_geometry_status + USERD_get_node_label_status + USERD_get_element_label_status + USERD_get_number_of_files_in_dataset + USERD_get_dataset_query_file_info + USERD_get_descrip_lines (for geometry) + USERD_get_number_of_model_parts + USERD_get_uns_failed_model_flag + USERD_get_gold_part_build_info + USERD_get_uns_failed_etype_flags + USERD_get_ghosts_in_model_flag + USERD_get_maxsize_info + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR (for model extents) + USERD_get_part_coords AND/OR + USERD_get_block_coords_by_component + +5. Gathering Variable info + + USERD_get_number_of_variables + USERD_get_gold_variable_info + +6. Part building (per part created) + + both unstructured and structured: + -------------------------------- + USERD_set_time_set_and_step + + if unstructured part: + -------------------- + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + + If any nsided elements: + + USERD_get_nsided_conn + + If any nfaced elements: + + USERD_get_nfaced_nodes_per_face + USERD_get_nfaced_conn + + USERD_get_part_coords + USERD_get_part_node_ids + USERD_get_uns_failed_elist_flags + + else if structured part: + ----------------------- + USERD_get_block_iblanking + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + both again: + ---------- + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + USERD_stop_part_building (only once when part builder + dialog is closed) + +7. Loading Variables + + constants: + --------- + USERD_set_time_set_and_step + USERD_get_constant_val + + scalars/vectors/tensors: + ------------------------ + USERD_get_descrip_lines + USERD_set_time_set_and_step + USERD_get_var_by_component + +8. Changing geometry + + changing coords only (per part): + -------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_part_coords + USERD_get_uns_failed_model_flag + USERD_get_uns_failed_etype_flags + USERD_get_uns_failed_elist_flags + USERD_get_block_coords_by_component + + changing connectivity (per part): + --------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_number_of_model_parts + USERD_get_uns_failed_model_flag + USERD_get_gold_part_build_info + USERD_get_uns_failed_etype_flags + USERD_get_ghosts_in_model_flag + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR + USERD_get_part_coords AND/OR + USERD_get_block_coords_by_component + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + USERD_get_part_coords + USERD_get_part_node_ids + USERD_get_uns_failed_elist_flags + USERD_get_block_iblanking + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + +9. Node or Element queries over time + + USERD_get_var_value_at_specific + +10. To see if materials in the model + + USERD_get_number_of_material_sets + USERD_get_matf_set_info + + If any material sets in the model (calls these once per material set): + USERD_get_number_of_materials + USERD_get_matf_var_info + + For each elment type of each part containing material ids, calls: + USERD_size_matf_data + USERD_load_matf_data + + If there are any elements with mixed materials, when a domain or + interface is created, calls these again per part: + + USERD_size_matf_data + USERD_load_matf_data + +11. To modify the variable extraction parameters and have the variables + update accordingly. + + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + + + +----------------------- +Detailed Specifications +----------------------- + +Include files: +-------------- +The following header file is required in any file containing these library +routines. + + #include "global_extern.h" + +And it references: + + #include "global_extern_proto.h" + + + +******************************************************************************* +****************************** Special Note *********************************** +******************************************************************************* + +Make sure you use the proper define in the global_extern.h header file, namely: +#define USERD_API_204 + +Also, Make sure the api version in the USERD_get_reader_version routine is set +to "2.04" or larger. + +Make sure your reader has access to the global_extern_proto.h This is a new +file which is accessed from the new global_extern.h + +******************************************************************************* +******************************************************************************* + + +Basis of arrays: +--------------- +Unless explicitly stated otherwise, all arrays are zero based - in true C +fashion. + + +Global variables: +---------------- +You will generally need to have a few global variables which are shared by +the various library routines. The detailed specifications below have assumed +the following are available. (Their names describe their purpose, and they +will be used in helping describe the details of the routines below). + +static int Numparts_available = 0; +static int Num_unstructured_parts = 0; +static int Num_structured_blocks = 0; + +/* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */ + +static int Num_timesets = 1; +static int Current_timeset = 1; +static int Geom_timeset_number = 1; + +static int Num_time_steps[Z_MAXSETS] = 1; +static int Current_time_step = 0; +static int Num_variables = 0; +static int Num_dataset_files = 0; + +static int Server_Number = 1; Which server of +static int Tot_Servers = 1; the total number of servers + + + +_________________________________________ +----------------------------------------- +Library Routines (in alphabetical order): +_________________________________________ +----------------------------------------- + +-------------------------------------------------------------------- +USERD_bkup + + Description: + ----------- + This routine is called during the EnSight archive process. You can + use it to save or restore info relating to your user defined reader. + + Specification: + ------------- + int USERD_bkup(FILE *archive_file, + int backup_type) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) archive_file = The archive file pointer + + (IN) backup_type = Z_SAVE_ARCHIVE for saving archive + Z_REST_ARCHIVE for restoring archive + + Notes: + ----- + * Since EnSight's archive file is saved in binary form, you should + also do any writing to it or reading from it in binary. + + * You should archive any variables, which will be needed for + future operations, that will not be read or computed again + before they will be needed. These are typically global + variables. + + * Make sure that the number of bytes that you write on a save and + the number of bytes that you read on a restore are identical!! + + * If any of the variables you save are allocated arrays, you must + do the allocations before restoring into them. + +-------------------------------------------------------------------- +USERD_exit_routine + + Description: + ----------- + This routine is called as EnSight is exiting. It can be used to clean + up anything needed - such as removing temporary files, etc. - or can simply + be a dummy. + + Specification: + ------------- + void USERD_exit_routine( void ) + + Arguments: + --------- + none + +-------------------------------------------------------------------- +USERD_get_block_coords_by_component + + Description: + ----------- + Get the coordinates of a given structured block, a component at a time. + + Specification: + ------------- + int USERD_get_block_coords_by_component(int block_number, + int which_component, + float *coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) which_component = Z_COMPX if x component wanted + = Z_COMPY if y component wanted + = Z_COMPZ if z component wanted + + (OUT) coord_array = 1D array containing x,y, or z + coordinate component of each node + + (Array will have been allocated + i*j*k for the block long) + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_block_iblanking + + Description: + ----------- + Get the iblanking value at each node of a block (if the block is + iblanked). + + Specification: + ------------- + int USERD_get_block_iblanking(int block_number, + int *iblank_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) iblank_array = 1D array containing iblank value + for each node. + + (Array will have been allocated + i*j*k for the block long) + + possible values are: Z_EXT = exterior + Z_INT = interior + Z_BND = boundary + Z_INTBND = internal boundary + Z_SYM = symmetry plane + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 and you have + some iblanked blocks + + * Will be based on Current_time_step + + + +---------------------------------------------------------------------- +USERD_get_block_ghost_flags + + Description: + ----------- + Get the ghost_flags value at each element of a block containing ghost cells. + + Specification: + ------------- + int USERD_get_block_ghost_flags(int block_number, + int *ghost_flags) + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) ghost_flags = 1D array containing ghost flag value + for each block cell. + + (Array will have been allocated + (i-1)*(j-1)*(k-1) for the block long) + + possible values are: 0 = non-ghost cell (normal cell) + >0 = ghost cell + + Notes: + ----- + * This routine is new in the 2.01 API + + * This will be based on Current_time_step + + * Only called for structured "block" parts that have some ghost cells + as indicated by the USERD_get_ghost_in_block_flag. The model must + of course also have been indicated to have some ghost cells in the + USERD_get_ghost_in_model_flag routine. + + * It is sufficient to set the value to be 1 to flag as a ghost cell, + but the value can be any non-zero value, so you could use it to + indicate which block or which server (for Server-of-server use) the + cell is actually in. + + + +-------------------------------------------------------------------- +USERD_get_border_availability + + Description: + ----------- + Finds out if border elements are provided by the reader for the + desired part, or will need to be computed internally by EnSight. + + Specification: + ------------- + int USERD_get_border_availability(int part_number, + int number_of_elements[Z_MAXTYPE]) + + Returns: + ------- + Z_OK if border elements will be provided by the reader. + (number_of_elements array will be loaded and + USERD_get_border_elements_by_type will be called) + + Z_ERR if border elements are not available - thus EnSight must compute. + (USERD_get_border_elements_by_type will not be called) + + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) number_of_elements = 2D array containing number of + each type of border element in + the part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + + Notes: + ----- + * Only called if border representation is used. + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_border_elements_by_type + + Description: + ----------- + Provides border element connectivity and parent information. + + Specification: + ------------- + int USERD_get_border_elements_by_type(int part_number, + int element_type, + int **conn_array, + short *parent_element_type, + int *parent_element_num) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + + (OUT) conn_array = 2D array containing connectivity + of each border element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_QUA08] = 30 + as obtained in: + USERD_get_border_availability + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_QUA08 + + (OUT) parent_element_type = 1D array containing element type of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + (OUT) parent_element_num = 1D array containing element number of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + + Notes: + ----- + * Not called unless USERD_get_border_availability returned Z_OK + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_changing_geometry_status + + Description: + ----------- + Gets the changing geometry status for the model + + Specification: + ------------- + int USERD_get_changing_geometry_status( void ) + + Returns: + ------- + Z_STATIC if geometry does not change + Z_CHANGE_COORDS if changing coordinates only + Z_CHANGE_CONN if changing connectivity + + Arguments: + --------- + none + + Notes: + ----- + * EnSight does not support changing number of parts. But the + coords and/or the connectivity of the parts can change. Note that + a part is allowed to be empty (number of nodes and elements equal + to zero). + + +-------------------------------------------------------------------- +USERD_get_constant_val + + Description: + ----------- + Get the value of a constant at a time step + + Specification: + ------------- + float USERD_get_constant_value(int which_var, + int imag_data) + + Returns: + ------- + Value of the requested constant variable + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) imag_data = TRUE if want imaginary data value. + FALSE if want real data value. + + Notes: + ----- + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_dataset_query_file_info + + Description: + ----------- + Get the information about files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_dataset_query_file_info(Z_QFILES *qfiles) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) qfiles = Structure containing information about each file + of the dataset. The Z_QFILES structure is defined + in the global_extern.h file + + (The structure will have been allocated + Num_dataset_files long, with 10 description + lines per file). + + qfiles[].name = The name of the file + (Z_MAXFILENP is the dimensioned length + of the name) + + qfiles[].sizeb = The number of bytes in the file + (Typically obtained with a call to the + "stat" system routine) (Is a long) + + qfiles[].timemod = The time the file was last modified + (Z_MAXTIMLEN is the dimensioned length + of this string) + (Typically obtained with a call to the + "stat" system routine) + + qfiles[].num_d_lines = The number of description lines you + are providing from the file. Max = 10 + + qfiles[].f_desc[] = The description line(s) per file, + qfiles[].num_d_lines of them + (Z_MAXFILENP is the allocated length of + each line) + + Notes: + ----- + * If Num_dataset_files is 0, this routine will not be called. + (See USERD_get_number_of_files_in_dataset) + + +-------------------------------------------------------------------- +USERD_get_descrip_lines + + Description: + ----------- + Get two description lines associated with geometry per time step, + or one description line associated with a variable per time step. + + Specification: + ------------- + int USERD_get_descrip_lines(int which_type, + int which_var, + int imag_data, + char line1[Z_BUFL], + char line2[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_type = Z_GEOM for geometry (2 lines) + = Z_VARI for variable (1 line) + + (IN) which_var = If it is a variable, which one. + Ignored if geometry type. + + (IN) imag_data = TRUE if want imaginary data file. + FALSE if want real data file. + + (OUT) line1 = The 1st geometry description line, + or the variable description line. + + (OUT) line2 = The 2nd geometry description line + Not used if variable type. + + Notes: + ----- + * Will be based on Current_time_step + + * These are the lines EnSight can echo to the screen in + annotation mode. + + + +-------------------------------------------------------------------- +USERD_get_element_label_status + + Description: + ----------- + Answers the question as to whether element labels will be provided. + + Specification: + ------------- + int USERD_get_element_label_status( void ) + + Returns: + ------- + TRUE if element labels will be provided + FALSE if element labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * element lables are needed in order to do any element querying, or + element labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. + + API 1.0: + USERD_get_element_ids_for_part is used to obtain the ids, + on a part by part basis, if TRUE status is returned here. + + API 2.0: + USERD_get_part_element_ids_by_type is used to obtain the ids, + on a per part, per type basis, if TRUE status is returned here. + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them youself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model (especially + if you are dealing with a decomposed dataset). + + USERD_get_part_element_ids_by_type is used to obtain the ids, + on an element type by part basis, if TRUE status is returned here. + + * Will call USERD_get_part_element_ids_by_type for each type of + of each part if this routine returns TRUE. +-------------------------------------------------------------------- +USERD_get_geom_timeset_number - + + Description: + ----------- + Gets the timeset number to be used for geometry + + Specification: + ------------- + int USERD_get_geom_timeset_number( void ) + + Returns: + ------- + Geom_timeset_number = The timeset number that will be used for geometry. + For example, if USERD_get_number_of timesets + returns 2, the valid timeset numbers would be + 1 or 2. + + Arguments: + --------- + none + + Notes: + ----- + * If your model is static, which you indicated by returning a zero + in USERD_get_number_of_timesets, you can return a zero here as well. + + + +-------------------------------------------------------------------- +USERD_get_gold_part_build_info + + Description: + ----------- + Gets the info needed for the part building process. + + Specification: + ------------- + int USERD_get_gold_part_build_info(int *part_id, + int *part_types, + char *part_description[Z_BUFL], + int *number_of_nodes, + int *number_of_elements[Z_MAXTYPE], + int *ijk_dimensions[9], + int *iblanking_options[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) part_id = Array containing the external part + ids for each of the model parts. + + IMPORTANT: + Parts numbers must be >= 1, because + of the way they are used in the GUI + + ******************************************* + The ids provided here are the numbers by + which the parts will be referred to in the + GUI (if possible). They are basically + labels as far as you are concerned. + + Note: The part numbers you pass to routines + which receive a part_number or block_number + or which_part as an argument are the 1-based + table index of the parts! + + example: If Numparts_available = 3 + + Table index part_id + ----------- ------- + 1 13 + 2 57 + 3 125 + + ^ ^ + | | + | These are placed in: + | part_id[0] = 13 + | part_id[1] = 57 + | part_id[2] = 125 + | for GUI labeling purposes. + | + These implied table indices are the part_number, + block_number, or which_part numbers that you would + pass to routines like: + + USERD_get_part_coords(int part_number,... + USERD_get_part_node_ids(int part_number,... + USERD_get_part_elements_by_type(int part_number,... + USERD_get_part_element_ids_by_type(int part_number,... + USERD_get_block_coords_by_component(int block_number,... + USERD_get_block_iblanking(int block_number,... + USERD_get_block_ghost_flags(int block_number,... + USERD_get_ghosts_in_block_flag(int block_number) + USERD_get_border_availability(int part_number,... + USERD_get_border_elements_by_type(int part_number,... + USERD_get_var_by_component(int which_variable, + int which_part,... + USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part,... + ******************************************** + + (Array will have been allocated + Numparts_available long) + + (OUT) part_types = Array containing one of the + following for each model part: + + Z_UNSTRUCTURED or + Z_STRUCTURED or + Z_IBLANKED + + (Array will have been allocated + Numparts_available long) + + (OUT) part_description = Array containing a description + for each of the model parts + + (Array will have been allocated + Numparts_available by Z_BUFL + long) + + (OUT) number_of_nodes = Number of unstructured nodes in the part + + (Array will have been allocated + Numparts_available long) + + (OUT) number_of_elements = 2D array containing number of + each type of element for each + unstructured model part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) ijk_dimensions = 2D array containing ijk dimension info + for structured blocks + + For Z_UNSTRUCTURED - is ignored + + For Z_STRUCTURED or Z_IBLANKED + + Prior to version 2.03: + ---------------------- + (Array will have been allocated + Numparts_available by 3 long) + + ijk_dimensions[][0] = I dimension + ijk_dimensions[][1] = J dimension + ijk_dimensions[][2] = K dimension + + + Starting at version 2.03: + ------------------------ + (Array will have been allocated + Numparts_available by 9 long) + + There are two ways to do this: + ------------------------------ + 1. The simple one, without ranges. + + This is good for all structured models + that will NOT be used in EnSight's + Server of Servers + + Simply provide the ijk dimensions in the + first three slots and place a -1 in + the 4th slot. (The remaining slots will + be ignored). + + Thus, + ijk_dimensions[][0] = I dimension of block + ijk_dimensions[][1] = J dimension of block + ijk_dimensions[][2] = K dimension of block + ijk_dimensions[][3] = -1 + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][4] = -1 + | | | + | | | + 2 *-------*-------* + | | | + | | | + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + + 2. Using ranges. + + This one can be used anytime, but MUST + be used if EnSight's Server of Servers + is to be used! + + The first 3 slots contain the ijk dimension + of the complete block (of which this may be + a portion). The last 6 slots contain the + ijk min and max ranges within the complete. + + Thus, + ijk_dimensions[][0] = I dim of complete block + ijk_dimensions[][1] = J dim of complete block + ijk_dimensions[][2] = K dim of complete block + + ijk_dimensions[][3] = Imin of portion (1-based) + ijk_dimensions[][4] = Imax of portion (1-based) + ijk_dimensions[][5] = Jmin of portion (1-based) + ijk_dimensions[][6] = Jmax of portion (1-based) + ijk_dimensions[][7] = Kmin of portion (1-based) + ijk_dimensions[][8] = Kmax of portion (1-based) + + + example1: (Model has one part, a simple 2D block, + and want whole thing) + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][3] = 1 + | | | ijk_dimension[0][4] = 3 + | | | ijk_dimension[0][5] = 1 + 2 *-------*-------* ijk_dimension[0][6] = 4 + | | | ijk_dimension[0][7] = 1 + | | | ijk_dimension[0][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + example2: (Want to have the block represented + in two portions - 2 parts) + + (J planes) top portion + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + . . . ijk_dimension[0][3] = 1 + . . . ijk_dimension[0][4] = 3 + . . . ijk_dimension[0][5] = 3 + 2 ................. ijk_dimension[0][6] = 4 + . . . ijk_dimension[0][7] = 1 + . . . ijk_dimension[0][8] = 1 + . . . + 1 ................. + 1 2 3 (I planes) + + + (J planes) bottom portion + 4 ................. + . . . ijk_dimension[1][0] = 3 + . . . ijk_dimension[2][1] = 4 + . . . ijk_dimension[3][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[1][3] = 1 + | | | ijk_dimension[1][4] = 3 + | | | ijk_dimension[1][5] = 1 + 2 *-------*-------* ijk_dimension[1][6] = 3 + | | | ijk_dimension[1][7] = 1 + | | | ijk_dimension[1][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + And note that if you were partioning this block for + EnSight's Server of Servers, you would only have one part, + instead of two. Each SOS server would return its appropriate + ranges in the last 6 slots. The first 3 slots would remain constant. + + + (OUT) iblanking_options = 2D array containing iblanking + options possible for each + structured model part. + ---------- + (Ignored unless Z_IBLANKED type) + + (Array will have been allocated + Numparts_available by 6 long) + + iblanking_options[][Z_EXT] = TRUE if external (outside) + [][Z_INT] = TRUE if internal (inside) + [][Z_BND] = TRUE if boundary + [][Z_INTBND] = TRUE if internal boundary + [][Z_SYM] = TRUE if symmetry surface + + + Notes: + ----- + * If you haven't built a table of pointers to the different parts, + you might want to do so here as you gather the needed info. + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_gold_variable_info + + Description: + ----------- + Get the variable descriptions, types and filenames + + Specification: + ------------- + int USERD_get_gold_variable_info(char **var_description, + char **var_filename, + int *var_type, + int *var_classify, + int *var_complex, + char **var_ifilename, + float *var_freq, + int *var_contran, + int *var_timeset) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) var_description = Variable descriptions + + (Array will have been allocated + Num_variables by Z_BUFL long) + + variable description restrictions: + ---------------------------------- + 1. Only first 19 characters used in EnSight. + 2. Leading and trailing whitespace will be removed by EnSight. + 3. Illegal characters will be replaced by underscores. + 4. Thay may not start with a numeric digit. + 4. No two variables may have the same description. + + + (OUT) var_filename = Variable real filenames + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_type = Variable type + + (Array will have been allocated + Num_variables long) + + types are: Z_CONSTANT + Z_SCALAR + Z_VECTOR + Z_TENSOR + Z_TENSOR9 + + (OUT) var_classify = Variable classification + + (Array will have been allocated + Num_variables long) + + types are: Z_PER_NODE + Z_PER_ELEM + + (OUT) var_complex = TRUE if complex, FALSE otherwise + + (Array will have been allocated + Num_variables long) + + (OUT) var_ifilename = Variable imaginary filenames (if complex) + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_freq = complex frequency (if complex) + + (Array will have been allocated + Num_variables long) + + (OUT) var_contran = TRUE if constant changes per time step + FALSE if constant truly same at all time steps + + (Array will have been allocated + Num_variables long) + + (OUT) var_timeset = Timeset the variable will use (1 based). + (For static models, set it to 1) + + (Array will have been allocated + Num_variables long) + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 or 2 + + + Notes: + ----- + * The implied variable numbers apply, but be aware that the + arrays are zero based. + So for variable 1, will need to provide var_description[0] + var_filename[0] + var_type[0] + var_classify[0] + var_complex[0] + var_ifilename[0] + var_freq[0] + var_contran[0] + var_timeset[0] + + + for variable 2, will need to provide var_description[1] + var_filename[1] + var_type[1] + var_classify[1] + var_complex[1] + var_ifilename[1] + var_freq[1] + var_contran[1] + var_timeset[1] + etc. + + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_block_flag + + Description: + ----------- + Gets whether ghost cells present in block or not + + Specification: + ------------- + int USERD_get_ghosts_in_block_flag(int block_number) + + Returns: + ------- + TRUE if any ghost cells in this structured part + FALSE if no ghost cells in this structured part + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Notes: + ----- + * This routine is new in the 2.01 API + * This will be based on Current_time_step + + * Intended for structured parts only, value will be ignored for + unstructured parts + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_model_flag + + Description: + ----------- + Answers the question as to whether any ghost cells in the model. + + Specification: + ------------- + int USERD_get_ghosts_in_model_flag( void ) + + Returns: + ------- + TRUE if any ghost cells in the model + FALSE if no ghost cells in the model + + Arguments: + --------- + + Notes: + ----- + * This routine is new in the 2.01 API + +------------------------------------------------------------------------- +USERD_get_matf_set_info + + Description: + ----------- + Get the material set ids and names + + Specification: + ------------- + int USERD_get_matf_set_info(int *mat_set_ids, + char **mat_set_name) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) mat_set_ids = 1D material set ids array + + (Array will have been allocated + Num_material_sets long) + + (OUT) mat_set_name = 2D material set name array + + (Array will have been allocated + Num_material_sets by Z_BUFL long) + + Notes: + ----- + * Will not be called if Num_material_sets is zero + * See USERD_get_number_of_material_sets header for explanatory example + + +-------------------------------------------------------------------- +USERD_get_matf_var_info + + Description: + ----------- + Gets the material ids and descriptions for the material set + + Specification: + ------------- + int USERD_get_matf_var_info(int set_index, + int *mat_ids, + char **mat_desc) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (OUT) mat_ids[set_index] = 1D integer array containing the material + ids to associated with each material + + (Array will have been allocated + Num_materials[set_index] long) + + (OUT) mat_desc[set_index] = 2D char array containing the material + descriptions to associated with each material + + (Array will have been allocated + Num_materials[set_index] by Z_BUFL long) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_get_maxsize_info + + Description: + ----------- + Gets maximum part sizes for efficient memory allocation. + + Transient models (especially those that increase in size) can cause + reallocations, at time step changes, to keep chewing up more and + more memory. The way to avoid this is to know what the maximum + size of such memory will be, and allocate for this maximum initially. + + Accordingly, if you choose to provide this information (it is optional), + EnSight will take advantage of it. + + + Specification: + ------------- + int USERD_get_maxsize_info(int *max_number_of_nodes, + int *max_number_of_elements[Z_MAXTYPE], + int *max_ijk_dimensions[3]) + + Returns: + ------- + Z_OK if supplying maximum data + Z_ERR if not supplying maximum data, or some error occurred + while trying to obtain it. + + Arguments: + --------- + (OUT) max_number_of_nodes = Maximum number of unstructured nodes + in the part (over all time). + + (Array will have been allocated + Numparts_available long) + + (OUT) max_number_of_elements = 2D array containing maximum number of + each type of element for each + unstructured model part (over all time). + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions + for each structured model part (over all time). + ---------- + (Ignored if Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by 3 long) + + max_ijk_dimensions[][0] = maximum I dimension + max_ijk_dimensions[][1] = maximum J dimension + max_ijk_dimensions[][2] = maximum K dimension + + Notes: + ----- + * You need to have first called USERD_get_number_of_model_parts and + USERD_get_gold_part_build_info, so Numparts_available is known and + so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED, + or Z_IBLANKED) of each part. + + * This will NOT be based on Current_time_step - it is to be the maximum + values over all time!! + + * This information is optional. If you return Z_ERR, Ensight will still + process things fine, reallocating as needed, etc. However, for + large transient models you will likely use considerably more memory + and take more processing time for the memory reallocations. So, if it + is possible to provide this information "up front", it is recommended + to do so. + + +-------------------------------------------------------------------- +USERD_get_model_extents + + Description: + ----------- + Gets the model bounding box extents. If this routine supplys them + EnSight will not have to spend time doing so. If this routine + returns Z_ERR, EnSight will have to take the time to touch all the + nodes and gather the extent info. + + Specification: + ------------- + int USERD_get_model_extents(float extents[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (whereupon EnSight will determine by reading + all coords of all parts) + + Arguments: + --------- + (OUT) extents[0] = min x + [1] = max x + [2] = min y + [3] = max y + [4] = min z + [5] = max z + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_name_of_reader + + Description: + ----------- + Gets the name of your user defined reader. The user interface will + ask for this and include it in the available reader list. + + Specification: + ------------- + int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], + int *two_fields) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) reader_name = the name of the your reader or data format. + (max length is Z_MAX_USERD_NAME, which is 20) + + (OUT) two_fields = FALSE if only one data field is + required. + TRUE if two data fields required + + -1 if one field (Geom) required + and one field (Param) is optional + Param field can contain any text + for example a file name, modifiers, + etc. that can be used to modify the + reader's behavior. + + + Notes: + ----- + * Always called. Please be sure to provide a name for your custom + reader format. + +-------------------------------------------------------------------- +USERD_get_nfaced_conn + + Description: + ----------- + Gets the array containing the connectivity of nsided faces of nfaced elements + + Specification: + -------------int + int USERD_get_nfaced_conn(int part_number, + int *nfaced_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced + elements + + (int array will have been allocated long enough to + hold all the nsided face connectivities. Which is + the sum of all the nodes per face values in the + nfaced_npf_array of USERD_get_nfaced_nodes_per_face) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In USERD_get_faced_nodes_per_face: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In this function: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + +-------------------------------------------------------------------- +USERD_get_nfaced_nodes_per_face - + + Description: + ----------- + Gets the array containing the number of nodes per face for each face + of the nfaced elements. + + Specification: + ------------- + int USERD_get_nfaced_nodes_per_face(int part_number, + int *nfaced_npf_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of + nfaced elements + + (int array will have been allocated long enough + to hold all the nodes_per_face values. Which is + the sum of all the number of faces per element + values in the conn_array of + USERD_get_part_elements_by_type) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the + the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In this routine: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In USERD_get_nfaced_conn: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + + +-------------------------------------------------------------------- +USERD_get_node_label_status + + Description: + ----------- + Answers the question as to whether node labels will be provided. + + Specification: + ------------- + int USERD_get_node_label_status( void ) + + Returns: + ------- + TRUE if node labels will be provided + FALSE if node labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * Node ids are needed in order to do any node querying, or node + labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. They must also be + positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + (Unlike API 1.0, where the connectivity of elements had to be + according to the node ids - API 2.0's element connectivities + are not affected either way by the status here.) + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them yourself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model. They must + also be positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + * Will call USERD_get_part_node_ids for each part if this routine + returns TRUE. + +-------------------------------------------------------------------- +USERD_get_nsided_conn - + + Description: + ----------- + Gets the array containing the connectivity of nsided elements + + Specification: + ------------- + int USERD_get_nsided_conn(int part_number, + int *nsided_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nsided_conn_array = 1D array of nsided connectivies + + (int array will have been allocated long enough + to hold all the nsided connectivities. Which is + the sum of all the nodes_per_element values in + the conn_array of USERD_get_part_elements_by_type) + + + Notes: + ----- + * Will not be called unless there are some nsided elements in the the part. + + * Providing nsided information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nsided + elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of nodes per nsided element. (as if connectivity + length of an nsided element is one) + + 3. In this routine, provide the streamed connectivities for each of the + nsided elements. + + + Simple example: 5 6 + +--------+ + 3 nsided elements: /| \ + (1 4-sided / | \ + 1 3-sided / | \ + 1 7-sided) / | \ 7 + /3 |4 + + +-----+ | + | | | + | | |8 + | | + + | | / + | | / + | | / + |1 |2 /9 + +-----+--------+ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NSIDED] = 3 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 3 x 1 + + for element_type of Z_NSIDED: + conn_array[0][0] = 4 (for the 4-sided element) + conn_array[1][0] = 3 (for the 3-sided element) + conn_array[2][0] = 7 (for the 7-sided element) + + Sum === + 14 <---------+ + | + 3. In this routine: | + length of nsided_conn_array will be: 14 + + nsided_conn_array[0] = 1 (connectivity of 4-sided element) + nsided_conn_array[1] = 2 + nsided_conn_array[2] = 4 + nsided_conn_array[3] = 3 + + nsided_conn_array[4] = 3 (connectivity of 3-sided element) + nsided_conn_array[5] = 4 + nsided_conn_array[6] = 5 + + nsided_conn_array[7] = 2 (connectivity of 7-sided element) + nsided_conn_array[8] = 9 + nsided_conn_array[9] = 8 + nsided_conn_array[10] = 7 + nsided_conn_array[11] = 6 + nsided_conn_array[12] = 5 + nsided_conn_array[13] = 4 + + + + +-------------------------------------------------------------------- +USERD_get_num_of_time_steps + + Description: + ----------- + Gets the number of time steps of data available for desired timeset. + + Specification: + ------------- + int USERD_get_num_of_time_steps( int timeset_number ) + + Returns: + ------- + Number of time steps in timeset (>0 if okay, <=0 if problems). + + Arguments: + --------- + (IN) timeset number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + Notes: + ----- + * This should be >= 1 1 indicates a static model + >1 indicates a transient model + + * Num_time_steps[timeset_number] would be set here + + + +-------------------------------------------------------------------- +USERD_get_number_of_files_in_dataset + + Description: + ----------- + Get the total number of files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_number_of_files_in_dataset( void ) + + Returns: + ------- + The total number of files in the dataset. + + Arguments: + --------- + none + + Notes: + ----- + * You can be as complete as you want about this. If you don't + care about the dataset query option, return a value of 0 + If you only want certain files, you can just include them. But, + you will need to supply the info in USERD_get_dataset_query_file_info + for each file you include here. + + * Num_dataset_files would be set here + + +-------------------------------------------------------------------- +USERD_get_number_of_material_sets - + + Description: + ----------- + Get the number of material sets in the model + + Specification: + ------------- + int USERD_get_number_of_material_sets( void ) + + + Returns: + ------- + Num_material_sets = number of material sets + (Zero would indicate that you have no materials + to deal with in the model) + + or + + -1 if an error condition + + Arguments: + --------- + none + + Notes: + ----- + * You may want to keep this as a global for use in other routines. + + ############################################################### + NOTE: For EnSight 7.6, only one material set is supported + within EnSight. + Thus the only valid returns here are: + 0 (no materials) + 1 (for the one material set allowed) + or -1 (if an error) + + If the casefile has more than this, this reader will + read them, but EnSight will issue an error message and + choke on them! + ############################################################### + + ================================================================ + A very simple explanatory example, to use as a reference for the + materials routines: + + Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials. + Most of the model is material 1, but the top left corner is material 9 - + basically as shown: + + + *--------*--------*--------* + | | / | | + | Mat 9 / | | + | | / | | + | |/ | | + | e7 / e8 | e9 | + | /| | | + | / | | | + | / | | | + *----/---*--------*--------* + | / | | | + | / | | | + | / | Mat 1 | + |/ | | | + | e4 | e5 | e6 | + | | | | + | | | | + | | | | + *--------*--------*--------* + | | | | + | | | | + | | | | + | | | | + | e1 | e2 | e3 | + | | | | + | | | | + | | | | + *--------*--------*--------* + + + Thus, in this routine, set: + Num_material_sets = 1 + + In USERD_get_matf_set_info, set: + mat_set_ids[0] = 1 + mat_set_name[0] = "Material Set 1" (or whatever name desired) + + In USERD_get_number_of_materials, input would be set_index = 0, and + would need to set: + Num_materials[0] = 2 + + For simplicity, the ids and descriptions that would be returned in + USERD_get_matf_var_info could be: + mat_ids[0] = 1 + mat_ids[1] = 9 + mat_desc[0] = "mat 1" (or whatever desired) + mat_desc[2] = "mat 9" + + The per element material ids list would need to be: + + material ids: + ------------- + ids_list[0] = 1 (material id 1, for elem e1) + ids_list[1] = 1 ( " e2) + ids_list[2] = 1 ( " e3) + ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4) + ids_list[5] = 1 (material id 1, for elem e5) + ids_list[5] = 1 ( " e6) + ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7) + ids_list[5] = -9 ( " e8) + ids_list[5] = 1 (material id 1, for elem e9) + + Finally we need the mixed material ids list and the mixed materials values list, + which would need to be: + + mixed-material ids: + ------------------- + ==> 1 ids_list[0] = 2 (the -1 in the material variable points here, + 2 indicates that two materials are present) + 2 ids_list[1] = 1 (1st material is 1) + 3 ids_list[2] = 9 (2nd material is 9) + 4 ids_list[3] = -1 (negative of index into mixed-material val_list) + ==> 5 ids_list[4] = 2 (the -5 in the material variable points here, + 2 indicates that two materials are present) + 6 ids_list[5] = 1 (1st material is 1) + 7 ids_list[6] = 9 (2nd material is 9) + 8 ids_list[7] = -3 (negative of index into mixed-material val_list) + ==> 9 ids_list[8] = 2 etc. + 10 ids_list[9] = 1 + 11 ids_list[10] = 9 + 12 ids_list[11] = -5 + + mixed-material values: + ---------------------- + ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here, + and this is the value for material 1) + 2 val_list[1] = 0.125 (the value for material 9) + ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here) + 4 val_list[3] = 0.875 + ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here) + 6 val_list[5] = 0.125 + + So, USERD_size_matf_data would need to return + matf_size = 8, when called with set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX + + matf_size = 12, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX + + = 6, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE + + And, USERD_load_matf_data would need to return: + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX (indicating id list). + + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX (indicating id list). + + the float array val_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE (indicating val list). + + +------------------------------------------------------------------------- +USERD_get_number_of_materials + + Description: + ----------- + Gets the number of materials in the material set + + Specification: + ------------- + int USERD_get_number_of_materials( int set_index ) + + Returns: + ------- + Num_materials[set_index] = Number of materials in the set + 0 indicates no materials information present + -1 indicates an error + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero + * You may want to keep this as a global for use in other routines. + + + +-------------------------------------------------------------------- +USERD_get_number_of_model_parts + + Description: + ----------- + Gets the total number of unstructured and structured parts + in the model, for which you can supply information. + + Specification: + ------------- + int USERD_get_number_of_model_parts( void ) + + Returns: + ------- + Number of parts (>0 if okay, <=0 if problems). + + Arguments: + --------- + none + + Notes: + ----- + * If going to have to read down through the parts in order to + know how many, you may want to build a table of pointers to + the various parts, so you can easily get to particular parts in + later processes. If you can simply read the number of parts + at the head of the file, then you would probably not build the + table at this time. + + * This routine would set Numparts_available, which is equal to + Num_unstructured_parts + Num_structured_blocks. + + + +-------------------------------------------------------------------- +USERD_get_number_of_timesets + + Description: + ----------- + Gets the number of timesets used in the model. + + Specification: + ------------- + int USERD_get_number_of_timesets( void ) + + Returns: + ------- + Number of timesets in the model + + Arguments: + --------- + none + + Notes: + ----- + * Num_timesets would be set here + + * If you have a static model, both geometry and variables, you should + return a value of zero. + + * If you have a transient model, then you should return one or more. + + For example: + + Geometry Variables No. of timesets + --------- ------------------------------ --------------- + static static 0 + static transient, all using same timeset 1 + + transient transient, all using same timeset as geom 1 + + static transient, using 3 different timesets 3 + + transient transient, using 3 different timesets and + none of them the same as the + geometry timeset 4 + etc. + + NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide + the timeset number to use + for geometry in: + USERD_get_geom_timeset_number + + Variables can use the same timeset as the geometry, or can use + other timesets. More than one variable can use the same timeset. + + example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0 + variable 1 provided at these same five steps + variable 2 provided at 3 steps, 0.5, 1.25, 3.33 + + This routine should return a value of 2, because only + two different timesets are needed. Timeset 1 would be for the + geometry and variable 1 (they both use it). Timeset 2 would + be for variable 2, which needs its own in this case. + + + + + +-------------------------------------------------------------------- +USERD_get_number_of_variables + + Description: + ----------- + Get the number of variables for which you will be providing info. + + Specification: + ------------- + int USERD_get_number_of_variables( void ) + + Returns: + ------- + Number of variables (includes constant, scalar, vector and tensor types) + (>=0 if okay, <0 if problem) + + Arguments: + --------- + none + + Notes: + ----- + ***************************************************************** + * Variable numbers, by which references will be made, are implied + here. If you say there are 3 variables, the variable numbers + will be 1, 2, and 3. + ***************************************************************** + + * Num_variables would be set here + + + +-------------------------------------------------------------------- +USERD_get_part_coords + + Description: + ----------- + Gets the coordinates for an unstructured part. + + Specification: + ------------- + int USERD_get_part_coords(int part_number, float **coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) coord_array = 2D float array which contains, + x,y,z coordinates of each node + in the part. + + (IMPORTANT: The second dimension of this aray is 1-based!!!) + + (Array will have been allocated + 3 by (number_of_nodes + 1) for the part + long - see USERD_get_gold_part_build_info) + + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + coord_array[3][101] + + Ignore the coord_array[0][0] + coord_array[1][0] + coord_array[2][0] locations and start + the node coordinates at: + coord_array[0][1] + coord_array[1][1] + coord_array[2][1] + + coord_array[0][2] + coord_array[1][2] + coord_array[2][2] + + etc. + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_element_ids_by_type + + Description: + ----------- + Gets the ids for the elements of a particular type for an unstructured + or structured part. + + Specification: + ------------- + int USERD_get_part_element_ids_by_type(int part_number, + int element_type, + int *elemid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (OUT) elemid_array = 1D array containing id of each + element of the type. + + (Array will have been allocated + number_of_elements of the type long) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25] when called with Z_TRI03 + + conn_array[100] when called with Z_QUA04 + + conn_array[30] when called with Z_HEX08 + + Notes: + ----- + * Not called unless element label status is set to TRUE in + USERD_get_element_label_status + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_part_elements_by_type + + Description: + ----------- + Gets the connectivities for the elements of a particular type in an + unstructured part + + Specification: + ------------- + int USERD_get_part_elements_by_type(int part_number, + int element_type, + int **conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + + (OUT) conn_array = 2D array containing connectivity + of each element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_HEX08 + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_node_ids + + Description: + ----------- + Gets the node ids of an unstructured or structured part. + + Specification: + ------------- + int USERD_get_part_node_ids(int part_number, int *nodeid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) nodeid_array = 1D array containing node ids of + each node in the part. + + (IMPORTANT: This array is 1-based!!!) + + (Array will have been allocated + (number_of_nodes + 1) for the part long + see USERD_get_gold_part_build_info) + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + nodeid_array[101] + + Ignore the nodeid_array[0] location and start + the node ids at: + nodeid_array[1] + + nodeid_array[2] + + etc. + + Notes: + ----- + * Not called unless node label status is TRUE, as returned from + USERD_get_node_label_status + + * Will be based on Current_time_step + + * The ids are purely labels, used when displaying or querying node ids. + However, any node id < 0 will never be displayed + + +-------------------------------------------------------------------- +USERD_get_reader_descrip + + Description: + ----------- + Gets the description of the reader, so gui can give more info + + Specification: + ------------- + int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) descrip = the description of the reader (max length is MAXFILENP, + which is 255) + + Notes: + ----- + * OPTIONAL ROUTINE! You can have it or not. + + + +-------------------------------------------------------------------- +USERD_get_reader_version + + Description: + ----------- + Gets the version number of the user defined reader + + Specification: + ------------- + int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (and will assume is version 1.0) + + Arguments: + --------- + (OUT) version_number = the version number of the reader + (max length is Z_MAX_USERD_NAME, which + is 20) + + Notes: + ----- + * This needs to be "2.000" or greater. Otherwise EnSight will assume + this reader is API 1.0 + + * should set it to "2.010" for this version of the API + + + + +-------------------------------------------------------------------- +USERD_get_sol_times + + Description: + ----------- + Get the solution times associated with each time step for + desired timeset. + + Specification: + ------------- + int USERD_get_sol_times(int timeset_number, + float *solution_times) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) solution_times = 1D array of solution times per time step + + (Array will have been allocated + Num_time_steps[timeset_number] long) + + Notes: + ----- + * The solution times must be non-negative and increasing. + + + +-------------------------------------------------------------------- +USERD_get_timeset_description - + + Description: + ----------- + Get the description to associate with the desired timeset. + + Specification: + ------------- + int USERD_get_timeset_description(int timeset_number, + char timeset_description[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) timeset_description = timeset description string + + + Notes: + ----- + * A string of NULLs is valid for timeset_description + + + + +-------------------------------------------------------------------- +USERD_get_var_by_component + + Description: + ----------- + Gets the values of a variable component. Both unstructured and structured + parts use this routine. + + if Z_PER_NODE: + Get the component value at each node for a given variable in the part. + + or if Z_PER_ELEM: + Get the component value at each element of a specific part and type + for a given variable. + + Specification: + ------------- + int USERD_get_var_by_component(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + or: Z_UNDEF, in which case you need not load any values into var_array + + + Arguments: + --------- + (IN) which_variable = The variable number + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + (IN) var_type = Z_SCALAR + Z_VECTOR + Z_TENSOR (symmetric tensor) + Z_TENSOR9 (asymmetric tensor) + + (IN) which_type + + if Z_PER_NODE: Not used + + if Z_PER_ELEM: = The element type + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (IN) imag_data = TRUE if imag component + FALSE if real component + + (IN) component = The component: (0 if Z_SCALAR) + (0 - 2 if Z_VECTOR) + (0 - 5 if Z_TENSOR) + (0 - 8 if Z_TENSOR9) + + * 6 Symmetric Indicies, 0:5 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 22 23 | = | 1 5 | * + * | | | | * + * | 33 | | 2 | * + + + * 9 General Indicies, 0:8 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 21 22 23 | = | 6 1 5 | * + * | | | | * + * | 31 32 33 | | 7 8 2 | * + + (OUT) var_array + + ----------------------------------------------------------------------- + (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!) + ----------------------------------------------------------------------- + + if Z_PER_NODE: = 1D array containing variable component value + for each node. + + (Array will have been allocated + (number_of_nodes + 1) long) + + Info stored in this fashion: + var_array[0] = not used + var_array[1] = var component for node 1 of part + var_array[2] = var_component for node 2 of part + var_array[3] = var_component for node 3 of part + etc. + + if Z_PER_ELEM: = 1D array containing variable component + value for each element of a particular + part and type. + + (Array will have been allocated + (number_of_elements[which_part][which_type] + 1) + long. See USERD_get_gold_part_build_info) + + Info stored in this fashion: + var_array[1] = var component for elem 1 (of part and type) + var_array[2] = var component for elem 2 (of part and type) + var_array[3] = var component for elem 3 (of part and type) + etc. + + Notes: + ----- + * Not called unless Num_variables is > 0 + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * Will be based on Current_time_step + + * If the variable is not defined for this part, simply return with a + value of Z_UNDEF. EnSight will treat the variable as undefined for + this part. + + +-------------------------------------------------------------------- +USERD_get_var_value_at_specific + + Description: + ----------- + if Z_PER_NODE: + Get the value of a particular variable at a particular node in a + particular part at a particular time. + + or if Z_PER_ELEM: + Get the value of a particular variable at a particular element of + a particular type in a particular part at a particular time. + + + Specification: + ------------- + int USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part, + int which_elem_type, + int time_step, + float values[3], + int imag_data) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) which_node_or_elem + + If Z_PER_NODE: + = The node number. This is not the id, but is + the index of the global node + list (1 based), or the block's + node list (1 based). + + Thus, coord_array[1] + coord_array[2] + coord_array[3] + . | + . |which_node_or_elem index + . ---- + + + If Z_PER_ELEM: + = The element number. This is not the id, but is + the element number index + of the number_of_element array + (see USERD_get_gold_part_build_info), + or the block's element list (1 based). + + Thus, for which_part: + conn_array[which_elem_type][0] + conn_array[which_elem_type][1] + conn_array[which_elem_type][2] + . | + . which_node_or_elem index + . ---- + + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + + (IN) which_elem_type + + If Z_PER_NODE, or block part: + = Not used + + If Z_PER_ELEM: + = The element type. This is the element type index + of the number_of_element array + (see USERD_get_gold_part_build_info) + + (IN) time_step = The time step + + (IN) imag_data = TRUE if want imaginary value. + FALSE if want real value. + + (OUT) values = scalar or vector component value(s) + values[0] = scalar or vector[0] + values[1] = vector[1] + values[2] = vector[2] + + + Notes: + ----- + * This routine is used in node querys over time (or element querys over + time for Z_PER_ELEM variables). If these operations are not critical + to you, this can be a dummy routine. + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * The time step given is for the proper variable timeset. + + +---------------------------------------------------------------------- +USERD_load_matf_data + + Description: + ----------- + Get the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_load_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *ids_list, + float *val_list) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) ids_list = If mat_type is Z_MAT_INDEX: + --------------------------- + 1D material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MAT_INDEX) + + If mat_type is Z_MIX_INDEX: + --------------------------- + 1D mixed-material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_INDEX) + + (OUT) val_list = 1D mixed-materials values list + (only used if mat_type is Z_MIX_VALUE) + + (Float array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_VALUE) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, + or Num_materials[set_index] is zero, + or the appropriate size from USERD_size_matf_data is zero + + + +-------------------------------------------------------------------- +USERD_set_filenames + + Description: + ----------- + Receives the geometry and result filenames entered in the data + dialog. The user written code will have to store and use these + as needed. The user written code must manage its own files!! + + Specification: + ------------- + int USERD_set_filenames(char filename_1[], + char filename_2[], + char the_path[], + int swapbytes) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) filename_1 = the filename entered into the geometry + field of the data dialog. + + (IN) param_2 = The usage of this string depends on + 'two_fields' in USERD_get_name_of_reader. + + If two_fields is FALSE then it's empty. + + If two_fields is TRUE, this is the + manditory results file entered + into the result field of the data dialog. + + If two_fields is -1, then this contains + optional text (filenames, modifiers, etc.) + that can be parsed and used to modify + reader + + (IN) the_path = the path info from the data dialog. + Note: filename_1 and filename_2 have already + had the path prepended to them. This + is provided in case it is needed for + filenames contained in one of the files + + (IN) swapbytes = TRUE if should swap bytes when reading data. + = FALSE normally. + + Notes: + ----- + * Since you must manage everything from the input that is entered in + these data dialog fields, this is an important routine! + + * It may be that you will need to have an executive type file that contains + info and other filenames within it, like EnSight6's case file. + + +-------------------------------------------------------------------- +USERD_set_server_number + + Description: + ----------- + Receives the server number of how many total servers. + + Specification: + ------------- + int USERD_set_server_number(int cur_serv, + int tot_servs) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) cur_serv = the current server. + + (IN) tot_servs = the total number of servers. + + Notes: + ----- + * Only useful if your user defined reader is being used with EnSight's + Server-of-Server capability. And even then, it may or may not be + something that you can take advantage of. If your data is already + partitioned in some manner, such that you can access the proper + portions using this information. + + For all non-SOS uses, this will simply be 1 of 1 + + + +-------------------------------------------------------------------- +USERD_set_time_set_and_step + + Description: + ----------- + Set the current time step in the desired timeset. All functions that + need time, and that do not explicitly pass it in, will use the timeset + and step set by this routine, if needed. + + Specification: + ------------- + void USERD_set_time_set_and_step(int timeset_number, + int time_step) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) timeset_number = the timeset number (1 based). + + For example: If USERD_get_number_of_timesets + returns 2, the valid timeset_number's + would be 1 and 2. + + (IN) time_step = The current time step to set + + Notes: + ----- + * Current_time_step and Current_timeset would be set here + + +-------------------------------------------------------------------- +USERD_size_matf_data + + Description: + ----------- + Get the length of the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_size_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *matf_size) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) matf_size = the length of the material id list, or + mixed-material id list, or + mixed-material values list + for the given material set and part number + (and element type if Z_MAT_INDEX) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_stop_part_building + + Description: + ----------- + This routine called when the part building dialog is closed. It is + provided in case you desire to release memory, etc. that was only needed + during the part building process. + + Specification: + ------------- + void USERD_stop_part_building( void ) + + Returns: + ------- + nothing + + Arguments: + --------- + none + + Notes: + ----- + +-------------------------------------------------------------------- +USERD_rigidbody_existence + + Description: + ----------- + Gets the existence of rigid body values or not in the model + + Specification: + ------------- + int USERD_rigidbody_existence( void ) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + none + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_rigidbody_values + + Description: + ----------- + Gets the rigid body values for each part + + Specification: + ------------- + int USERD_rigidbody_values(int part_number, + float values[7]) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + (IN) part_number = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) values values[0] = IX (x location) + values[1] = IY (y location) + values[2] = IZ (z location) + values[3] = E0 (e0 euler value) + values[4] = E1 (e1 euler value) + values[5] = E2 (e2 euler value) + values[6] = E3 (e3 euler value) + + + Notes: + ----- + * This will be based on Current_time_step + * It will not be called unless USERD_rigidbody_existence indicates + that there are some values in the model by returning Z_OK. + + +-------------------------------------------------------------------- +USERD_set_right_side + + Description: + ----------- + Informs the reader that the time currently set is the right side of a time + span used for variable interpolation between time steps + + Specification: + ------------- + void USERD_set_right_side( void ) + + Returns: + ------- + + Arguments: + --------- + none + + Notes: + ----- + * Applies to Current_time_step + + + + + +------------------------------------------------------------------ + ENHANCED GUI ROUTINES + +-------------------------------------------------------------------- +USERD_get_extra_gui_numbers + + Description: + ----------- + The Enhanced GUI routines are added to allow + the user to customize a portion of the Data + Reader dialog to pass in options to their + user defined reader. + + Specification: + ------------- + void USERD__get_extra_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_extra_gui_numbers + USERD_get_extra_gui_defaults + USERD_set_extra_gui_data + + The existence of these routine indicates that + you wish to add customize entries to the + Data Reader dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_extra_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_extra_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_extra_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_extra_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_extra_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_extra_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_numbers + + Description: + ----------- + The Var_Extract_GUI routines are added to allow + the user to customize a extraction parameters + for variables "after" the file has been read. + These things can be modified and the variables will + be update/refreshed according to the new parameters set + + Specification: + ------------- + void USERD_get_var_extract_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults (this one) + USERD_set_var_extract_gui_data + + The existence of these routine indicates that + you wish to have the Var Extract Parameters dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_var_extract_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_var_extract_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_var_extract_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_var_extract_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_var_extract_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + + + +----------------------------------------------------------------------------------- +/* ---------------------------------------------------------- + * New in EnSight 8 is the capability to remove (fail) elements + * based on variable threshold values. Basically the variable + * name, a couple of thresholds, a couple of values and a logic + * criteria are read in from this routine. Every element that + * satisfies the failure criteria is removed and not used in + * EnSight calculations. + * + * Example Failure criteria + * Let fail_var_name = "fail_flag" + * threshold_val1 = 0 + * threshold_operator1 = Z_EQUAL_TO + * logic_criteria2 not used + * threshold_val2 not used + * threshold_operator2 not used + * For each value of "fail_flag" at each element, + * if fail flag == threshold_val1 (0.0) then element fails + * Return (Z_ERR) if this is not used. + * Return (Z_OK) if failed element feature should be used + * + * threshold_operator1 & 2 can be one of the following + * Z_ELE_FAILED_NONE, - disables checking + * Z_ELE_FAILED_GREATER, - greater than + * Z_ELE_FAILED_LESS, - less than + * Z_ELE_FAILED_EQUAL, - equal + * Z_ELE_FAILED_NOT_EQUAL, - not equal + * Z_ELE_FAILED_MANY - not used + * + * logic_criteria2 + * Z_ELE_FAILED_LOGIC_NONE, + * Z_ELE_FAILED_LOGIC_AND, + * Z_ELE_FAILED_LOGIC_OR, + * Z_ELE_FAILED_LOGIC_MANY + * + * ---------------------------------------------------------- */ +int USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + + + +---- end of document ---- diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.06 b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.06 new file mode 100644 index 0000000000..88c4955c81 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.06 @@ -0,0 +1,4603 @@ +README_USERD_2.06 +================= +-------------------------------------- +EnSight User Defined Reader Capability ===> (API 2.06) +-------------------------------------- +A user defined reader capability is included in EnSight which can allow +otherwise unsupported structured or unstructured data to be read. The user +defined reader capability utilizes dynamic shared libraries composed of +routines defined in this document but produced by you, the user, (or some +third party). This capability is currently available for dec, ibm, hp, sgi, +sun, linux, alpha linux, and NT servers. + +You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0 +for a discussion of the differences between API 1.0 and API 2.*. + +***>> API 2.06 additional capabilities (beyond API 2.05): +Routines to allow userd defined readers for structured data +to deal with min, max, and stride within the reader itself +instead of within EnSight. + USERD_get_structured_reader_cinching + USERD_set_block_range_and_stride + + +***>> API 2.05 additional capabilities (beyond API 2.04): +Routines to handle material species. + USERD_get_number_of_species + USERD_get_matsp_info + +Routines to handle variable extraction parameters after a read, and then +update the variables accordingly. Similar to the extra GUI capabilities +(which are processed before a read). (Can actually be added to pre-2.05 readers) + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + +Routines to obtain rigid body values from a reader. +(Routines were added - EnSight is now using for Nastran and STL readers + with Dynasty rigid body motion data file) + USERD_rigidbody_existence + USERD_rigidbody_values + +Routine that lets reader know when EnSight is getting the right side of a time +interval for variable interpolation between steps. Not generally needed for +most readers - however, may be needed for those that implement rigid body, and +wish to cache left and right timespan information for interpolation within the +reader itself. (Can actually be added to pre-2.05 readers) + USERD_set_right_side + + +***>> API 2.04 additional capabilities (beyond API 2.03): +Routines to handle failed elements. Basically +a.One routine to return a flag indicating the existence of + failed elements in at least one part in at least one + timestep in the model. +b.A second routine to return a matrix of flags indexed by part and + element type indicating which parts and element types have failed + elements at the current time step. +c.Finally a third routine to return an array of flags for a given + part and element type that is number of elements of that type long + indicating which elements have failed, and which have not failed. + + +***>> API 2.03 additional capabilities (beyond API 2.01): +1. Routines to handle materials +2. Routines to handle nsided and nfaced elements +3. Modified routine to handle structured ranges + + +**************************************************************************** +Note: Only the the Ensight Gold example reader, has been moved to + this 2.06 API level. And it is purely for an example - it does not + actually provide a benefit. +**************************************************************************** + + +The process for producing a user defined reader is: +--------------------------------------------------- +1. Write code for all pertinent routines in the library (Unless someone else + has done this for you). + + This is of course where the work is done by the user. The word + "pertinent" is used because depending on the nature of the data, some + of the routines in the library may be dummy routines. + + The source code for a dummy_gold library and for various other + working or sample libraries is copied from the installation CD during + installation. These will be located in directories under: + + $CEI_HOME/ensight76/user_defined_src/readers + + examples: + -------- + Basic dummy_gold routines provide skeleton for a new reader + $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold + + Sample library which reads unstructured binary EnSight Gold data + $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold + + You may find it useful to place your library source in this area as + well, but are not limited to this location. + + * ===> The descriptions of each library routine and the order that the + routines are called, which is provided in this file, along with + the example libraries, should make it possible for you to produce + code for your own data reader. + + +2. Produce the dynamic shared library. + + This is a compiling and loading process which varies according to + the type of machine you are on. In the user-defined-reader source + tree we have tried to isolate the machine dependent parts of the + build process using a set of files in the 'config' directory. In this + directory there is a configuration file for each platform on which + EnSight is supported. Before you can compile the installed readers + you should run the script called 'init' in the config directory. + + i.e. (for UNIX) + cd config + ./init sgi_6.5_n64 + cd .. + make + + If you are compiling for Windows NT, there are two options. If you + have the Cygwin GNU utilities installed, you can use GNU make as for + Unix. Otherwise, there is a script called makeall.cmd which will + build all of the readers using nmake. The Makefiles in each reader + directory will work using either make or nmake. + + i.e. (WIN32 Cygwin) (using nmake) + cd config cd config + sh init win32 cp win32 config + cd .. cd .. + mkdir lib + make makeall.cmd + + If you have platform-specific portions of code in your reader, the + build system defines a set of flags which can be used within + #ifdef ... #endif regions in your source, as shown in the table + below. + + Because the readers are now dynamically opened by EnSight, you may + have to include dependent libraries on your link-line to avoid having + unresolved symbols. If you are having problems with a reader, start + ensight as "ensight7 -readerdbg" and you will get feedback on any + problems encountered in loading a reader. If there are unresolved + symbols, you need to find the library which contains the missing + symbols and link it into your reader by adding it to the example + link commands below. + + If you choose to use a different build environment for your reader, + you should take care to use compatible compilation flags to ensure + compatibilty with the EnSight executables, most notably on the SGI + and HP-UX 11.0 platforms, which should use the following flags: + + sgi_6.2_o32: -mips2 + sgi_6.2_n64: -mips4 -64 + sgi_6.5_n32: -mips3 + sgi_6.5_n64: -mips4 -64 + hp_11.0_32: +DA2.0 + hp_11.0_64: +DA2.0W + + ______________________________________________________________________ + | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED | + | TYPE |------------------------------------------------------------| + | | LD COMMAND USED IN MAKEFILE | + ====================================================================== + ______________________________________________________________________ + | sgi | -DSGI | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | hp | -DHP | libuserd-X.sl | + | |------------------------------------------------------------| + | | ld -b -o libuserd-X.sl libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | sun | -DSUN | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | dec | -DDEC | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | linux | -DLINUX | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | alpha | -DALINUX | libuserd-X.so | + | linux |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | ibm | -DIBM | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc | + ---------------------------------------------------------------------- + + Once you have created your library, you should place it in a directory + of your choice or in the standard reader location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + For example, if you created a reader for "mydata", you should create + the reader libuserd-mydata.so and place the file in your own reader + directory (see section 3 below) or in the standard location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so + + +3. By default EnSight will load all readers found in the directory: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + Files with names "libuserd-X.so" (where X is a name unique to the reader) + are assumed to be user-defined readers. + + There are two methods which can be used to supplement the default + behavior. + + (1) A feature which is useful for site-level or user-level configuration + is the optional environment variable $ENSIGHT7_READER. This + variable directs EnSight to load all readers in the specified reader + directory (you should probably specify a full path) before loading + the built-in readers. If the same reader exists in both directories + (as determined by the name returned by USERD_get_name_of_reader(), + NOT by the filename), the locally configured reader will take + precedence. + + (2) A useful feature for end-users is the use of the libuserd-devel + reader. EnSight will search for a reader named libuserd-devel.so + (.sl for HP or .dll for NT). This reader can exist anywhere in the + library path (see below) of the user. This is useful for an + individual actively developing a reader because the existence of a + libuserd-devel library will take precedence over any other library + which returns the same name from USERD_get_name_of_reader(). + + As an example, a site may install commonly used readers in a common + location, and users can set the ENSIGHT7_READER variable to access them: + + setenv ENSIGHT7_READER /usr/local/lib/e7readers + + A user working on a new reader may compile the reader and place it in + a directory specified by the library path: + + cp libuserd-myreader.so ~/lib/libuserd-devel.so + setenv ~/lib:$ + + The user is responsible for correctly configuring the library path + variable in order to make use of the libuserd-devel feature. The + library environment variables used are: + + Machine type Environment variable to set + ------------ --------------------------- + sgi LD_LIBRARY_PATH + dec LD_LIBRARY_PATH + sun LD_LIBRARY_PATH + linux LD_LIBRARY_PATH + alpha linux LD_LIBRARY_PATH + hp SHLIB_PATH + ibm LIBPATH + +As always, EnSight support is available if you need it. + +------------------------------- +Quick Index of Library Routines +------------------------------- + +Generally Needed for UNSTRUCTURED data +-------------------------------------- +USERD_get_part_coords part's node coordinates +USERD_get_part_node_ids part's node ids +USERD_get_part_elements_by_type part's element connectivites +USERD_get_part_element_ids_by_type part's element ids + + +Generally Needed for BLOCK data +-------------------------------------- +USERD_get_block_coords_by_component block coordinates +USERD_get_block_iblanking block iblanking values +USERD_get_ghosts_in_block_flag block ghost cell existence? +USERD_get_block_ghost_flags block ghost cell flags + + These routines, which formerly were only for unstructured data, will now + also be called for structured data if you specify that ids will be given + in the USERD_get_node_label_status and USERD_get_element_label_status rotuines + ------------------------------------------------------------------------------ + USERD_get_part_node_ids part's node ids + USERD_get_part_element_ids_by_type part's element ids + + +Generally needed for either or both kinds of data +------------------------------------------------- +USERD_get_name_of_reader name of reader for GUI +USERD_get_reader_release release string of reader +USERD_get_reader_version provide reader version number +USERD_get_reader_descrip provide GUI more description (optional) + +USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields +USERD_get_extra_gui_defaults Gets the default values for the GUI members +USERD_set_extra_gui_data Returns the answers provided by the user + +USERD_set_filenames filenames entered in GUI +USERD_set_server_number server which of how many + +USERD_get_number_of_timesets number of timesets +USERD_get_timeset_description description of timeset +USERD_get_geom_timeset_number timeset # to use for geom + +USERD_get_num_of_time_steps number of time steps +USERD_get_sol_times solution time values +USERD_set_time_set_and_step current timeset and time step + +USERD_get_changing_geometry_status changing geometry? +USERD_get_node_label_status node labels? +USERD_get_element_label_status element labels? +USERD_get_model_extents provide model bounding extents +USERD_get_number_of_files_in_dataset number of files in model +USERD_get_dataset_query_file_info info about each model file +USERD_get_descrip_lines file associated description lines +USERD_get_number_of_model_parts number of model parts +USERD_get_gold_part_build_info Gets the info needed for part building process +USERD_get_part_build_info part/block type/descrip etc. +USERD_get_maxsize_info part/block allocation maximums +USERD_get_ghosts_in_model_flag model contains ghost cells? +USERD_get_nsided_conn Gets the element connectivities for nsided + elements. (utilizes the number of nodes + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced + elements (utilizes the number of faces + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_conn Gets the element connectivities for nfaced + elements (utilizes the number of nodes + per face obtained in + USERD_get_nfaced_nodes_per_face) + + +USERD_get_border_availability part border provided? +USERD_get_border_elements_by_type part border conn and parent info + +USERD_get_number_of_variables number of variables +USERD_get_gold_variable_info variable type/descrip etc. +USERD_get_var_by_component part or block variable values +USERD_get_constant_val constant variable's value +USERD_get_var_value_at_specific node's or element's variable value over time +USERD_stop_part_building cleanup after part build routine + +USERD_get_number_of_material_sets Gets the number of material sets +USERD_get_matf_set_info Gets the material set indices and names +USERD_get_number_of_materials Gets the number of materials +USERD_get_matf_var_info Gets the material indices and descriptions +USERD_size_matf_data Gets the length of either the + material ids list, + mixed-material ids list, or + mixed-material values list +USERD_load_matf_data Gets the material ids list, + mixed-material ids list, or + mixed-material values list + +USERD_bkup archive routine + +USERD_exit_routine cleanup upon exit routine + +USERD_get_uns_failed_params Gets thresholds/criteria for failure + +USERD_rigidbody_existence Returns whether rigid body transformation + data exists for the model. +USERD_rigidbody_values Returns the euler and location values for a + given part + +USERD_set_right_side Simply informs the reader when the time set + is for the right side of a time span during + variable interpolation between time steps. + +USERD_get_structured_reader_cinching Tells if the reader will do structured + cinching +USERD_set_block_range_and_stride Sets the min, max, and stride of a block + if doing structured cinching + + +------------------------- +Order Routines are called +------------------------- + +The various main operations are given basically in the order they will +be performed. Within each operation, the order the routines will be +called is given. + +1. Setting name in the gui, and specifying one or two input fields + + USERD_get_name_of_reader + USERD_get_reader_descrip (optional) + USERD_get_extra_gui_numbers (optional) + USERD_get_extra_gui_defaults (optional) + +2. Getting the reader version (also distinguishes between API's) + + USERD_get_reader_version + +3. Setting filenames and getting timeset and time info + + (optional if reader has + USERD_get_extra_gui_defaults routine) + USERD_get_structured_reader_cinching + USERD_set_server_number + USERD_set_extra_gui_data (optional) + USERD_set_filenames + USERD_get_number_of_timesets + USERD_get_geom_timeset_number + + for each timeset: + USERD_get_timeset_description + USERD_get_num_of_time_steps + USERD_get_sol_times + + USERD_set_time_set_and_step + +4. Gathering info for part builder + + USERD_set_time_set_and_step + USERD_get_changing_geometry_status + USERD_get_node_label_status + USERD_get_element_label_status + USERD_get_number_of_files_in_dataset + USERD_get_dataset_query_file_info + USERD_get_descrip_lines (for geometry) + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_maxsize_info + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR (for model extents) + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + +5. Gathering Variable info + + USERD_get_number_of_variables + USERD_get_gold_variable_info + +6. Part building (per part created) + + both unstructured and structured: + -------------------------------- + USERD_set_time_set_and_step + + if unstructured part: + -------------------- + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + + If any nsided elements: + + USERD_get_nsided_conn + + If any nfaced elements: + + USERD_get_nfaced_nodes_per_face + USERD_get_nfaced_conn + + USERD_get_part_coords + USERD_get_part_node_ids + + else if structured part: + ----------------------- + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + both again: + ---------- + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + USERD_stop_part_building (only once when part builder + dialog is closed) + +7. Loading Variables + + constants: + --------- + USERD_set_time_set_and_step + USERD_get_constant_val + + scalars/vectors/tensors: + ------------------------ + USERD_get_descrip_lines + USERD_set_time_set_and_step + (if doing structured reader cinching + USERD_get_var_by_component + +8. Changing geometry + + changing coords only (per part): + -------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_part_coords + (if doing structured reader cinching + USERD_get_block_coords_by_component + + changing connectivity (per part): + --------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + USERD_get_part_coords + USERD_get_part_node_ids + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + +9. Node or Element queries over time + + USERD_get_var_value_at_specific + +10. To see if materials in the model + + USERD_get_number_of_material_sets + USERD_get_matf_set_info + + If any material sets in the model (calls these once per material set): + USERD_get_number_of_materials + USERD_get_matf_var_info + + For each elment type of each part containing material ids, calls: + USERD_size_matf_data + USERD_load_matf_data + + If there are any elements with mixed materials, when a domain or + interface is created, calls these again per part: + + USERD_size_matf_data + USERD_load_matf_data + +11. To modify the variable extraction parameters and have the variables + update accordingly. + + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + + + +----------------------- +Detailed Specifications +----------------------- + +Include files: +-------------- +The following header file is required in any file containing these library +routines. + + #include "global_extern.h" + +And it references: + + #include "global_extern_proto.h" + + + +******************************************************************************* +****************************** Special Note *********************************** +******************************************************************************* + +Make sure you use the proper define in the global_extern.h header file, namely: +#define USERD_API_204 + +Also, Make sure the api version in the USERD_get_reader_version routine is set +to "2.04" or larger. + +Make sure your reader has access to the global_extern_proto.h This is a new +file which is accessed from the new global_extern.h + +******************************************************************************* +******************************************************************************* + + +Basis of arrays: +--------------- +Unless explicitly stated otherwise, all arrays are zero based - in true C +fashion. + + +Global variables: +---------------- +You will generally need to have a few global variables which are shared by +the various library routines. The detailed specifications below have assumed +the following are available. (Their names describe their purpose, and they +will be used in helping describe the details of the routines below). + +static int Numparts_available = 0; +static int Num_unstructured_parts = 0; +static int Num_structured_blocks = 0; + +/* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */ + +static int Num_timesets = 1; +static int Current_timeset = 1; +static int Geom_timeset_number = 1; + +static int Num_time_steps[Z_MAXSETS] = 1; +static int Current_time_step = 0; +static int Num_variables = 0; +static int Num_dataset_files = 0; + +static int Server_Number = 1; Which server of +static int Tot_Servers = 1; the total number of servers + + + +_________________________________________ +----------------------------------------- +Library Routines (in alphabetical order): +_________________________________________ +----------------------------------------- + +-------------------------------------------------------------------- +USERD_bkup + + Description: + ----------- + This routine is called during the EnSight archive process. You can + use it to save or restore info relating to your user defined reader. + + Specification: + ------------- + int USERD_bkup(FILE *archive_file, + int backup_type) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) archive_file = The archive file pointer + + (IN) backup_type = Z_SAVE_ARCHIVE for saving archive + Z_REST_ARCHIVE for restoring archive + + Notes: + ----- + * Since EnSight's archive file is saved in binary form, you should + also do any writing to it or reading from it in binary. + + * You should archive any variables, which will be needed for + future operations, that will not be read or computed again + before they will be needed. These are typically global + variables. + + * Make sure that the number of bytes that you write on a save and + the number of bytes that you read on a restore are identical!! + + * If any of the variables you save are allocated arrays, you must + do the allocations before restoring into them. + +-------------------------------------------------------------------- +USERD_exit_routine + + Description: + ----------- + This routine is called as EnSight is exiting. It can be used to clean + up anything needed - such as removing temporary files, etc. - or can simply + be a dummy. + + Specification: + ------------- + void USERD_exit_routine( void ) + + Arguments: + --------- + none + +-------------------------------------------------------------------- +USERD_get_block_coords_by_component + + Description: + ----------- + Get the coordinates of a given structured block, a component at a time. + + Specification: + ------------- + int USERD_get_block_coords_by_component(int block_number, + int which_component, + float *coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) which_component = Z_COMPX if x component wanted + = Z_COMPY if y component wanted + = Z_COMPZ if z component wanted + + (OUT) coord_array = 1D array containing x,y, or z + coordinate component of each node + + (Array will have been allocated + i*j*k for the block long) + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_block_iblanking + + Description: + ----------- + Get the iblanking value at each node of a block (if the block is + iblanked). + + Specification: + ------------- + int USERD_get_block_iblanking(int block_number, + int *iblank_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) iblank_array = 1D array containing iblank value + for each node. + + (Array will have been allocated + i*j*k for the block long) + + possible values are: Z_EXT = exterior + Z_INT = interior + Z_BND = boundary + Z_INTBND = internal boundary + Z_SYM = symmetry plane + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 and you have + some iblanked blocks + + * Will be based on Current_time_step + + + +---------------------------------------------------------------------- +USERD_get_block_ghost_flags + + Description: + ----------- + Get the ghost_flags value at each element of a block containing ghost cells. + + Specification: + ------------- + int USERD_get_block_ghost_flags(int block_number, + int *ghost_flags) + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) ghost_flags = 1D array containing ghost flag value + for each block cell. + + (Array will have been allocated + (i-1)*(j-1)*(k-1) for the block long) + + possible values are: 0 = non-ghost cell (normal cell) + >0 = ghost cell + + Notes: + ----- + * This routine is new in the 2.01 API + + * This will be based on Current_time_step + + * Only called for structured "block" parts that have some ghost cells + as indicated by the USERD_get_ghost_in_block_flag. The model must + of course also have been indicated to have some ghost cells in the + USERD_get_ghost_in_model_flag routine. + + * It is sufficient to set the value to be 1 to flag as a ghost cell, + but the value can be any non-zero value, so you could use it to + indicate which block or which server (for Server-of-server use) the + cell is actually in. + + + +-------------------------------------------------------------------- +USERD_get_border_availability + + Description: + ----------- + Finds out if border elements are provided by the reader for the + desired part, or will need to be computed internally by EnSight. + + Specification: + ------------- + int USERD_get_border_availability(int part_number, + int number_of_elements[Z_MAXTYPE]) + + Returns: + ------- + Z_OK if border elements will be provided by the reader. + (number_of_elements array will be loaded and + USERD_get_border_elements_by_type will be called) + + Z_ERR if border elements are not available - thus EnSight must compute. + (USERD_get_border_elements_by_type will not be called) + + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) number_of_elements = 2D array containing number of + each type of border element in + the part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + + Notes: + ----- + * Only called if border representation is used. + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_border_elements_by_type + + Description: + ----------- + Provides border element connectivity and parent information. + + Specification: + ------------- + int USERD_get_border_elements_by_type(int part_number, + int element_type, + int **conn_array, + short *parent_element_type, + int *parent_element_num) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + + (OUT) conn_array = 2D array containing connectivity + of each border element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_QUA08] = 30 + as obtained in: + USERD_get_border_availability + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_QUA08 + + (OUT) parent_element_type = 1D array containing element type of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + (OUT) parent_element_num = 1D array containing element number of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + + Notes: + ----- + * Not called unless USERD_get_border_availability returned Z_OK + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_changing_geometry_status + + Description: + ----------- + Gets the changing geometry status for the model + + Specification: + ------------- + int USERD_get_changing_geometry_status( void ) + + Returns: + ------- + Z_STATIC if geometry does not change + Z_CHANGE_COORDS if changing coordinates only + Z_CHANGE_CONN if changing connectivity + + Arguments: + --------- + none + + Notes: + ----- + * EnSight does not support changing number of parts. But the + coords and/or the connectivity of the parts can change. Note that + a part is allowed to be empty (number of nodes and elements equal + to zero). + + +-------------------------------------------------------------------- +USERD_get_constant_val + + Description: + ----------- + Get the value of a constant at a time step + + Specification: + ------------- + float USERD_get_constant_value(int which_var, + int imag_data) + + Returns: + ------- + Value of the requested constant variable + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) imag_data = TRUE if want imaginary data value. + FALSE if want real data value. + + Notes: + ----- + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_dataset_query_file_info + + Description: + ----------- + Get the information about files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_dataset_query_file_info(Z_QFILES *qfiles) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) qfiles = Structure containing information about each file + of the dataset. The Z_QFILES structure is defined + in the global_extern.h file + + (The structure will have been allocated + Num_dataset_files long, with 10 description + lines per file). + + qfiles[].name = The name of the file + (Z_MAXFILENP is the dimensioned length + of the name) + + qfiles[].sizeb = The number of bytes in the file + (Typically obtained with a call to the + "stat" system routine) (Is a long) + + qfiles[].timemod = The time the file was last modified + (Z_MAXTIMLEN is the dimensioned length + of this string) + (Typically obtained with a call to the + "stat" system routine) + + qfiles[].num_d_lines = The number of description lines you + are providing from the file. Max = 10 + + qfiles[].f_desc[] = The description line(s) per file, + qfiles[].num_d_lines of them + (Z_MAXFILENP is the allocated length of + each line) + + Notes: + ----- + * If Num_dataset_files is 0, this routine will not be called. + (See USERD_get_number_of_files_in_dataset) + + +-------------------------------------------------------------------- +USERD_get_descrip_lines + + Description: + ----------- + Get two description lines associated with geometry per time step, + or one description line associated with a variable per time step. + + Specification: + ------------- + int USERD_get_descrip_lines(int which_type, + int which_var, + int imag_data, + char line1[Z_BUFL], + char line2[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_type = Z_GEOM for geometry (2 lines) + = Z_VARI for variable (1 line) + + (IN) which_var = If it is a variable, which one. + Ignored if geometry type. + + (IN) imag_data = TRUE if want imaginary data file. + FALSE if want real data file. + + (OUT) line1 = The 1st geometry description line, + or the variable description line. + + (OUT) line2 = The 2nd geometry description line + Not used if variable type. + + Notes: + ----- + * Will be based on Current_time_step + + * These are the lines EnSight can echo to the screen in + annotation mode. + + + +-------------------------------------------------------------------- +USERD_get_element_label_status + + Description: + ----------- + Answers the question as to whether element labels will be provided. + + Specification: + ------------- + int USERD_get_element_label_status( void ) + + Returns: + ------- + TRUE if element labels will be provided + FALSE if element labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * element lables are needed in order to do any element querying, or + element labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. + + API 1.0: + USERD_get_element_ids_for_part is used to obtain the ids, + on a part by part basis, if TRUE status is returned here. + + API 2.0: + USERD_get_part_element_ids_by_type is used to obtain the ids, + on a per part, per type basis, if TRUE status is returned here. + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them youself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model (especially + if you are dealing with a decomposed dataset). + + USERD_get_part_element_ids_by_type is used to obtain the ids, + on an element type by part basis, if TRUE status is returned here. + + * Will call USERD_get_part_element_ids_by_type for each type of + of each part if this routine returns TRUE. +-------------------------------------------------------------------- +USERD_get_geom_timeset_number - + + Description: + ----------- + Gets the timeset number to be used for geometry + + Specification: + ------------- + int USERD_get_geom_timeset_number( void ) + + Returns: + ------- + Geom_timeset_number = The timeset number that will be used for geometry. + For example, if USERD_get_number_of timesets + returns 2, the valid timeset numbers would be + 1 or 2. + + Arguments: + --------- + none + + Notes: + ----- + * If your model is static, which you indicated by returning a zero + in USERD_get_number_of_timesets, you can return a zero here as well. + + + +-------------------------------------------------------------------- +USERD_get_gold_part_build_info + + Description: + ----------- + Gets the info needed for the part building process. + + Specification: + ------------- + int USERD_get_gold_part_build_info(int *part_id, + int *part_types, + char *part_description[Z_BUFL], + int *number_of_nodes, + int *number_of_elements[Z_MAXTYPE], + int *ijk_dimensions[9], + int *iblanking_options[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) part_id = Array containing the external part + ids for each of the model parts. + + IMPORTANT: + Parts numbers must be >= 1, because + of the way they are used in the GUI + + ******************************************* + The ids provided here are the numbers by + which the parts will be referred to in the + GUI (if possible). They are basically + labels as far as you are concerned. + + Note: The part numbers you pass to routines + which receive a part_number or block_number + or which_part as an argument are the 1-based + table index of the parts! + + example: If Numparts_available = 3 + + Table index part_id + ----------- ------- + 1 13 + 2 57 + 3 125 + + ^ ^ + | | + | These are placed in: + | part_id[0] = 13 + | part_id[1] = 57 + | part_id[2] = 125 + | for GUI labeling purposes. + | + These implied table indices are the part_number, + block_number, or which_part numbers that you would + pass to routines like: + + USERD_get_part_coords(int part_number,... + USERD_get_part_node_ids(int part_number,... + USERD_get_part_elements_by_type(int part_number,... + USERD_get_part_element_ids_by_type(int part_number,... + USERD_get_block_coords_by_component(int block_number,... + USERD_get_block_iblanking(int block_number,... + USERD_get_block_ghost_flags(int block_number,... + USERD_get_ghosts_in_block_flag(int block_number) + USERD_get_border_availability(int part_number,... + USERD_get_border_elements_by_type(int part_number,... + USERD_get_var_by_component(int which_variable, + int which_part,... + USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part,... + ******************************************** + + (Array will have been allocated + Numparts_available long) + + (OUT) part_types = Array containing one of the + following for each model part: + + Z_UNSTRUCTURED or + Z_STRUCTURED or + Z_IBLANKED + + (Array will have been allocated + Numparts_available long) + + (OUT) part_description = Array containing a description + for each of the model parts + + (Array will have been allocated + Numparts_available by Z_BUFL + long) + + (OUT) number_of_nodes = Number of unstructured nodes in the part + + (Array will have been allocated + Numparts_available long) + + (OUT) number_of_elements = 2D array containing number of + each type of element for each + unstructured model part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) ijk_dimensions = 2D array containing ijk dimension info + for structured blocks + + For Z_UNSTRUCTURED - is ignored + + For Z_STRUCTURED or Z_IBLANKED + + Prior to version 2.03: + ---------------------- + (Array will have been allocated + Numparts_available by 3 long) + + ijk_dimensions[][0] = I dimension + ijk_dimensions[][1] = J dimension + ijk_dimensions[][2] = K dimension + + + Starting at version 2.03: + ------------------------ + (Array will have been allocated + Numparts_available by 9 long) + + There are two ways to do this: + ------------------------------ + 1. The simple one, without ranges. + + This is good for all structured models + that will NOT be used in EnSight's + Server of Servers + + Simply provide the ijk dimensions in the + first three slots and place a -1 in + the 4th slot. (The remaining slots will + be ignored). + + Thus, + ijk_dimensions[][0] = I dimension of block + ijk_dimensions[][1] = J dimension of block + ijk_dimensions[][2] = K dimension of block + ijk_dimensions[][3] = -1 + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][4] = -1 + | | | + | | | + 2 *-------*-------* + | | | + | | | + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + + 2. Using ranges. + + This one can be used anytime, but MUST + be used if EnSight's Server of Servers + is to be used! + + The first 3 slots contain the ijk dimension + of the complete block (of which this may be + a portion). The last 6 slots contain the + ijk min and max ranges within the complete. + + Thus, + ijk_dimensions[][0] = I dim of complete block + ijk_dimensions[][1] = J dim of complete block + ijk_dimensions[][2] = K dim of complete block + + ijk_dimensions[][3] = Imin of portion (1-based) + ijk_dimensions[][4] = Imax of portion (1-based) + ijk_dimensions[][5] = Jmin of portion (1-based) + ijk_dimensions[][6] = Jmax of portion (1-based) + ijk_dimensions[][7] = Kmin of portion (1-based) + ijk_dimensions[][8] = Kmax of portion (1-based) + + + example1: (Model has one part, a simple 2D block, + and want whole thing) + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][3] = 1 + | | | ijk_dimension[0][4] = 3 + | | | ijk_dimension[0][5] = 1 + 2 *-------*-------* ijk_dimension[0][6] = 4 + | | | ijk_dimension[0][7] = 1 + | | | ijk_dimension[0][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + example2: (Want to have the block represented + in two portions - 2 parts) + + (J planes) top portion + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + . . . ijk_dimension[0][3] = 1 + . . . ijk_dimension[0][4] = 3 + . . . ijk_dimension[0][5] = 3 + 2 ................. ijk_dimension[0][6] = 4 + . . . ijk_dimension[0][7] = 1 + . . . ijk_dimension[0][8] = 1 + . . . + 1 ................. + 1 2 3 (I planes) + + + (J planes) bottom portion + 4 ................. + . . . ijk_dimension[1][0] = 3 + . . . ijk_dimension[2][1] = 4 + . . . ijk_dimension[3][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[1][3] = 1 + | | | ijk_dimension[1][4] = 3 + | | | ijk_dimension[1][5] = 1 + 2 *-------*-------* ijk_dimension[1][6] = 3 + | | | ijk_dimension[1][7] = 1 + | | | ijk_dimension[1][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + And note that if you were partioning this block for + EnSight's Server of Servers, you would only have one part, + instead of two. Each SOS server would return its appropriate + ranges in the last 6 slots. The first 3 slots would remain constant. + + + (OUT) iblanking_options = 2D array containing iblanking + options possible for each + structured model part. + ---------- + (Ignored unless Z_IBLANKED type) + + (Array will have been allocated + Numparts_available by 6 long) + + iblanking_options[][Z_EXT] = TRUE if external (outside) + [][Z_INT] = TRUE if internal (inside) + [][Z_BND] = TRUE if boundary + [][Z_INTBND] = TRUE if internal boundary + [][Z_SYM] = TRUE if symmetry surface + + + Notes: + ----- + * If you haven't built a table of pointers to the different parts, + you might want to do so here as you gather the needed info. + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_gold_variable_info + + Description: + ----------- + Get the variable descriptions, types and filenames + + Specification: + ------------- + int USERD_get_gold_variable_info(char **var_description, + char **var_filename, + int *var_type, + int *var_classify, + int *var_complex, + char **var_ifilename, + float *var_freq, + int *var_contran, + int *var_timeset) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) var_description = Variable descriptions + + (Array will have been allocated + Num_variables by Z_BUFL long) + + variable description restrictions: + ---------------------------------- + 1. Only first 19 characters used in EnSight. + 2. Leading and trailing whitespace will be removed by EnSight. + 3. Illegal characters will be replaced by underscores. + 4. Thay may not start with a numeric digit. + 4. No two variables may have the same description. + + + (OUT) var_filename = Variable real filenames + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_type = Variable type + + (Array will have been allocated + Num_variables long) + + types are: Z_CONSTANT + Z_SCALAR + Z_VECTOR + Z_TENSOR + Z_TENSOR9 + + (OUT) var_classify = Variable classification + + (Array will have been allocated + Num_variables long) + + types are: Z_PER_NODE + Z_PER_ELEM + + (OUT) var_complex = TRUE if complex, FALSE otherwise + + (Array will have been allocated + Num_variables long) + + (OUT) var_ifilename = Variable imaginary filenames (if complex) + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_freq = complex frequency (if complex) + + (Array will have been allocated + Num_variables long) + + (OUT) var_contran = TRUE if constant changes per time step + FALSE if constant truly same at all time steps + + (Array will have been allocated + Num_variables long) + + (OUT) var_timeset = Timeset the variable will use (1 based). + (For static models, set it to 1) + + (Array will have been allocated + Num_variables long) + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 or 2 + + + Notes: + ----- + * The implied variable numbers apply, but be aware that the + arrays are zero based. + So for variable 1, will need to provide var_description[0] + var_filename[0] + var_type[0] + var_classify[0] + var_complex[0] + var_ifilename[0] + var_freq[0] + var_contran[0] + var_timeset[0] + + + for variable 2, will need to provide var_description[1] + var_filename[1] + var_type[1] + var_classify[1] + var_complex[1] + var_ifilename[1] + var_freq[1] + var_contran[1] + var_timeset[1] + etc. + + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_block_flag + + Description: + ----------- + Gets whether ghost cells present in block or not + + Specification: + ------------- + int USERD_get_ghosts_in_block_flag(int block_number) + + Returns: + ------- + TRUE if any ghost cells in this structured part + FALSE if no ghost cells in this structured part + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Notes: + ----- + * This routine is new in the 2.01 API + * This will be based on Current_time_step + + * Intended for structured parts only, value will be ignored for + unstructured parts + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_model_flag + + Description: + ----------- + Answers the question as to whether any ghost cells in the model. + + Specification: + ------------- + int USERD_get_ghosts_in_model_flag( void ) + + Returns: + ------- + TRUE if any ghost cells in the model + FALSE if no ghost cells in the model + + Arguments: + --------- + + Notes: + ----- + * This routine is new in the 2.01 API + +------------------------------------------------------------------------- +USERD_get_matf_set_info + + Description: + ----------- + Get the material set ids and names + + Specification: + ------------- + int USERD_get_matf_set_info(int *mat_set_ids, + char **mat_set_name) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) mat_set_ids = 1D material set ids array + + (Array will have been allocated + Num_material_sets long) + + (OUT) mat_set_name = 2D material set name array + + (Array will have been allocated + Num_material_sets by Z_BUFL long) + + Notes: + ----- + * Will not be called if Num_material_sets is zero + * See USERD_get_number_of_material_sets header for explanatory example + + +-------------------------------------------------------------------- +USERD_get_matf_var_info + + Description: + ----------- + Gets the material ids and descriptions for the material set + + Specification: + ------------- + int USERD_get_matf_var_info(int set_index, + int *mat_ids, + char **mat_desc) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (OUT) mat_ids[set_index] = 1D integer array containing the material + ids to associated with each material + + (Array will have been allocated + Num_materials[set_index] long) + + (OUT) mat_desc[set_index] = 2D char array containing the material + descriptions to associated with each material + + (Array will have been allocated + Num_materials[set_index] by Z_BUFL long) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_get_maxsize_info + + Description: + ----------- + Gets maximum part sizes for efficient memory allocation. + + Transient models (especially those that increase in size) can cause + reallocations, at time step changes, to keep chewing up more and + more memory. The way to avoid this is to know what the maximum + size of such memory will be, and allocate for this maximum initially. + + Accordingly, if you choose to provide this information (it is optional), + EnSight will take advantage of it. + + + Specification: + ------------- + int USERD_get_maxsize_info(int *max_number_of_nodes, + int *max_number_of_elements[Z_MAXTYPE], + int *max_ijk_dimensions[3]) + + Returns: + ------- + Z_OK if supplying maximum data + Z_ERR if not supplying maximum data, or some error occurred + while trying to obtain it. + + Arguments: + --------- + (OUT) max_number_of_nodes = Maximum number of unstructured nodes + in the part (over all time). + + (Array will have been allocated + Numparts_available long) + + (OUT) max_number_of_elements = 2D array containing maximum number of + each type of element for each + unstructured model part (over all time). + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions + for each structured model part (over all time). + ---------- + (Ignored if Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by 3 long) + + max_ijk_dimensions[][0] = maximum I dimension + max_ijk_dimensions[][1] = maximum J dimension + max_ijk_dimensions[][2] = maximum K dimension + + Notes: + ----- + * You need to have first called USERD_get_number_of_model_parts and + USERD_get_gold_part_build_info, so Numparts_available is known and + so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED, + or Z_IBLANKED) of each part. + + * This will NOT be based on Current_time_step - it is to be the maximum + values over all time!! + + * This information is optional. If you return Z_ERR, Ensight will still + process things fine, reallocating as needed, etc. However, for + large transient models you will likely use considerably more memory + and take more processing time for the memory reallocations. So, if it + is possible to provide this information "up front", it is recommended + to do so. + + +-------------------------------------------------------------------- +USERD_get_model_extents + + Description: + ----------- + Gets the model bounding box extents. If this routine supplys them + EnSight will not have to spend time doing so. If this routine + returns Z_ERR, EnSight will have to take the time to touch all the + nodes and gather the extent info. + + Specification: + ------------- + int USERD_get_model_extents(float extents[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (whereupon EnSight will determine by reading + all coords of all parts) + + Arguments: + --------- + (OUT) extents[0] = min x + [1] = max x + [2] = min y + [3] = max y + [4] = min z + [5] = max z + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_name_of_reader + + Description: + ----------- + Gets the name of your user defined reader. The user interface will + ask for this and include it in the available reader list. + + Specification: + ------------- + int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], + int *two_fields) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) reader_name = the name of the your reader or data format. + (max length is Z_MAX_USERD_NAME, which is 20) + + (OUT) two_fields = FALSE if only one data field is + required. + TRUE if two data fields required + + -1 if one field (Geom) required + and one field (Param) is optional + Param field can contain any text + for example a file name, modifiers, + etc. that can be used to modify the + reader's behavior. + + + Notes: + ----- + * Always called. Please be sure to provide a name for your custom + reader format. + +-------------------------------------------------------------------- +USERD_get_nfaced_conn + + Description: + ----------- + Gets the array containing the connectivity of nsided faces of nfaced elements + + Specification: + -------------int + int USERD_get_nfaced_conn(int part_number, + int *nfaced_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced + elements + + (int array will have been allocated long enough to + hold all the nsided face connectivities. Which is + the sum of all the nodes per face values in the + nfaced_npf_array of USERD_get_nfaced_nodes_per_face) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In USERD_get_faced_nodes_per_face: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In this function: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + +-------------------------------------------------------------------- +USERD_get_nfaced_nodes_per_face - + + Description: + ----------- + Gets the array containing the number of nodes per face for each face + of the nfaced elements. + + Specification: + ------------- + int USERD_get_nfaced_nodes_per_face(int part_number, + int *nfaced_npf_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of + nfaced elements + + (int array will have been allocated long enough + to hold all the nodes_per_face values. Which is + the sum of all the number of faces per element + values in the conn_array of + USERD_get_part_elements_by_type) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the + the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In this routine: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In USERD_get_nfaced_conn: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + + +-------------------------------------------------------------------- +USERD_get_node_label_status + + Description: + ----------- + Answers the question as to whether node labels will be provided. + + Specification: + ------------- + int USERD_get_node_label_status( void ) + + Returns: + ------- + TRUE if node labels will be provided + FALSE if node labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * Node ids are needed in order to do any node querying, or node + labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. They must also be + positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + (Unlike API 1.0, where the connectivity of elements had to be + according to the node ids - API 2.0's element connectivities + are not affected either way by the status here.) + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them yourself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model. They must + also be positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + * Will call USERD_get_part_node_ids for each part if this routine + returns TRUE. + +-------------------------------------------------------------------- +USERD_get_nsided_conn - + + Description: + ----------- + Gets the array containing the connectivity of nsided elements + + Specification: + ------------- + int USERD_get_nsided_conn(int part_number, + int *nsided_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nsided_conn_array = 1D array of nsided connectivies + + (int array will have been allocated long enough + to hold all the nsided connectivities. Which is + the sum of all the nodes_per_element values in + the conn_array of USERD_get_part_elements_by_type) + + + Notes: + ----- + * Will not be called unless there are some nsided elements in the the part. + + * Providing nsided information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nsided + elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of nodes per nsided element. (as if connectivity + length of an nsided element is one) + + 3. In this routine, provide the streamed connectivities for each of the + nsided elements. + + + Simple example: 5 6 + +--------+ + 3 nsided elements: /| \ + (1 4-sided / | \ + 1 3-sided / | \ + 1 7-sided) / | \ 7 + /3 |4 + + +-----+ | + | | | + | | |8 + | | + + | | / + | | / + | | / + |1 |2 /9 + +-----+--------+ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NSIDED] = 3 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 3 x 1 + + for element_type of Z_NSIDED: + conn_array[0][0] = 4 (for the 4-sided element) + conn_array[1][0] = 3 (for the 3-sided element) + conn_array[2][0] = 7 (for the 7-sided element) + + Sum === + 14 <---------+ + | + 3. In this routine: | + length of nsided_conn_array will be: 14 + + nsided_conn_array[0] = 1 (connectivity of 4-sided element) + nsided_conn_array[1] = 2 + nsided_conn_array[2] = 4 + nsided_conn_array[3] = 3 + + nsided_conn_array[4] = 3 (connectivity of 3-sided element) + nsided_conn_array[5] = 4 + nsided_conn_array[6] = 5 + + nsided_conn_array[7] = 2 (connectivity of 7-sided element) + nsided_conn_array[8] = 9 + nsided_conn_array[9] = 8 + nsided_conn_array[10] = 7 + nsided_conn_array[11] = 6 + nsided_conn_array[12] = 5 + nsided_conn_array[13] = 4 + + + + +-------------------------------------------------------------------- +USERD_get_num_of_time_steps + + Description: + ----------- + Gets the number of time steps of data available for desired timeset. + + Specification: + ------------- + int USERD_get_num_of_time_steps( int timeset_number ) + + Returns: + ------- + Number of time steps in timeset (>0 if okay, <=0 if problems). + + Arguments: + --------- + (IN) timeset number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + Notes: + ----- + * This should be >= 1 1 indicates a static model + >1 indicates a transient model + + * Num_time_steps[timeset_number] would be set here + + + +-------------------------------------------------------------------- +USERD_get_number_of_files_in_dataset + + Description: + ----------- + Get the total number of files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_number_of_files_in_dataset( void ) + + Returns: + ------- + The total number of files in the dataset. + + Arguments: + --------- + none + + Notes: + ----- + * You can be as complete as you want about this. If you don't + care about the dataset query option, return a value of 0 + If you only want certain files, you can just include them. But, + you will need to supply the info in USERD_get_dataset_query_file_info + for each file you include here. + + * Num_dataset_files would be set here + + +-------------------------------------------------------------------- +USERD_get_number_of_material_sets - + + Description: + ----------- + Get the number of material sets in the model + + Specification: + ------------- + int USERD_get_number_of_material_sets( void ) + + + Returns: + ------- + Num_material_sets = number of material sets + (Zero would indicate that you have no materials + to deal with in the model) + + or + + -1 if an error condition + + Arguments: + --------- + none + + Notes: + ----- + * You may want to keep this as a global for use in other routines. + + ############################################################### + NOTE: For EnSight 7.6, only one material set is supported + within EnSight. + Thus the only valid returns here are: + 0 (no materials) + 1 (for the one material set allowed) + or -1 (if an error) + + If the casefile has more than this, this reader will + read them, but EnSight will issue an error message and + choke on them! + ############################################################### + + ================================================================ + A very simple explanatory example, to use as a reference for the + materials routines: + + Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials. + Most of the model is material 1, but the top left corner is material 9 - + basically as shown: + + + *--------*--------*--------* + | | / | | + | Mat 9 / | | + | | / | | + | |/ | | + | e7 / e8 | e9 | + | /| | | + | / | | | + | / | | | + *----/---*--------*--------* + | / | | | + | / | | | + | / | Mat 1 | + |/ | | | + | e4 | e5 | e6 | + | | | | + | | | | + | | | | + *--------*--------*--------* + | | | | + | | | | + | | | | + | | | | + | e1 | e2 | e3 | + | | | | + | | | | + | | | | + *--------*--------*--------* + + + Thus, in this routine, set: + Num_material_sets = 1 + + In USERD_get_matf_set_info, set: + mat_set_ids[0] = 1 + mat_set_name[0] = "Material Set 1" (or whatever name desired) + + In USERD_get_number_of_materials, input would be set_index = 0, and + would need to set: + Num_materials[0] = 2 + + For simplicity, the ids and descriptions that would be returned in + USERD_get_matf_var_info could be: + mat_ids[0] = 1 + mat_ids[1] = 9 + mat_desc[0] = "mat 1" (or whatever desired) + mat_desc[2] = "mat 9" + + The per element material ids list would need to be: + + material ids: + ------------- + ids_list[0] = 1 (material id 1, for elem e1) + ids_list[1] = 1 ( " e2) + ids_list[2] = 1 ( " e3) + ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4) + ids_list[5] = 1 (material id 1, for elem e5) + ids_list[5] = 1 ( " e6) + ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7) + ids_list[5] = -9 ( " e8) + ids_list[5] = 1 (material id 1, for elem e9) + + Finally we need the mixed material ids list and the mixed materials values list, + which would need to be: + + mixed-material ids: + ------------------- + ==> 1 ids_list[0] = 2 (the -1 in the material variable points here, + 2 indicates that two materials are present) + 2 ids_list[1] = 1 (1st material is 1) + 3 ids_list[2] = 9 (2nd material is 9) + 4 ids_list[3] = -1 (negative of index into mixed-material val_list) + ==> 5 ids_list[4] = 2 (the -5 in the material variable points here, + 2 indicates that two materials are present) + 6 ids_list[5] = 1 (1st material is 1) + 7 ids_list[6] = 9 (2nd material is 9) + 8 ids_list[7] = -3 (negative of index into mixed-material val_list) + ==> 9 ids_list[8] = 2 etc. + 10 ids_list[9] = 1 + 11 ids_list[10] = 9 + 12 ids_list[11] = -5 + + mixed-material values: + ---------------------- + ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here, + and this is the value for material 1) + 2 val_list[1] = 0.125 (the value for material 9) + ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here) + 4 val_list[3] = 0.875 + ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here) + 6 val_list[5] = 0.125 + + So, USERD_size_matf_data would need to return + matf_size = 8, when called with set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX + + matf_size = 12, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX + + = 6, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE + + And, USERD_load_matf_data would need to return: + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX (indicating id list). + + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX (indicating id list). + + the float array val_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE (indicating val list). + + +------------------------------------------------------------------------- +USERD_get_number_of_materials + + Description: + ----------- + Gets the number of materials in the material set + + Specification: + ------------- + int USERD_get_number_of_materials( int set_index ) + + Returns: + ------- + Num_materials[set_index] = Number of materials in the set + 0 indicates no materials information present + -1 indicates an error + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero + * You may want to keep this as a global for use in other routines. + + + +-------------------------------------------------------------------- +USERD_get_number_of_model_parts + + Description: + ----------- + Gets the total number of unstructured and structured parts + in the model, for which you can supply information. + + Specification: + ------------- + int USERD_get_number_of_model_parts( void ) + + Returns: + ------- + Number of parts (>0 if okay, <=0 if problems). + + Arguments: + --------- + none + + Notes: + ----- + * If going to have to read down through the parts in order to + know how many, you may want to build a table of pointers to + the various parts, so you can easily get to particular parts in + later processes. If you can simply read the number of parts + at the head of the file, then you would probably not build the + table at this time. + + * This routine would set Numparts_available, which is equal to + Num_unstructured_parts + Num_structured_blocks. + + + +-------------------------------------------------------------------- +USERD_get_number_of_timesets + + Description: + ----------- + Gets the number of timesets used in the model. + + Specification: + ------------- + int USERD_get_number_of_timesets( void ) + + Returns: + ------- + Number of timesets in the model + + Arguments: + --------- + none + + Notes: + ----- + * Num_timesets would be set here + + * If you have a static model, both geometry and variables, you should + return a value of zero. + + * If you have a transient model, then you should return one or more. + + For example: + + Geometry Variables No. of timesets + --------- ------------------------------ --------------- + static static 0 + static transient, all using same timeset 1 + + transient transient, all using same timeset as geom 1 + + static transient, using 3 different timesets 3 + + transient transient, using 3 different timesets and + none of them the same as the + geometry timeset 4 + etc. + + NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide + the timeset number to use + for geometry in: + USERD_get_geom_timeset_number + + Variables can use the same timeset as the geometry, or can use + other timesets. More than one variable can use the same timeset. + + example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0 + variable 1 provided at these same five steps + variable 2 provided at 3 steps, 0.5, 1.25, 3.33 + + This routine should return a value of 2, because only + two different timesets are needed. Timeset 1 would be for the + geometry and variable 1 (they both use it). Timeset 2 would + be for variable 2, which needs its own in this case. + + + + + +-------------------------------------------------------------------- +USERD_get_number_of_variables + + Description: + ----------- + Get the number of variables for which you will be providing info. + + Specification: + ------------- + int USERD_get_number_of_variables( void ) + + Returns: + ------- + Number of variables (includes constant, scalar, vector and tensor types) + (>=0 if okay, <0 if problem) + + Arguments: + --------- + none + + Notes: + ----- + ***************************************************************** + * Variable numbers, by which references will be made, are implied + here. If you say there are 3 variables, the variable numbers + will be 1, 2, and 3. + ***************************************************************** + + * Num_variables would be set here + + + +-------------------------------------------------------------------- +USERD_get_part_coords + + Description: + ----------- + Gets the coordinates for an unstructured part. + + Specification: + ------------- + int USERD_get_part_coords(int part_number, float **coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) coord_array = 2D float array which contains, + x,y,z coordinates of each node + in the part. + + (IMPORTANT: The second dimension of this aray is 1-based!!!) + + (Array will have been allocated + 3 by (number_of_nodes + 1) for the part + long - see USERD_get_gold_part_build_info) + + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + coord_array[3][101] + + Ignore the coord_array[0][0] + coord_array[1][0] + coord_array[2][0] locations and start + the node coordinates at: + coord_array[0][1] + coord_array[1][1] + coord_array[2][1] + + coord_array[0][2] + coord_array[1][2] + coord_array[2][2] + + etc. + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_element_ids_by_type + + Description: + ----------- + Gets the ids for the elements of a particular type for an unstructured + or structured part. + + Specification: + ------------- + int USERD_get_part_element_ids_by_type(int part_number, + int element_type, + int *elemid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (OUT) elemid_array = 1D array containing id of each + element of the type. + + (Array will have been allocated + number_of_elements of the type long) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25] when called with Z_TRI03 + + conn_array[100] when called with Z_QUA04 + + conn_array[30] when called with Z_HEX08 + + Notes: + ----- + * Not called unless element label status is set to TRUE in + USERD_get_element_label_status + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_part_elements_by_type + + Description: + ----------- + Gets the connectivities for the elements of a particular type in an + unstructured part + + Specification: + ------------- + int USERD_get_part_elements_by_type(int part_number, + int element_type, + int **conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + + (OUT) conn_array = 2D array containing connectivity + of each element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_HEX08 + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_node_ids + + Description: + ----------- + Gets the node ids of an unstructured or structured part. + + Specification: + ------------- + int USERD_get_part_node_ids(int part_number, int *nodeid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) nodeid_array = 1D array containing node ids of + each node in the part. + + (IMPORTANT: This array is 1-based!!!) + + (Array will have been allocated + (number_of_nodes + 1) for the part long + see USERD_get_gold_part_build_info) + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + nodeid_array[101] + + Ignore the nodeid_array[0] location and start + the node ids at: + nodeid_array[1] + + nodeid_array[2] + + etc. + + Notes: + ----- + * Not called unless node label status is TRUE, as returned from + USERD_get_node_label_status + + * Will be based on Current_time_step + + * The ids are purely labels, used when displaying or querying node ids. + However, any node id < 0 will never be displayed + + +-------------------------------------------------------------------- +USERD_get_reader_descrip + + Description: + ----------- + Gets the description of the reader, so gui can give more info + + Specification: + ------------- + int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) descrip = the description of the reader (max length is MAXFILENP, + which is 255) + + Notes: + ----- + * OPTIONAL ROUTINE! You can have it or not. + + + +-------------------------------------------------------------------- +USERD_get_reader_version + + Description: + ----------- + Gets the version number of the user defined reader + + Specification: + ------------- + int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (and will assume is version 1.0) + + Arguments: + --------- + (OUT) version_number = the version number of the reader + (max length is Z_MAX_USERD_NAME, which + is 20) + + Notes: + ----- + * This needs to be "2.000" or greater. Otherwise EnSight will assume + this reader is API 1.0 + + * should set it to "2.010" for this version of the API + + + + +-------------------------------------------------------------------- +USERD_get_sol_times + + Description: + ----------- + Get the solution times associated with each time step for + desired timeset. + + Specification: + ------------- + int USERD_get_sol_times(int timeset_number, + float *solution_times) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) solution_times = 1D array of solution times per time step + + (Array will have been allocated + Num_time_steps[timeset_number] long) + + Notes: + ----- + * The solution times must be non-negative and increasing. + + + +-------------------------------------------------------------------- +USERD_get_timeset_description - + + Description: + ----------- + Get the description to associate with the desired timeset. + + Specification: + ------------- + int USERD_get_timeset_description(int timeset_number, + char timeset_description[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) timeset_description = timeset description string + + + Notes: + ----- + * A string of NULLs is valid for timeset_description + + + + +-------------------------------------------------------------------- +USERD_get_var_by_component + + Description: + ----------- + Gets the values of a variable component. Both unstructured and structured + parts use this routine. + + if Z_PER_NODE: + Get the component value at each node for a given variable in the part. + + or if Z_PER_ELEM: + Get the component value at each element of a specific part and type + for a given variable. + + Specification: + ------------- + int USERD_get_var_by_component(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + or: Z_UNDEF, in which case you need not load any values into var_array + + + Arguments: + --------- + (IN) which_variable = The variable number + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + (IN) var_type = Z_SCALAR + Z_VECTOR + Z_TENSOR (symmetric tensor) + Z_TENSOR9 (asymmetric tensor) + + (IN) which_type + + if Z_PER_NODE: Not used + + if Z_PER_ELEM: = The element type + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (IN) imag_data = TRUE if imag component + FALSE if real component + + (IN) component = The component: (0 if Z_SCALAR) + (0 - 2 if Z_VECTOR) + (0 - 5 if Z_TENSOR) + (0 - 8 if Z_TENSOR9) + + * 6 Symmetric Indicies, 0:5 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 22 23 | = | 1 5 | * + * | | | | * + * | 33 | | 2 | * + + + * 9 General Indicies, 0:8 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 21 22 23 | = | 6 1 5 | * + * | | | | * + * | 31 32 33 | | 7 8 2 | * + + (OUT) var_array + + ----------------------------------------------------------------------- + (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!) + ----------------------------------------------------------------------- + + if Z_PER_NODE: = 1D array containing variable component value + for each node. + + (Array will have been allocated + (number_of_nodes + 1) long) + + Info stored in this fashion: + var_array[0] = not used + var_array[1] = var component for node 1 of part + var_array[2] = var_component for node 2 of part + var_array[3] = var_component for node 3 of part + etc. + + if Z_PER_ELEM: = 1D array containing variable component + value for each element of a particular + part and type. + + (Array will have been allocated + (number_of_elements[which_part][which_type] + 1) + long. See USERD_get_gold_part_build_info) + + Info stored in this fashion: + var_array[1] = var component for elem 1 (of part and type) + var_array[2] = var component for elem 2 (of part and type) + var_array[3] = var component for elem 3 (of part and type) + etc. + + Notes: + ----- + * Not called unless Num_variables is > 0 + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * Will be based on Current_time_step + + * If the variable is not defined for this part, simply return with a + value of Z_UNDEF. EnSight will treat the variable as undefined for + this part. + + +-------------------------------------------------------------------- +USERD_get_var_value_at_specific + + Description: + ----------- + if Z_PER_NODE: + Get the value of a particular variable at a particular node in a + particular part at a particular time. + + or if Z_PER_ELEM: + Get the value of a particular variable at a particular element of + a particular type in a particular part at a particular time. + + + Specification: + ------------- + int USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part, + int which_elem_type, + int time_step, + float values[3], + int imag_data) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) which_node_or_elem + + If Z_PER_NODE: + = The node number. This is not the id, but is + the index of the global node + list (1 based), or the block's + node list (1 based). + + Thus, coord_array[1] + coord_array[2] + coord_array[3] + . | + . |which_node_or_elem index + . ---- + + + If Z_PER_ELEM: + = The element number. This is not the id, but is + the element number index + of the number_of_element array + (see USERD_get_gold_part_build_info), + or the block's element list (1 based). + + Thus, for which_part: + conn_array[which_elem_type][0] + conn_array[which_elem_type][1] + conn_array[which_elem_type][2] + . | + . which_node_or_elem index + . ---- + + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + + (IN) which_elem_type + + If Z_PER_NODE, or block part: + = Not used + + If Z_PER_ELEM: + = The element type. This is the element type index + of the number_of_element array + (see USERD_get_gold_part_build_info) + + (IN) time_step = The time step + + (IN) imag_data = TRUE if want imaginary value. + FALSE if want real value. + + (OUT) values = scalar or vector component value(s) + values[0] = scalar or vector[0] + values[1] = vector[1] + values[2] = vector[2] + + + Notes: + ----- + * This routine is used in node querys over time (or element querys over + time for Z_PER_ELEM variables). If these operations are not critical + to you, this can be a dummy routine. + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * The time step given is for the proper variable timeset. + + +---------------------------------------------------------------------- +USERD_load_matf_data + + Description: + ----------- + Get the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_load_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *ids_list, + float *val_list) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) ids_list = If mat_type is Z_MAT_INDEX: + --------------------------- + 1D material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MAT_INDEX) + + If mat_type is Z_MIX_INDEX: + --------------------------- + 1D mixed-material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_INDEX) + + (OUT) val_list = 1D mixed-materials values list + (only used if mat_type is Z_MIX_VALUE) + + (Float array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_VALUE) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, + or Num_materials[set_index] is zero, + or the appropriate size from USERD_size_matf_data is zero + + + +-------------------------------------------------------------------- +USERD_set_filenames + + Description: + ----------- + Receives the geometry and result filenames entered in the data + dialog. The user written code will have to store and use these + as needed. The user written code must manage its own files!! + + Specification: + ------------- + int USERD_set_filenames(char filename_1[], + char filename_2[], + char the_path[], + int swapbytes) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) filename_1 = the filename entered into the geometry + field of the data dialog. + + (IN) param_2 = The usage of this string depends on + 'two_fields' in USERD_get_name_of_reader. + + If two_fields is FALSE then it's empty. + + If two_fields is TRUE, this is the + manditory results file entered + into the result field of the data dialog. + + If two_fields is -1, then this contains + optional text (filenames, modifiers, etc.) + that can be parsed and used to modify + reader + + (IN) the_path = the path info from the data dialog. + Note: filename_1 and filename_2 have already + had the path prepended to them. This + is provided in case it is needed for + filenames contained in one of the files + + (IN) swapbytes = TRUE if should swap bytes when reading data. + = FALSE normally. + + Notes: + ----- + * Since you must manage everything from the input that is entered in + these data dialog fields, this is an important routine! + + * It may be that you will need to have an executive type file that contains + info and other filenames within it, like EnSight6's case file. + + +-------------------------------------------------------------------- +USERD_set_server_number + + Description: + ----------- + Receives the server number of how many total servers. + + Specification: + ------------- + int USERD_set_server_number(int cur_serv, + int tot_servs) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) cur_serv = the current server. + + (IN) tot_servs = the total number of servers. + + Notes: + ----- + * Only useful if your user defined reader is being used with EnSight's + Server-of-Server capability. And even then, it may or may not be + something that you can take advantage of. If your data is already + partitioned in some manner, such that you can access the proper + portions using this information. + + For all non-SOS uses, this will simply be 1 of 1 + + + +-------------------------------------------------------------------- +USERD_set_time_set_and_step + + Description: + ----------- + Set the current time step in the desired timeset. All functions that + need time, and that do not explicitly pass it in, will use the timeset + and step set by this routine, if needed. + + Specification: + ------------- + void USERD_set_time_set_and_step(int timeset_number, + int time_step) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) timeset_number = the timeset number (1 based). + + For example: If USERD_get_number_of_timesets + returns 2, the valid timeset_number's + would be 1 and 2. + + (IN) time_step = The current time step to set + + Notes: + ----- + * Current_time_step and Current_timeset would be set here + + +-------------------------------------------------------------------- +USERD_size_matf_data + + Description: + ----------- + Get the length of the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_size_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *matf_size) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) matf_size = the length of the material id list, or + mixed-material id list, or + mixed-material values list + for the given material set and part number + (and element type if Z_MAT_INDEX) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_stop_part_building + + Description: + ----------- + This routine called when the part building dialog is closed. It is + provided in case you desire to release memory, etc. that was only needed + during the part building process. + + Specification: + ------------- + void USERD_stop_part_building( void ) + + Returns: + ------- + nothing + + Arguments: + --------- + none + + Notes: + ----- + +-------------------------------------------------------------------- +USERD_rigidbody_existence + + Description: + ----------- + Gets the existence of rigid body values or not in the model + + Specification: + ------------- + int USERD_rigidbody_existence( void ) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + none + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_rigidbody_values + + Description: + ----------- + Gets the rigid body values for each part + + Specification: + ------------- + int USERD_rigidbody_values(int part_number, + float values[7]) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + (IN) part_number = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) values values[0] = IX (x location) + values[1] = IY (y location) + values[2] = IZ (z location) + values[3] = E0 (e0 euler value) + values[4] = E1 (e1 euler value) + values[5] = E2 (e2 euler value) + values[6] = E3 (e3 euler value) + + + Notes: + ----- + * This will be based on Current_time_step + * It will not be called unless USERD_rigidbody_existence indicates + that there are some values in the model by returning Z_OK. + + +-------------------------------------------------------------------- +USERD_set_right_side + + Description: + ----------- + Informs the reader that the time currently set is the right side of a time + span used for variable interpolation between time steps + + Specification: + ------------- + void USERD_set_right_side( void ) + + Returns: + ------- + + Arguments: + --------- + none + + Notes: + ----- + * Applies to Current_time_step + + + + + +------------------------------------------------------------------ + ENHANCED GUI ROUTINES + +-------------------------------------------------------------------- +USERD_get_extra_gui_numbers + + Description: + ----------- + The Enhanced GUI routines are added to allow + the user to customize a portion of the Data + Reader dialog to pass in options to their + user defined reader. + + Specification: + ------------- + void USERD__get_extra_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_extra_gui_numbers + USERD_get_extra_gui_defaults + USERD_set_extra_gui_data + + The existence of these routine indicates that + you wish to add customize entries to the + Data Reader dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_extra_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_extra_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_extra_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_extra_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_extra_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_extra_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_numbers + + Description: + ----------- + The Var_Extract_GUI routines are added to allow + the user to customize a extraction parameters + for variables "after" the file has been read. + These things can be modified and the variables will + be update/refreshed according to the new parameters set + + Specification: + ------------- + void USERD_get_var_extract_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults (this one) + USERD_set_var_extract_gui_data + + The existence of these routine indicates that + you wish to have the Var Extract Parameters dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_var_extract_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_var_extract_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_var_extract_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_var_extract_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_var_extract_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + + + +----------------------------------------------------------------------------------- +/* ---------------------------------------------------------- + * New in EnSight 8 is the capability to remove (fail) elements + * based on variable threshold values. Basically the variable + * name, a couple of thresholds, a couple of values and a logic + * criteria are read in from this routine. Every element that + * satisfies the failure criteria is removed and not used in + * EnSight calculations. + * + * Example Failure criteria + * Let fail_var_name = "fail_flag" + * threshold_val1 = 0 + * threshold_operator1 = Z_EQUAL_TO + * logic_criteria2 not used + * threshold_val2 not used + * threshold_operator2 not used + * For each value of "fail_flag" at each element, + * if fail flag == threshold_val1 (0.0) then element fails + * Return (Z_ERR) if this is not used. + * Return (Z_OK) if failed element feature should be used + * + * threshold_operator1 & 2 can be one of the following + * Z_ELE_FAILED_NONE, - disables checking + * Z_ELE_FAILED_GREATER, - greater than + * Z_ELE_FAILED_LESS, - less than + * Z_ELE_FAILED_EQUAL, - equal + * Z_ELE_FAILED_NOT_EQUAL, - not equal + * Z_ELE_FAILED_MANY - not used + * + * logic_criteria2 + * Z_ELE_FAILED_LOGIC_NONE, + * Z_ELE_FAILED_LOGIC_AND, + * Z_ELE_FAILED_LOGIC_OR, + * Z_ELE_FAILED_LOGIC_MANY + * + * ---------------------------------------------------------- */ +int USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + +/*-------------------------------------------------------------------- + * USERD_get_structured_reader_cinching - + *-------------------------------------------------------------------- + * + * Gets whether this reader will do structured cinching for block data + * This means that it will handle the min, max, and step values for a + * given block and return the coordinate components or variable components + * in their "cinched" state when partial extraction or striding is used. + * This is as opposed to returning the entire component (ignoring min, max + * and stride) and letting Ensight pick out the values actually used. + * + * returns: Z_OK if the reader will handle the + * min, max, and stride and return + * the cinched values only. + * + * Z_UNDEF or Z_ERR if will return entire component + * and rely on EnSight to cinch. + * + * Notes: + * Unless you can actually pull out the desired min, max, and stride + * without using a full component of memory, don't enable this feature. + *--------------------------------------------------------------------*/ +int +USERD_get_structured_reader_cinching( void ) + + + +/*-------------------------------------------------------------------- + * USERD_set_block_range_and_stride - + *-------------------------------------------------------------------- + * + * Sets the min, max, and step values in each of the i, j, and k, directions + * for the given part. + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in + * USERD_get_gold_part_build_info) + * + * (IN) mini = min i plane desired (zero based) + * maxi = max i plane desired (zero based) + * stepi = i stride + * minj = min j plane desired (zero based) + * maxj = max j plane desired (zero based) + * stepj = j stride + * mink = min k plane desired (zero based) + * maxk = max k plane desired (zero based) + * stepk = k stride + * + * + * returns: Z_OK if no problems + * Z_ERR if an error + * + * Notes: + * * It will not be called unless USERD_get_structured_reader_cinching + * indicates that this reader does structured cinching by returning + * a Z_OK. + * + * * It will actually be called before each geom component and before + * each part variable - so if you are storing things locally, you should + * make this routine be able to quickly check whether anything needs + * updated or not. + * + * * If the stride (step) does not hit right on the max, the last element + * in each direction will be shortened appropriately. + * For example, if a block had 0 to 12 in the i direction, + * and the user specified min = 1 + * max = 8 + * step = 3 + * + * 0 1 2 3 4 5 6 7 8 9 10 11 12 + * | | | | | | | | | | | | | + * + * | | | | + * + * Namely, the coarser cell boundaries in this direction would be at 1, 4, +7, and 8 + * + *--------------------------------------------------------------------*/ +int +USERD_set_block_range_and_stride(int part_number, + int mini, int maxi, int stepi, + int minj, int maxj, int stepj, + int mink, int maxk, int stepk) + + + +---- end of document ---- diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.07 b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.07 new file mode 100644 index 0000000000..3b52eed3a3 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.07 @@ -0,0 +1,4617 @@ +README_USERD_2.07 +================= +-------------------------------------- +EnSight User Defined Reader Capability ===> (API 2.07) +-------------------------------------- +A user defined reader capability is included in EnSight which can allow +otherwise unsupported structured or unstructured data to be read. The user +defined reader capability utilizes dynamic shared libraries composed of +routines defined in this document but produced by you, the user, (or some +third party). This capability is currently available for dec, ibm, hp, sgi, +sun, linux, alpha linux, and NT servers. + +You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0 +for a discussion of the differences between API 1.0 and API 2.*. + +***>> API 2.07 additional capabilities (beyond API 2.06): +Optional routine to allow userd defined readers to indicate their auto +distribute preference when used with SOS. This is used to set the auto +distribute flag default in the client. If the function does not exist, +then it defaults to 'use auto distribute'. If the function does exist and +indicates 'no auto distribute', then it's up to the UDR to decompose a +distributed data set. + USERD_prefer_auto_distribute +Optional routine to allow userd defined readers to indicate their +preference for the 'Set file...' button labels in the client's File->Open +dialog. If the function does not exist or it returns a null string for +an argument, then the default values are used. + USERD_set_filename_button_labels + +***>> API 2.06 additional capabilities (beyond API 2.05): +Routines to allow userd defined readers for structured data +to deal with min, max, and stride within the reader itself +instead of within EnSight. + USERD_get_structured_reader_cinching + USERD_set_block_range_and_stride + + +***>> API 2.05 additional capabilities (beyond API 2.04): +Routines to handle material species. + USERD_get_number_of_species + USERD_get_matsp_info + +Routines to handle variable extraction parameters after a read, and then +update the variables accordingly. Similar to the extra GUI capabilities +(which are processed before a read). (Can actually be added to pre-2.05 readers) + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + +Routines to obtain rigid body values from a reader. +(Routines were added - EnSight is now using for Nastran and STL readers + with Dynasty rigid body motion data file) + USERD_rigidbody_existence + USERD_rigidbody_values + +Routine that lets reader know when EnSight is getting the right side of a time +interval for variable interpolation between steps. Not generally needed for +most readers - however, may be needed for those that implement rigid body, and +wish to cache left and right timespan information for interpolation within the +reader itself. (Can actually be added to pre-2.05 readers) + USERD_set_right_side + + +***>> API 2.04 additional capabilities (beyond API 2.03): +Routines to handle failed elements. Basically +a.One routine to return a flag indicating the existence of + failed elements in at least one part in at least one + timestep in the model. +b.A second routine to return a matrix of flags indexed by part and + element type indicating which parts and element types have failed + elements at the current time step. +c.Finally a third routine to return an array of flags for a given + part and element type that is number of elements of that type long + indicating which elements have failed, and which have not failed. + + +***>> API 2.03 additional capabilities (beyond API 2.01): +1. Routines to handle materials +2. Routines to handle nsided and nfaced elements +3. Modified routine to handle structured ranges + + +**************************************************************************** +Note: Only the the Ensight Gold example reader, has been moved to + this 2.06 API level. And it is purely for an example - it does not + actually provide a benefit. +**************************************************************************** + + +The process for producing a user defined reader is: +--------------------------------------------------- +1. Write code for all pertinent routines in the library (Unless someone else + has done this for you). + + This is of course where the work is done by the user. The word + "pertinent" is used because depending on the nature of the data, some + of the routines in the library may be dummy routines. + + The source code for a dummy_gold library and for various other + working or sample libraries is copied from the installation CD during + installation. These will be located in directories under: + + $CEI_HOME/ensight76/user_defined_src/readers + + examples: + -------- + Basic dummy_gold routines provide skeleton for a new reader + $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold + + Sample library which reads unstructured binary EnSight Gold data + $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold + + You may find it useful to place your library source in this area as + well, but are not limited to this location. + + * ===> The descriptions of each library routine and the order that the + routines are called, which is provided in this file, along with + the example libraries, should make it possible for you to produce + code for your own data reader. + + +2. Produce the dynamic shared library. + + This is a compiling and loading process which varies according to + the type of machine you are on. In the user-defined-reader source + tree we have tried to isolate the machine dependent parts of the + build process using a set of files in the 'config' directory. In this + directory there is a configuration file for each platform on which + EnSight is supported. Before you can compile the installed readers + you should run the script called 'init' in the config directory. + + i.e. (for UNIX) + cd config + ./init sgi_6.5_n64 + cd .. + make + + If you are compiling for Windows NT, there are two options. If you + have the Cygwin GNU utilities installed, you can use GNU make as for + Unix. Otherwise, there is a script called makeall.cmd which will + build all of the readers using nmake. The Makefiles in each reader + directory will work using either make or nmake. + + i.e. (WIN32 Cygwin) (using nmake) + cd config cd config + sh init win32 cp win32 config + cd .. cd .. + mkdir lib + make makeall.cmd + + If you have platform-specific portions of code in your reader, the + build system defines a set of flags which can be used within + #ifdef ... #endif regions in your source, as shown in the table + below. + + Because the readers are now dynamically opened by EnSight, you may + have to include dependent libraries on your link-line to avoid having + unresolved symbols. If you are having problems with a reader, start + ensight as "ensight7 -readerdbg" and you will get feedback on any + problems encountered in loading a reader. If there are unresolved + symbols, you need to find the library which contains the missing + symbols and link it into your reader by adding it to the example + link commands below. + + If you choose to use a different build environment for your reader, + you should take care to use compatible compilation flags to ensure + compatibilty with the EnSight executables, most notably on the SGI + and HP-UX 11.0 platforms, which should use the following flags: + + sgi_6.2_o32: -mips2 + sgi_6.2_n64: -mips4 -64 + sgi_6.5_n32: -mips3 + sgi_6.5_n64: -mips4 -64 + hp_11.0_32: +DA2.0 + hp_11.0_64: +DA2.0W + + ______________________________________________________________________ + | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED | + | TYPE |------------------------------------------------------------| + | | LD COMMAND USED IN MAKEFILE | + ====================================================================== + ______________________________________________________________________ + | sgi | -DSGI | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | hp | -DHP | libuserd-X.sl | + | |------------------------------------------------------------| + | | ld -b -o libuserd-X.sl libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | sun | -DSUN | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | dec | -DDEC | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | linux | -DLINUX | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | alpha | -DALINUX | libuserd-X.so | + | linux |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | ibm | -DIBM | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc | + ---------------------------------------------------------------------- + + Once you have created your library, you should place it in a directory + of your choice or in the standard reader location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + For example, if you created a reader for "mydata", you should create + the reader libuserd-mydata.so and place the file in your own reader + directory (see section 3 below) or in the standard location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so + + +3. By default EnSight will load all readers found in the directory: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + Files with names "libuserd-X.so" (where X is a name unique to the reader) + are assumed to be user-defined readers. + + There are two methods which can be used to supplement the default + behavior. + + (1) A feature which is useful for site-level or user-level configuration + is the optional environment variable $ENSIGHT7_READER. This + variable directs EnSight to load all readers in the specified reader + directory (you should probably specify a full path) before loading + the built-in readers. If the same reader exists in both directories + (as determined by the name returned by USERD_get_name_of_reader(), + NOT by the filename), the locally configured reader will take + precedence. + + (2) A useful feature for end-users is the use of the libuserd-devel + reader. EnSight will search for a reader named libuserd-devel.so + (.sl for HP or .dll for NT). This reader can exist anywhere in the + library path (see below) of the user. This is useful for an + individual actively developing a reader because the existence of a + libuserd-devel library will take precedence over any other library + which returns the same name from USERD_get_name_of_reader(). + + As an example, a site may install commonly used readers in a common + location, and users can set the ENSIGHT7_READER variable to access them: + + setenv ENSIGHT7_READER /usr/local/lib/e7readers + + A user working on a new reader may compile the reader and place it in + a directory specified by the library path: + + cp libuserd-myreader.so ~/lib/libuserd-devel.so + setenv ~/lib:$ + + The user is responsible for correctly configuring the library path + variable in order to make use of the libuserd-devel feature. The + library environment variables used are: + + Machine type Environment variable to set + ------------ --------------------------- + sgi LD_LIBRARY_PATH + dec LD_LIBRARY_PATH + sun LD_LIBRARY_PATH + linux LD_LIBRARY_PATH + alpha linux LD_LIBRARY_PATH + hp SHLIB_PATH + ibm LIBPATH + +As always, EnSight support is available if you need it. + +------------------------------- +Quick Index of Library Routines +------------------------------- + +Generally Needed for UNSTRUCTURED data +-------------------------------------- +USERD_get_part_coords part's node coordinates +USERD_get_part_node_ids part's node ids +USERD_get_part_elements_by_type part's element connectivites +USERD_get_part_element_ids_by_type part's element ids + + +Generally Needed for BLOCK data +-------------------------------------- +USERD_get_block_coords_by_component block coordinates +USERD_get_block_iblanking block iblanking values +USERD_get_ghosts_in_block_flag block ghost cell existence? +USERD_get_block_ghost_flags block ghost cell flags + + These routines, which formerly were only for unstructured data, will now + also be called for structured data if you specify that ids will be given + in the USERD_get_node_label_status and USERD_get_element_label_status rotuines + ------------------------------------------------------------------------------ + USERD_get_part_node_ids part's node ids + USERD_get_part_element_ids_by_type part's element ids + + +Generally needed for either or both kinds of data +------------------------------------------------- +USERD_get_name_of_reader name of reader for GUI +USERD_get_reader_release release string of reader +USERD_get_reader_version provide reader version number +USERD_get_reader_descrip provide GUI more description (optional) + +USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields +USERD_get_extra_gui_defaults Gets the default values for the GUI members +USERD_set_extra_gui_data Returns the answers provided by the user + +USERD_set_filenames filenames entered in GUI +USERD_set_server_number server which of how many + +USERD_get_number_of_timesets number of timesets +USERD_get_timeset_description description of timeset +USERD_get_geom_timeset_number timeset # to use for geom + +USERD_get_num_of_time_steps number of time steps +USERD_get_sol_times solution time values +USERD_set_time_set_and_step current timeset and time step + +USERD_get_changing_geometry_status changing geometry? +USERD_get_node_label_status node labels? +USERD_get_element_label_status element labels? +USERD_get_model_extents provide model bounding extents +USERD_get_number_of_files_in_dataset number of files in model +USERD_get_dataset_query_file_info info about each model file +USERD_get_descrip_lines file associated description lines +USERD_get_number_of_model_parts number of model parts +USERD_get_gold_part_build_info Gets the info needed for part building process +USERD_get_part_build_info part/block type/descrip etc. +USERD_get_maxsize_info part/block allocation maximums +USERD_get_ghosts_in_model_flag model contains ghost cells? +USERD_get_nsided_conn Gets the element connectivities for nsided + elements. (utilizes the number of nodes + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced + elements (utilizes the number of faces + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_conn Gets the element connectivities for nfaced + elements (utilizes the number of nodes + per face obtained in + USERD_get_nfaced_nodes_per_face) + + +USERD_get_border_availability part border provided? +USERD_get_border_elements_by_type part border conn and parent info + +USERD_get_number_of_variables number of variables +USERD_get_gold_variable_info variable type/descrip etc. +USERD_get_var_by_component part or block variable values +USERD_get_constant_val constant variable's value +USERD_get_var_value_at_specific node's or element's variable value over time +USERD_stop_part_building cleanup after part build routine + +USERD_get_number_of_material_sets Gets the number of material sets +USERD_get_matf_set_info Gets the material set indices and names +USERD_get_number_of_materials Gets the number of materials +USERD_get_matf_var_info Gets the material indices and descriptions +USERD_size_matf_data Gets the length of either the + material ids list, + mixed-material ids list, or + mixed-material values list +USERD_load_matf_data Gets the material ids list, + mixed-material ids list, or + mixed-material values list + +USERD_bkup archive routine + +USERD_exit_routine cleanup upon exit routine + +USERD_get_uns_failed_params Gets thresholds/criteria for failure + +USERD_rigidbody_existence Returns whether rigid body transformation + data exists for the model. +USERD_rigidbody_values Returns the euler and location values for a + given part + +USERD_set_right_side Simply informs the reader when the time set + is for the right side of a time span during + variable interpolation between time steps. + +USERD_get_structured_reader_cinching Tells if the reader will do structured + cinching +USERD_set_block_range_and_stride Sets the min, max, and stride of a block + if doing structured cinching + + +------------------------- +Order Routines are called +------------------------- + +The various main operations are given basically in the order they will +be performed. Within each operation, the order the routines will be +called is given. + +1. Setting name in the gui, and specifying one or two input fields + + USERD_get_name_of_reader + USERD_get_reader_descrip (optional) + USERD_get_extra_gui_numbers (optional) + USERD_get_extra_gui_defaults (optional) + +2. Getting the reader version (also distinguishes between API's) + + USERD_get_reader_version + +3. Setting filenames and getting timeset and time info + + (optional if reader has + USERD_get_extra_gui_defaults routine) + USERD_get_structured_reader_cinching + USERD_set_server_number + USERD_set_extra_gui_data (optional) + USERD_set_filenames + USERD_get_number_of_timesets + USERD_get_geom_timeset_number + + for each timeset: + USERD_get_timeset_description + USERD_get_num_of_time_steps + USERD_get_sol_times + + USERD_set_time_set_and_step + +4. Gathering info for part builder + + USERD_set_time_set_and_step + USERD_get_changing_geometry_status + USERD_get_node_label_status + USERD_get_element_label_status + USERD_get_number_of_files_in_dataset + USERD_get_dataset_query_file_info + USERD_get_descrip_lines (for geometry) + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_maxsize_info + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR (for model extents) + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + +5. Gathering Variable info + + USERD_get_number_of_variables + USERD_get_gold_variable_info + +6. Part building (per part created) + + both unstructured and structured: + -------------------------------- + USERD_set_time_set_and_step + + if unstructured part: + -------------------- + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + + If any nsided elements: + + USERD_get_nsided_conn + + If any nfaced elements: + + USERD_get_nfaced_nodes_per_face + USERD_get_nfaced_conn + + USERD_get_part_coords + USERD_get_part_node_ids + + else if structured part: + ----------------------- + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + both again: + ---------- + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + USERD_stop_part_building (only once when part builder + dialog is closed) + +7. Loading Variables + + constants: + --------- + USERD_set_time_set_and_step + USERD_get_constant_val + + scalars/vectors/tensors: + ------------------------ + USERD_get_descrip_lines + USERD_set_time_set_and_step + (if doing structured reader cinching + USERD_get_var_by_component + +8. Changing geometry + + changing coords only (per part): + -------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_part_coords + (if doing structured reader cinching + USERD_get_block_coords_by_component + + changing connectivity (per part): + --------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + USERD_get_part_coords + USERD_get_part_node_ids + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + +9. Node or Element queries over time + + USERD_get_var_value_at_specific + +10. To see if materials in the model + + USERD_get_number_of_material_sets + USERD_get_matf_set_info + + If any material sets in the model (calls these once per material set): + USERD_get_number_of_materials + USERD_get_matf_var_info + + For each elment type of each part containing material ids, calls: + USERD_size_matf_data + USERD_load_matf_data + + If there are any elements with mixed materials, when a domain or + interface is created, calls these again per part: + + USERD_size_matf_data + USERD_load_matf_data + +11. To modify the variable extraction parameters and have the variables + update accordingly. + + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + + + +----------------------- +Detailed Specifications +----------------------- + +Include files: +-------------- +The following header file is required in any file containing these library +routines. + + #include "global_extern.h" + +And it references: + + #include "global_extern_proto.h" + + + +******************************************************************************* +****************************** Special Note *********************************** +******************************************************************************* + +Make sure you use the proper define in the global_extern.h header file, namely: +#define USERD_API_204 + +Also, Make sure the api version in the USERD_get_reader_version routine is set +to "2.04" or larger. + +Make sure your reader has access to the global_extern_proto.h This is a new +file which is accessed from the new global_extern.h + +******************************************************************************* +******************************************************************************* + + +Basis of arrays: +--------------- +Unless explicitly stated otherwise, all arrays are zero based - in true C +fashion. + + +Global variables: +---------------- +You will generally need to have a few global variables which are shared by +the various library routines. The detailed specifications below have assumed +the following are available. (Their names describe their purpose, and they +will be used in helping describe the details of the routines below). + +static int Numparts_available = 0; +static int Num_unstructured_parts = 0; +static int Num_structured_blocks = 0; + +/* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */ + +static int Num_timesets = 1; +static int Current_timeset = 1; +static int Geom_timeset_number = 1; + +static int Num_time_steps[Z_MAXSETS] = 1; +static int Current_time_step = 0; +static int Num_variables = 0; +static int Num_dataset_files = 0; + +static int Server_Number = 1; Which server of +static int Tot_Servers = 1; the total number of servers + + + +_________________________________________ +----------------------------------------- +Library Routines (in alphabetical order): +_________________________________________ +----------------------------------------- + +-------------------------------------------------------------------- +USERD_bkup + + Description: + ----------- + This routine is called during the EnSight archive process. You can + use it to save or restore info relating to your user defined reader. + + Specification: + ------------- + int USERD_bkup(FILE *archive_file, + int backup_type) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) archive_file = The archive file pointer + + (IN) backup_type = Z_SAVE_ARCHIVE for saving archive + Z_REST_ARCHIVE for restoring archive + + Notes: + ----- + * Since EnSight's archive file is saved in binary form, you should + also do any writing to it or reading from it in binary. + + * You should archive any variables, which will be needed for + future operations, that will not be read or computed again + before they will be needed. These are typically global + variables. + + * Make sure that the number of bytes that you write on a save and + the number of bytes that you read on a restore are identical!! + + * If any of the variables you save are allocated arrays, you must + do the allocations before restoring into them. + +-------------------------------------------------------------------- +USERD_exit_routine + + Description: + ----------- + This routine is called as EnSight is exiting. It can be used to clean + up anything needed - such as removing temporary files, etc. - or can simply + be a dummy. + + Specification: + ------------- + void USERD_exit_routine( void ) + + Arguments: + --------- + none + +-------------------------------------------------------------------- +USERD_get_block_coords_by_component + + Description: + ----------- + Get the coordinates of a given structured block, a component at a time. + + Specification: + ------------- + int USERD_get_block_coords_by_component(int block_number, + int which_component, + float *coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) which_component = Z_COMPX if x component wanted + = Z_COMPY if y component wanted + = Z_COMPZ if z component wanted + + (OUT) coord_array = 1D array containing x,y, or z + coordinate component of each node + + (Array will have been allocated + i*j*k for the block long) + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_block_iblanking + + Description: + ----------- + Get the iblanking value at each node of a block (if the block is + iblanked). + + Specification: + ------------- + int USERD_get_block_iblanking(int block_number, + int *iblank_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) iblank_array = 1D array containing iblank value + for each node. + + (Array will have been allocated + i*j*k for the block long) + + possible values are: Z_EXT = exterior + Z_INT = interior + Z_BND = boundary + Z_INTBND = internal boundary + Z_SYM = symmetry plane + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 and you have + some iblanked blocks + + * Will be based on Current_time_step + + + +---------------------------------------------------------------------- +USERD_get_block_ghost_flags + + Description: + ----------- + Get the ghost_flags value at each element of a block containing ghost cells. + + Specification: + ------------- + int USERD_get_block_ghost_flags(int block_number, + int *ghost_flags) + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) ghost_flags = 1D array containing ghost flag value + for each block cell. + + (Array will have been allocated + (i-1)*(j-1)*(k-1) for the block long) + + possible values are: 0 = non-ghost cell (normal cell) + >0 = ghost cell + + Notes: + ----- + * This routine is new in the 2.01 API + + * This will be based on Current_time_step + + * Only called for structured "block" parts that have some ghost cells + as indicated by the USERD_get_ghost_in_block_flag. The model must + of course also have been indicated to have some ghost cells in the + USERD_get_ghost_in_model_flag routine. + + * It is sufficient to set the value to be 1 to flag as a ghost cell, + but the value can be any non-zero value, so you could use it to + indicate which block or which server (for Server-of-server use) the + cell is actually in. + + + +-------------------------------------------------------------------- +USERD_get_border_availability + + Description: + ----------- + Finds out if border elements are provided by the reader for the + desired part, or will need to be computed internally by EnSight. + + Specification: + ------------- + int USERD_get_border_availability(int part_number, + int number_of_elements[Z_MAXTYPE]) + + Returns: + ------- + Z_OK if border elements will be provided by the reader. + (number_of_elements array will be loaded and + USERD_get_border_elements_by_type will be called) + + Z_ERR if border elements are not available - thus EnSight must compute. + (USERD_get_border_elements_by_type will not be called) + + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) number_of_elements = 2D array containing number of + each type of border element in + the part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + + Notes: + ----- + * Only called if border representation is used. + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_border_elements_by_type + + Description: + ----------- + Provides border element connectivity and parent information. + + Specification: + ------------- + int USERD_get_border_elements_by_type(int part_number, + int element_type, + int **conn_array, + short *parent_element_type, + int *parent_element_num) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + + (OUT) conn_array = 2D array containing connectivity + of each border element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_QUA08] = 30 + as obtained in: + USERD_get_border_availability + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_QUA08 + + (OUT) parent_element_type = 1D array containing element type of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + (OUT) parent_element_num = 1D array containing element number of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + + Notes: + ----- + * Not called unless USERD_get_border_availability returned Z_OK + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_changing_geometry_status + + Description: + ----------- + Gets the changing geometry status for the model + + Specification: + ------------- + int USERD_get_changing_geometry_status( void ) + + Returns: + ------- + Z_STATIC if geometry does not change + Z_CHANGE_COORDS if changing coordinates only + Z_CHANGE_CONN if changing connectivity + + Arguments: + --------- + none + + Notes: + ----- + * EnSight does not support changing number of parts. But the + coords and/or the connectivity of the parts can change. Note that + a part is allowed to be empty (number of nodes and elements equal + to zero). + + +-------------------------------------------------------------------- +USERD_get_constant_val + + Description: + ----------- + Get the value of a constant at a time step + + Specification: + ------------- + float USERD_get_constant_value(int which_var, + int imag_data) + + Returns: + ------- + Value of the requested constant variable + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) imag_data = TRUE if want imaginary data value. + FALSE if want real data value. + + Notes: + ----- + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_dataset_query_file_info + + Description: + ----------- + Get the information about files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_dataset_query_file_info(Z_QFILES *qfiles) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) qfiles = Structure containing information about each file + of the dataset. The Z_QFILES structure is defined + in the global_extern.h file + + (The structure will have been allocated + Num_dataset_files long, with 10 description + lines per file). + + qfiles[].name = The name of the file + (Z_MAXFILENP is the dimensioned length + of the name) + + qfiles[].sizeb = The number of bytes in the file + (Typically obtained with a call to the + "stat" system routine) (Is a long) + + qfiles[].timemod = The time the file was last modified + (Z_MAXTIMLEN is the dimensioned length + of this string) + (Typically obtained with a call to the + "stat" system routine) + + qfiles[].num_d_lines = The number of description lines you + are providing from the file. Max = 10 + + qfiles[].f_desc[] = The description line(s) per file, + qfiles[].num_d_lines of them + (Z_MAXFILENP is the allocated length of + each line) + + Notes: + ----- + * If Num_dataset_files is 0, this routine will not be called. + (See USERD_get_number_of_files_in_dataset) + + +-------------------------------------------------------------------- +USERD_get_descrip_lines + + Description: + ----------- + Get two description lines associated with geometry per time step, + or one description line associated with a variable per time step. + + Specification: + ------------- + int USERD_get_descrip_lines(int which_type, + int which_var, + int imag_data, + char line1[Z_BUFL], + char line2[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_type = Z_GEOM for geometry (2 lines) + = Z_VARI for variable (1 line) + + (IN) which_var = If it is a variable, which one. + Ignored if geometry type. + + (IN) imag_data = TRUE if want imaginary data file. + FALSE if want real data file. + + (OUT) line1 = The 1st geometry description line, + or the variable description line. + + (OUT) line2 = The 2nd geometry description line + Not used if variable type. + + Notes: + ----- + * Will be based on Current_time_step + + * These are the lines EnSight can echo to the screen in + annotation mode. + + + +-------------------------------------------------------------------- +USERD_get_element_label_status + + Description: + ----------- + Answers the question as to whether element labels will be provided. + + Specification: + ------------- + int USERD_get_element_label_status( void ) + + Returns: + ------- + TRUE if element labels will be provided + FALSE if element labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * element lables are needed in order to do any element querying, or + element labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. + + API 1.0: + USERD_get_element_ids_for_part is used to obtain the ids, + on a part by part basis, if TRUE status is returned here. + + API 2.0: + USERD_get_part_element_ids_by_type is used to obtain the ids, + on a per part, per type basis, if TRUE status is returned here. + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them youself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model (especially + if you are dealing with a decomposed dataset). + + USERD_get_part_element_ids_by_type is used to obtain the ids, + on an element type by part basis, if TRUE status is returned here. + + * Will call USERD_get_part_element_ids_by_type for each type of + of each part if this routine returns TRUE. +-------------------------------------------------------------------- +USERD_get_geom_timeset_number - + + Description: + ----------- + Gets the timeset number to be used for geometry + + Specification: + ------------- + int USERD_get_geom_timeset_number( void ) + + Returns: + ------- + Geom_timeset_number = The timeset number that will be used for geometry. + For example, if USERD_get_number_of timesets + returns 2, the valid timeset numbers would be + 1 or 2. + + Arguments: + --------- + none + + Notes: + ----- + * If your model is static, which you indicated by returning a zero + in USERD_get_number_of_timesets, you can return a zero here as well. + + + +-------------------------------------------------------------------- +USERD_get_gold_part_build_info + + Description: + ----------- + Gets the info needed for the part building process. + + Specification: + ------------- + int USERD_get_gold_part_build_info(int *part_id, + int *part_types, + char *part_description[Z_BUFL], + int *number_of_nodes, + int *number_of_elements[Z_MAXTYPE], + int *ijk_dimensions[9], + int *iblanking_options[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) part_id = Array containing the external part + ids for each of the model parts. + + IMPORTANT: + Parts numbers must be >= 1, because + of the way they are used in the GUI + + ******************************************* + The ids provided here are the numbers by + which the parts will be referred to in the + GUI (if possible). They are basically + labels as far as you are concerned. + + Note: The part numbers you pass to routines + which receive a part_number or block_number + or which_part as an argument are the 1-based + table index of the parts! + + example: If Numparts_available = 3 + + Table index part_id + ----------- ------- + 1 13 + 2 57 + 3 125 + + ^ ^ + | | + | These are placed in: + | part_id[0] = 13 + | part_id[1] = 57 + | part_id[2] = 125 + | for GUI labeling purposes. + | + These implied table indices are the part_number, + block_number, or which_part numbers that you would + pass to routines like: + + USERD_get_part_coords(int part_number,... + USERD_get_part_node_ids(int part_number,... + USERD_get_part_elements_by_type(int part_number,... + USERD_get_part_element_ids_by_type(int part_number,... + USERD_get_block_coords_by_component(int block_number,... + USERD_get_block_iblanking(int block_number,... + USERD_get_block_ghost_flags(int block_number,... + USERD_get_ghosts_in_block_flag(int block_number) + USERD_get_border_availability(int part_number,... + USERD_get_border_elements_by_type(int part_number,... + USERD_get_var_by_component(int which_variable, + int which_part,... + USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part,... + ******************************************** + + (Array will have been allocated + Numparts_available long) + + (OUT) part_types = Array containing one of the + following for each model part: + + Z_UNSTRUCTURED or + Z_STRUCTURED or + Z_IBLANKED + + (Array will have been allocated + Numparts_available long) + + (OUT) part_description = Array containing a description + for each of the model parts + + (Array will have been allocated + Numparts_available by Z_BUFL + long) + + (OUT) number_of_nodes = Number of unstructured nodes in the part + + (Array will have been allocated + Numparts_available long) + + (OUT) number_of_elements = 2D array containing number of + each type of element for each + unstructured model part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) ijk_dimensions = 2D array containing ijk dimension info + for structured blocks + + For Z_UNSTRUCTURED - is ignored + + For Z_STRUCTURED or Z_IBLANKED + + Prior to version 2.03: + ---------------------- + (Array will have been allocated + Numparts_available by 3 long) + + ijk_dimensions[][0] = I dimension + ijk_dimensions[][1] = J dimension + ijk_dimensions[][2] = K dimension + + + Starting at version 2.03: + ------------------------ + (Array will have been allocated + Numparts_available by 9 long) + + There are two ways to do this: + ------------------------------ + 1. The simple one, without ranges. + + This is good for all structured models + that will NOT be used in EnSight's + Server of Servers + + Simply provide the ijk dimensions in the + first three slots and place a -1 in + the 4th slot. (The remaining slots will + be ignored). + + Thus, + ijk_dimensions[][0] = I dimension of block + ijk_dimensions[][1] = J dimension of block + ijk_dimensions[][2] = K dimension of block + ijk_dimensions[][3] = -1 + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][4] = -1 + | | | + | | | + 2 *-------*-------* + | | | + | | | + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + + 2. Using ranges. + + This one can be used anytime, but MUST + be used if EnSight's Server of Servers + is to be used! + + The first 3 slots contain the ijk dimension + of the complete block (of which this may be + a portion). The last 6 slots contain the + ijk min and max ranges within the complete. + + Thus, + ijk_dimensions[][0] = I dim of complete block + ijk_dimensions[][1] = J dim of complete block + ijk_dimensions[][2] = K dim of complete block + + ijk_dimensions[][3] = Imin of portion (1-based) + ijk_dimensions[][4] = Imax of portion (1-based) + ijk_dimensions[][5] = Jmin of portion (1-based) + ijk_dimensions[][6] = Jmax of portion (1-based) + ijk_dimensions[][7] = Kmin of portion (1-based) + ijk_dimensions[][8] = Kmax of portion (1-based) + + + example1: (Model has one part, a simple 2D block, + and want whole thing) + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][3] = 1 + | | | ijk_dimension[0][4] = 3 + | | | ijk_dimension[0][5] = 1 + 2 *-------*-------* ijk_dimension[0][6] = 4 + | | | ijk_dimension[0][7] = 1 + | | | ijk_dimension[0][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + example2: (Want to have the block represented + in two portions - 2 parts) + + (J planes) top portion + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + . . . ijk_dimension[0][3] = 1 + . . . ijk_dimension[0][4] = 3 + . . . ijk_dimension[0][5] = 3 + 2 ................. ijk_dimension[0][6] = 4 + . . . ijk_dimension[0][7] = 1 + . . . ijk_dimension[0][8] = 1 + . . . + 1 ................. + 1 2 3 (I planes) + + + (J planes) bottom portion + 4 ................. + . . . ijk_dimension[1][0] = 3 + . . . ijk_dimension[2][1] = 4 + . . . ijk_dimension[3][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[1][3] = 1 + | | | ijk_dimension[1][4] = 3 + | | | ijk_dimension[1][5] = 1 + 2 *-------*-------* ijk_dimension[1][6] = 3 + | | | ijk_dimension[1][7] = 1 + | | | ijk_dimension[1][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + And note that if you were partioning this block for + EnSight's Server of Servers, you would only have one part, + instead of two. Each SOS server would return its appropriate + ranges in the last 6 slots. The first 3 slots would remain constant. + + + (OUT) iblanking_options = 2D array containing iblanking + options possible for each + structured model part. + ---------- + (Ignored unless Z_IBLANKED type) + + (Array will have been allocated + Numparts_available by 6 long) + + iblanking_options[][Z_EXT] = TRUE if external (outside) + [][Z_INT] = TRUE if internal (inside) + [][Z_BND] = TRUE if boundary + [][Z_INTBND] = TRUE if internal boundary + [][Z_SYM] = TRUE if symmetry surface + + + Notes: + ----- + * If you haven't built a table of pointers to the different parts, + you might want to do so here as you gather the needed info. + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_gold_variable_info + + Description: + ----------- + Get the variable descriptions, types and filenames + + Specification: + ------------- + int USERD_get_gold_variable_info(char **var_description, + char **var_filename, + int *var_type, + int *var_classify, + int *var_complex, + char **var_ifilename, + float *var_freq, + int *var_contran, + int *var_timeset) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) var_description = Variable descriptions + + (Array will have been allocated + Num_variables by Z_BUFL long) + + variable description restrictions: + ---------------------------------- + 1. Only first 19 characters used in EnSight. + 2. Leading and trailing whitespace will be removed by EnSight. + 3. Illegal characters will be replaced by underscores. + 4. Thay may not start with a numeric digit. + 4. No two variables may have the same description. + + + (OUT) var_filename = Variable real filenames + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_type = Variable type + + (Array will have been allocated + Num_variables long) + + types are: Z_CONSTANT + Z_SCALAR + Z_VECTOR + Z_TENSOR + Z_TENSOR9 + + (OUT) var_classify = Variable classification + + (Array will have been allocated + Num_variables long) + + types are: Z_PER_NODE + Z_PER_ELEM + + (OUT) var_complex = TRUE if complex, FALSE otherwise + + (Array will have been allocated + Num_variables long) + + (OUT) var_ifilename = Variable imaginary filenames (if complex) + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_freq = complex frequency (if complex) + + (Array will have been allocated + Num_variables long) + + (OUT) var_contran = TRUE if constant changes per time step + FALSE if constant truly same at all time steps + + (Array will have been allocated + Num_variables long) + + (OUT) var_timeset = Timeset the variable will use (1 based). + (For static models, set it to 1) + + (Array will have been allocated + Num_variables long) + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 or 2 + + + Notes: + ----- + * The implied variable numbers apply, but be aware that the + arrays are zero based. + So for variable 1, will need to provide var_description[0] + var_filename[0] + var_type[0] + var_classify[0] + var_complex[0] + var_ifilename[0] + var_freq[0] + var_contran[0] + var_timeset[0] + + + for variable 2, will need to provide var_description[1] + var_filename[1] + var_type[1] + var_classify[1] + var_complex[1] + var_ifilename[1] + var_freq[1] + var_contran[1] + var_timeset[1] + etc. + + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_block_flag + + Description: + ----------- + Gets whether ghost cells present in block or not + + Specification: + ------------- + int USERD_get_ghosts_in_block_flag(int block_number) + + Returns: + ------- + TRUE if any ghost cells in this structured part + FALSE if no ghost cells in this structured part + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Notes: + ----- + * This routine is new in the 2.01 API + * This will be based on Current_time_step + + * Intended for structured parts only, value will be ignored for + unstructured parts + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_model_flag + + Description: + ----------- + Answers the question as to whether any ghost cells in the model. + + Specification: + ------------- + int USERD_get_ghosts_in_model_flag( void ) + + Returns: + ------- + TRUE if any ghost cells in the model + FALSE if no ghost cells in the model + + Arguments: + --------- + + Notes: + ----- + * This routine is new in the 2.01 API + +------------------------------------------------------------------------- +USERD_get_matf_set_info + + Description: + ----------- + Get the material set ids and names + + Specification: + ------------- + int USERD_get_matf_set_info(int *mat_set_ids, + char **mat_set_name) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) mat_set_ids = 1D material set ids array + + (Array will have been allocated + Num_material_sets long) + + (OUT) mat_set_name = 2D material set name array + + (Array will have been allocated + Num_material_sets by Z_BUFL long) + + Notes: + ----- + * Will not be called if Num_material_sets is zero + * See USERD_get_number_of_material_sets header for explanatory example + + +-------------------------------------------------------------------- +USERD_get_matf_var_info + + Description: + ----------- + Gets the material ids and descriptions for the material set + + Specification: + ------------- + int USERD_get_matf_var_info(int set_index, + int *mat_ids, + char **mat_desc) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (OUT) mat_ids[set_index] = 1D integer array containing the material + ids to associated with each material + + (Array will have been allocated + Num_materials[set_index] long) + + (OUT) mat_desc[set_index] = 2D char array containing the material + descriptions to associated with each material + + (Array will have been allocated + Num_materials[set_index] by Z_BUFL long) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_get_maxsize_info + + Description: + ----------- + Gets maximum part sizes for efficient memory allocation. + + Transient models (especially those that increase in size) can cause + reallocations, at time step changes, to keep chewing up more and + more memory. The way to avoid this is to know what the maximum + size of such memory will be, and allocate for this maximum initially. + + Accordingly, if you choose to provide this information (it is optional), + EnSight will take advantage of it. + + + Specification: + ------------- + int USERD_get_maxsize_info(int *max_number_of_nodes, + int *max_number_of_elements[Z_MAXTYPE], + int *max_ijk_dimensions[3]) + + Returns: + ------- + Z_OK if supplying maximum data + Z_ERR if not supplying maximum data, or some error occurred + while trying to obtain it. + + Arguments: + --------- + (OUT) max_number_of_nodes = Maximum number of unstructured nodes + in the part (over all time). + + (Array will have been allocated + Numparts_available long) + + (OUT) max_number_of_elements = 2D array containing maximum number of + each type of element for each + unstructured model part (over all time). + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions + for each structured model part (over all time). + ---------- + (Ignored if Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by 3 long) + + max_ijk_dimensions[][0] = maximum I dimension + max_ijk_dimensions[][1] = maximum J dimension + max_ijk_dimensions[][2] = maximum K dimension + + Notes: + ----- + * You need to have first called USERD_get_number_of_model_parts and + USERD_get_gold_part_build_info, so Numparts_available is known and + so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED, + or Z_IBLANKED) of each part. + + * This will NOT be based on Current_time_step - it is to be the maximum + values over all time!! + + * This information is optional. If you return Z_ERR, Ensight will still + process things fine, reallocating as needed, etc. However, for + large transient models you will likely use considerably more memory + and take more processing time for the memory reallocations. So, if it + is possible to provide this information "up front", it is recommended + to do so. + + +-------------------------------------------------------------------- +USERD_get_model_extents + + Description: + ----------- + Gets the model bounding box extents. If this routine supplys them + EnSight will not have to spend time doing so. If this routine + returns Z_ERR, EnSight will have to take the time to touch all the + nodes and gather the extent info. + + Specification: + ------------- + int USERD_get_model_extents(float extents[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (whereupon EnSight will determine by reading + all coords of all parts) + + Arguments: + --------- + (OUT) extents[0] = min x + [1] = max x + [2] = min y + [3] = max y + [4] = min z + [5] = max z + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_name_of_reader + + Description: + ----------- + Gets the name of your user defined reader. The user interface will + ask for this and include it in the available reader list. + + Specification: + ------------- + int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], + int *two_fields) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) reader_name = the name of the your reader or data format. + (max length is Z_MAX_USERD_NAME, which is 20) + + (OUT) two_fields = FALSE if only one data field is + required. + TRUE if two data fields required + + -1 if one field (Geom) required + and one field (Param) is optional + Param field can contain any text + for example a file name, modifiers, + etc. that can be used to modify the + reader's behavior. + + + Notes: + ----- + * Always called. Please be sure to provide a name for your custom + reader format. + +-------------------------------------------------------------------- +USERD_get_nfaced_conn + + Description: + ----------- + Gets the array containing the connectivity of nsided faces of nfaced elements + + Specification: + -------------int + int USERD_get_nfaced_conn(int part_number, + int *nfaced_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced + elements + + (int array will have been allocated long enough to + hold all the nsided face connectivities. Which is + the sum of all the nodes per face values in the + nfaced_npf_array of USERD_get_nfaced_nodes_per_face) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In USERD_get_faced_nodes_per_face: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In this function: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + +-------------------------------------------------------------------- +USERD_get_nfaced_nodes_per_face - + + Description: + ----------- + Gets the array containing the number of nodes per face for each face + of the nfaced elements. + + Specification: + ------------- + int USERD_get_nfaced_nodes_per_face(int part_number, + int *nfaced_npf_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of + nfaced elements + + (int array will have been allocated long enough + to hold all the nodes_per_face values. Which is + the sum of all the number of faces per element + values in the conn_array of + USERD_get_part_elements_by_type) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the + the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In this routine: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In USERD_get_nfaced_conn: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + + +-------------------------------------------------------------------- +USERD_get_node_label_status + + Description: + ----------- + Answers the question as to whether node labels will be provided. + + Specification: + ------------- + int USERD_get_node_label_status( void ) + + Returns: + ------- + TRUE if node labels will be provided + FALSE if node labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * Node ids are needed in order to do any node querying, or node + labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. They must also be + positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + (Unlike API 1.0, where the connectivity of elements had to be + according to the node ids - API 2.0's element connectivities + are not affected either way by the status here.) + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them yourself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model. They must + also be positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + * Will call USERD_get_part_node_ids for each part if this routine + returns TRUE. + +-------------------------------------------------------------------- +USERD_get_nsided_conn - + + Description: + ----------- + Gets the array containing the connectivity of nsided elements + + Specification: + ------------- + int USERD_get_nsided_conn(int part_number, + int *nsided_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nsided_conn_array = 1D array of nsided connectivies + + (int array will have been allocated long enough + to hold all the nsided connectivities. Which is + the sum of all the nodes_per_element values in + the conn_array of USERD_get_part_elements_by_type) + + + Notes: + ----- + * Will not be called unless there are some nsided elements in the the part. + + * Providing nsided information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nsided + elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of nodes per nsided element. (as if connectivity + length of an nsided element is one) + + 3. In this routine, provide the streamed connectivities for each of the + nsided elements. + + + Simple example: 5 6 + +--------+ + 3 nsided elements: /| \ + (1 4-sided / | \ + 1 3-sided / | \ + 1 7-sided) / | \ 7 + /3 |4 + + +-----+ | + | | | + | | |8 + | | + + | | / + | | / + | | / + |1 |2 /9 + +-----+--------+ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NSIDED] = 3 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 3 x 1 + + for element_type of Z_NSIDED: + conn_array[0][0] = 4 (for the 4-sided element) + conn_array[1][0] = 3 (for the 3-sided element) + conn_array[2][0] = 7 (for the 7-sided element) + + Sum === + 14 <---------+ + | + 3. In this routine: | + length of nsided_conn_array will be: 14 + + nsided_conn_array[0] = 1 (connectivity of 4-sided element) + nsided_conn_array[1] = 2 + nsided_conn_array[2] = 4 + nsided_conn_array[3] = 3 + + nsided_conn_array[4] = 3 (connectivity of 3-sided element) + nsided_conn_array[5] = 4 + nsided_conn_array[6] = 5 + + nsided_conn_array[7] = 2 (connectivity of 7-sided element) + nsided_conn_array[8] = 9 + nsided_conn_array[9] = 8 + nsided_conn_array[10] = 7 + nsided_conn_array[11] = 6 + nsided_conn_array[12] = 5 + nsided_conn_array[13] = 4 + + + + +-------------------------------------------------------------------- +USERD_get_num_of_time_steps + + Description: + ----------- + Gets the number of time steps of data available for desired timeset. + + Specification: + ------------- + int USERD_get_num_of_time_steps( int timeset_number ) + + Returns: + ------- + Number of time steps in timeset (>0 if okay, <=0 if problems). + + Arguments: + --------- + (IN) timeset number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + Notes: + ----- + * This should be >= 1 1 indicates a static model + >1 indicates a transient model + + * Num_time_steps[timeset_number] would be set here + + + +-------------------------------------------------------------------- +USERD_get_number_of_files_in_dataset + + Description: + ----------- + Get the total number of files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_number_of_files_in_dataset( void ) + + Returns: + ------- + The total number of files in the dataset. + + Arguments: + --------- + none + + Notes: + ----- + * You can be as complete as you want about this. If you don't + care about the dataset query option, return a value of 0 + If you only want certain files, you can just include them. But, + you will need to supply the info in USERD_get_dataset_query_file_info + for each file you include here. + + * Num_dataset_files would be set here + + +-------------------------------------------------------------------- +USERD_get_number_of_material_sets - + + Description: + ----------- + Get the number of material sets in the model + + Specification: + ------------- + int USERD_get_number_of_material_sets( void ) + + + Returns: + ------- + Num_material_sets = number of material sets + (Zero would indicate that you have no materials + to deal with in the model) + + or + + -1 if an error condition + + Arguments: + --------- + none + + Notes: + ----- + * You may want to keep this as a global for use in other routines. + + ############################################################### + NOTE: For EnSight 7.6, only one material set is supported + within EnSight. + Thus the only valid returns here are: + 0 (no materials) + 1 (for the one material set allowed) + or -1 (if an error) + + If the casefile has more than this, this reader will + read them, but EnSight will issue an error message and + choke on them! + ############################################################### + + ================================================================ + A very simple explanatory example, to use as a reference for the + materials routines: + + Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials. + Most of the model is material 1, but the top left corner is material 9 - + basically as shown: + + + *--------*--------*--------* + | | / | | + | Mat 9 / | | + | | / | | + | |/ | | + | e7 / e8 | e9 | + | /| | | + | / | | | + | / | | | + *----/---*--------*--------* + | / | | | + | / | | | + | / | Mat 1 | + |/ | | | + | e4 | e5 | e6 | + | | | | + | | | | + | | | | + *--------*--------*--------* + | | | | + | | | | + | | | | + | | | | + | e1 | e2 | e3 | + | | | | + | | | | + | | | | + *--------*--------*--------* + + + Thus, in this routine, set: + Num_material_sets = 1 + + In USERD_get_matf_set_info, set: + mat_set_ids[0] = 1 + mat_set_name[0] = "Material Set 1" (or whatever name desired) + + In USERD_get_number_of_materials, input would be set_index = 0, and + would need to set: + Num_materials[0] = 2 + + For simplicity, the ids and descriptions that would be returned in + USERD_get_matf_var_info could be: + mat_ids[0] = 1 + mat_ids[1] = 9 + mat_desc[0] = "mat 1" (or whatever desired) + mat_desc[2] = "mat 9" + + The per element material ids list would need to be: + + material ids: + ------------- + ids_list[0] = 1 (material id 1, for elem e1) + ids_list[1] = 1 ( " e2) + ids_list[2] = 1 ( " e3) + ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4) + ids_list[5] = 1 (material id 1, for elem e5) + ids_list[5] = 1 ( " e6) + ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7) + ids_list[5] = -9 ( " e8) + ids_list[5] = 1 (material id 1, for elem e9) + + Finally we need the mixed material ids list and the mixed materials values list, + which would need to be: + + mixed-material ids: + ------------------- + ==> 1 ids_list[0] = 2 (the -1 in the material variable points here, + 2 indicates that two materials are present) + 2 ids_list[1] = 1 (1st material is 1) + 3 ids_list[2] = 9 (2nd material is 9) + 4 ids_list[3] = -1 (negative of index into mixed-material val_list) + ==> 5 ids_list[4] = 2 (the -5 in the material variable points here, + 2 indicates that two materials are present) + 6 ids_list[5] = 1 (1st material is 1) + 7 ids_list[6] = 9 (2nd material is 9) + 8 ids_list[7] = -3 (negative of index into mixed-material val_list) + ==> 9 ids_list[8] = 2 etc. + 10 ids_list[9] = 1 + 11 ids_list[10] = 9 + 12 ids_list[11] = -5 + + mixed-material values: + ---------------------- + ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here, + and this is the value for material 1) + 2 val_list[1] = 0.125 (the value for material 9) + ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here) + 4 val_list[3] = 0.875 + ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here) + 6 val_list[5] = 0.125 + + So, USERD_size_matf_data would need to return + matf_size = 8, when called with set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX + + matf_size = 12, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX + + = 6, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE + + And, USERD_load_matf_data would need to return: + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX (indicating id list). + + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX (indicating id list). + + the float array val_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE (indicating val list). + + +------------------------------------------------------------------------- +USERD_get_number_of_materials + + Description: + ----------- + Gets the number of materials in the material set + + Specification: + ------------- + int USERD_get_number_of_materials( int set_index ) + + Returns: + ------- + Num_materials[set_index] = Number of materials in the set + 0 indicates no materials information present + -1 indicates an error + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero + * You may want to keep this as a global for use in other routines. + + + +-------------------------------------------------------------------- +USERD_get_number_of_model_parts + + Description: + ----------- + Gets the total number of unstructured and structured parts + in the model, for which you can supply information. + + Specification: + ------------- + int USERD_get_number_of_model_parts( void ) + + Returns: + ------- + Number of parts (>0 if okay, <=0 if problems). + + Arguments: + --------- + none + + Notes: + ----- + * If going to have to read down through the parts in order to + know how many, you may want to build a table of pointers to + the various parts, so you can easily get to particular parts in + later processes. If you can simply read the number of parts + at the head of the file, then you would probably not build the + table at this time. + + * This routine would set Numparts_available, which is equal to + Num_unstructured_parts + Num_structured_blocks. + + + +-------------------------------------------------------------------- +USERD_get_number_of_timesets + + Description: + ----------- + Gets the number of timesets used in the model. + + Specification: + ------------- + int USERD_get_number_of_timesets( void ) + + Returns: + ------- + Number of timesets in the model + + Arguments: + --------- + none + + Notes: + ----- + * Num_timesets would be set here + + * If you have a static model, both geometry and variables, you should + return a value of zero. + + * If you have a transient model, then you should return one or more. + + For example: + + Geometry Variables No. of timesets + --------- ------------------------------ --------------- + static static 0 + static transient, all using same timeset 1 + + transient transient, all using same timeset as geom 1 + + static transient, using 3 different timesets 3 + + transient transient, using 3 different timesets and + none of them the same as the + geometry timeset 4 + etc. + + NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide + the timeset number to use + for geometry in: + USERD_get_geom_timeset_number + + Variables can use the same timeset as the geometry, or can use + other timesets. More than one variable can use the same timeset. + + example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0 + variable 1 provided at these same five steps + variable 2 provided at 3 steps, 0.5, 1.25, 3.33 + + This routine should return a value of 2, because only + two different timesets are needed. Timeset 1 would be for the + geometry and variable 1 (they both use it). Timeset 2 would + be for variable 2, which needs its own in this case. + + + + + +-------------------------------------------------------------------- +USERD_get_number_of_variables + + Description: + ----------- + Get the number of variables for which you will be providing info. + + Specification: + ------------- + int USERD_get_number_of_variables( void ) + + Returns: + ------- + Number of variables (includes constant, scalar, vector and tensor types) + (>=0 if okay, <0 if problem) + + Arguments: + --------- + none + + Notes: + ----- + ***************************************************************** + * Variable numbers, by which references will be made, are implied + here. If you say there are 3 variables, the variable numbers + will be 1, 2, and 3. + ***************************************************************** + + * Num_variables would be set here + + + +-------------------------------------------------------------------- +USERD_get_part_coords + + Description: + ----------- + Gets the coordinates for an unstructured part. + + Specification: + ------------- + int USERD_get_part_coords(int part_number, float **coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) coord_array = 2D float array which contains, + x,y,z coordinates of each node + in the part. + + (IMPORTANT: The second dimension of this aray is 1-based!!!) + + (Array will have been allocated + 3 by (number_of_nodes + 1) for the part + long - see USERD_get_gold_part_build_info) + + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + coord_array[3][101] + + Ignore the coord_array[0][0] + coord_array[1][0] + coord_array[2][0] locations and start + the node coordinates at: + coord_array[0][1] + coord_array[1][1] + coord_array[2][1] + + coord_array[0][2] + coord_array[1][2] + coord_array[2][2] + + etc. + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_element_ids_by_type + + Description: + ----------- + Gets the ids for the elements of a particular type for an unstructured + or structured part. + + Specification: + ------------- + int USERD_get_part_element_ids_by_type(int part_number, + int element_type, + int *elemid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (OUT) elemid_array = 1D array containing id of each + element of the type. + + (Array will have been allocated + number_of_elements of the type long) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25] when called with Z_TRI03 + + conn_array[100] when called with Z_QUA04 + + conn_array[30] when called with Z_HEX08 + + Notes: + ----- + * Not called unless element label status is set to TRUE in + USERD_get_element_label_status + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_part_elements_by_type + + Description: + ----------- + Gets the connectivities for the elements of a particular type in an + unstructured part + + Specification: + ------------- + int USERD_get_part_elements_by_type(int part_number, + int element_type, + int **conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + + (OUT) conn_array = 2D array containing connectivity + of each element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_HEX08 + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_node_ids + + Description: + ----------- + Gets the node ids of an unstructured or structured part. + + Specification: + ------------- + int USERD_get_part_node_ids(int part_number, int *nodeid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) nodeid_array = 1D array containing node ids of + each node in the part. + + (IMPORTANT: This array is 1-based!!!) + + (Array will have been allocated + (number_of_nodes + 1) for the part long + see USERD_get_gold_part_build_info) + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + nodeid_array[101] + + Ignore the nodeid_array[0] location and start + the node ids at: + nodeid_array[1] + + nodeid_array[2] + + etc. + + Notes: + ----- + * Not called unless node label status is TRUE, as returned from + USERD_get_node_label_status + + * Will be based on Current_time_step + + * The ids are purely labels, used when displaying or querying node ids. + However, any node id < 0 will never be displayed + + +-------------------------------------------------------------------- +USERD_get_reader_descrip + + Description: + ----------- + Gets the description of the reader, so gui can give more info + + Specification: + ------------- + int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) descrip = the description of the reader (max length is MAXFILENP, + which is 255) + + Notes: + ----- + * OPTIONAL ROUTINE! You can have it or not. + + + +-------------------------------------------------------------------- +USERD_get_reader_version + + Description: + ----------- + Gets the version number of the user defined reader + + Specification: + ------------- + int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (and will assume is version 1.0) + + Arguments: + --------- + (OUT) version_number = the version number of the reader + (max length is Z_MAX_USERD_NAME, which + is 20) + + Notes: + ----- + * This needs to be "2.000" or greater. Otherwise EnSight will assume + this reader is API 1.0 + + * should set it to "2.010" for this version of the API + + + + +-------------------------------------------------------------------- +USERD_get_sol_times + + Description: + ----------- + Get the solution times associated with each time step for + desired timeset. + + Specification: + ------------- + int USERD_get_sol_times(int timeset_number, + float *solution_times) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) solution_times = 1D array of solution times per time step + + (Array will have been allocated + Num_time_steps[timeset_number] long) + + Notes: + ----- + * The solution times must be non-negative and increasing. + + + +-------------------------------------------------------------------- +USERD_get_timeset_description - + + Description: + ----------- + Get the description to associate with the desired timeset. + + Specification: + ------------- + int USERD_get_timeset_description(int timeset_number, + char timeset_description[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) timeset_description = timeset description string + + + Notes: + ----- + * A string of NULLs is valid for timeset_description + + + + +-------------------------------------------------------------------- +USERD_get_var_by_component + + Description: + ----------- + Gets the values of a variable component. Both unstructured and structured + parts use this routine. + + if Z_PER_NODE: + Get the component value at each node for a given variable in the part. + + or if Z_PER_ELEM: + Get the component value at each element of a specific part and type + for a given variable. + + Specification: + ------------- + int USERD_get_var_by_component(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + or: Z_UNDEF, in which case you need not load any values into var_array + + + Arguments: + --------- + (IN) which_variable = The variable number + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + (IN) var_type = Z_SCALAR + Z_VECTOR + Z_TENSOR (symmetric tensor) + Z_TENSOR9 (asymmetric tensor) + + (IN) which_type + + if Z_PER_NODE: Not used + + if Z_PER_ELEM: = The element type + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (IN) imag_data = TRUE if imag component + FALSE if real component + + (IN) component = The component: (0 if Z_SCALAR) + (0 - 2 if Z_VECTOR) + (0 - 5 if Z_TENSOR) + (0 - 8 if Z_TENSOR9) + + * 6 Symmetric Indicies, 0:5 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 22 23 | = | 1 5 | * + * | | | | * + * | 33 | | 2 | * + + + * 9 General Indicies, 0:8 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 21 22 23 | = | 6 1 5 | * + * | | | | * + * | 31 32 33 | | 7 8 2 | * + + (OUT) var_array + + ----------------------------------------------------------------------- + (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!) + ----------------------------------------------------------------------- + + if Z_PER_NODE: = 1D array containing variable component value + for each node. + + (Array will have been allocated + (number_of_nodes + 1) long) + + Info stored in this fashion: + var_array[0] = not used + var_array[1] = var component for node 1 of part + var_array[2] = var_component for node 2 of part + var_array[3] = var_component for node 3 of part + etc. + + if Z_PER_ELEM: = 1D array containing variable component + value for each element of a particular + part and type. + + (Array will have been allocated + (number_of_elements[which_part][which_type] + 1) + long. See USERD_get_gold_part_build_info) + + Info stored in this fashion: + var_array[1] = var component for elem 1 (of part and type) + var_array[2] = var component for elem 2 (of part and type) + var_array[3] = var component for elem 3 (of part and type) + etc. + + Notes: + ----- + * Not called unless Num_variables is > 0 + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * Will be based on Current_time_step + + * If the variable is not defined for this part, simply return with a + value of Z_UNDEF. EnSight will treat the variable as undefined for + this part. + + +-------------------------------------------------------------------- +USERD_get_var_value_at_specific + + Description: + ----------- + if Z_PER_NODE: + Get the value of a particular variable at a particular node in a + particular part at a particular time. + + or if Z_PER_ELEM: + Get the value of a particular variable at a particular element of + a particular type in a particular part at a particular time. + + + Specification: + ------------- + int USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part, + int which_elem_type, + int time_step, + float values[3], + int imag_data) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) which_node_or_elem + + If Z_PER_NODE: + = The node number. This is not the id, but is + the index of the global node + list (1 based), or the block's + node list (1 based). + + Thus, coord_array[1] + coord_array[2] + coord_array[3] + . | + . |which_node_or_elem index + . ---- + + + If Z_PER_ELEM: + = The element number. This is not the id, but is + the element number index + of the number_of_element array + (see USERD_get_gold_part_build_info), + or the block's element list (1 based). + + Thus, for which_part: + conn_array[which_elem_type][0] + conn_array[which_elem_type][1] + conn_array[which_elem_type][2] + . | + . which_node_or_elem index + . ---- + + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + + (IN) which_elem_type + + If Z_PER_NODE, or block part: + = Not used + + If Z_PER_ELEM: + = The element type. This is the element type index + of the number_of_element array + (see USERD_get_gold_part_build_info) + + (IN) time_step = The time step + + (IN) imag_data = TRUE if want imaginary value. + FALSE if want real value. + + (OUT) values = scalar or vector component value(s) + values[0] = scalar or vector[0] + values[1] = vector[1] + values[2] = vector[2] + + + Notes: + ----- + * This routine is used in node querys over time (or element querys over + time for Z_PER_ELEM variables). If these operations are not critical + to you, this can be a dummy routine. + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * The time step given is for the proper variable timeset. + + +---------------------------------------------------------------------- +USERD_load_matf_data + + Description: + ----------- + Get the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_load_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *ids_list, + float *val_list) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) ids_list = If mat_type is Z_MAT_INDEX: + --------------------------- + 1D material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MAT_INDEX) + + If mat_type is Z_MIX_INDEX: + --------------------------- + 1D mixed-material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_INDEX) + + (OUT) val_list = 1D mixed-materials values list + (only used if mat_type is Z_MIX_VALUE) + + (Float array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_VALUE) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, + or Num_materials[set_index] is zero, + or the appropriate size from USERD_size_matf_data is zero + + + +-------------------------------------------------------------------- +USERD_set_filenames + + Description: + ----------- + Receives the geometry and result filenames entered in the data + dialog. The user written code will have to store and use these + as needed. The user written code must manage its own files!! + + Specification: + ------------- + int USERD_set_filenames(char filename_1[], + char filename_2[], + char the_path[], + int swapbytes) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) filename_1 = the filename entered into the geometry + field of the data dialog. + + (IN) param_2 = The usage of this string depends on + 'two_fields' in USERD_get_name_of_reader. + + If two_fields is FALSE then it's empty. + + If two_fields is TRUE, this is the + manditory results file entered + into the result field of the data dialog. + + If two_fields is -1, then this contains + optional text (filenames, modifiers, etc.) + that can be parsed and used to modify + reader + + (IN) the_path = the path info from the data dialog. + Note: filename_1 and filename_2 have already + had the path prepended to them. This + is provided in case it is needed for + filenames contained in one of the files + + (IN) swapbytes = TRUE if should swap bytes when reading data. + = FALSE normally. + + Notes: + ----- + * Since you must manage everything from the input that is entered in + these data dialog fields, this is an important routine! + + * It may be that you will need to have an executive type file that contains + info and other filenames within it, like EnSight6's case file. + + +-------------------------------------------------------------------- +USERD_set_server_number + + Description: + ----------- + Receives the server number of how many total servers. + + Specification: + ------------- + int USERD_set_server_number(int cur_serv, + int tot_servs) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) cur_serv = the current server. + + (IN) tot_servs = the total number of servers. + + Notes: + ----- + * Only useful if your user defined reader is being used with EnSight's + Server-of-Server capability. And even then, it may or may not be + something that you can take advantage of. If your data is already + partitioned in some manner, such that you can access the proper + portions using this information. + + For all non-SOS uses, this will simply be 1 of 1 + + + +-------------------------------------------------------------------- +USERD_set_time_set_and_step + + Description: + ----------- + Set the current time step in the desired timeset. All functions that + need time, and that do not explicitly pass it in, will use the timeset + and step set by this routine, if needed. + + Specification: + ------------- + void USERD_set_time_set_and_step(int timeset_number, + int time_step) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) timeset_number = the timeset number (1 based). + + For example: If USERD_get_number_of_timesets + returns 2, the valid timeset_number's + would be 1 and 2. + + (IN) time_step = The current time step to set + + Notes: + ----- + * Current_time_step and Current_timeset would be set here + + +-------------------------------------------------------------------- +USERD_size_matf_data + + Description: + ----------- + Get the length of the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_size_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *matf_size) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) matf_size = the length of the material id list, or + mixed-material id list, or + mixed-material values list + for the given material set and part number + (and element type if Z_MAT_INDEX) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_stop_part_building + + Description: + ----------- + This routine called when the part building dialog is closed. It is + provided in case you desire to release memory, etc. that was only needed + during the part building process. + + Specification: + ------------- + void USERD_stop_part_building( void ) + + Returns: + ------- + nothing + + Arguments: + --------- + none + + Notes: + ----- + +-------------------------------------------------------------------- +USERD_rigidbody_existence + + Description: + ----------- + Gets the existence of rigid body values or not in the model + + Specification: + ------------- + int USERD_rigidbody_existence( void ) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + none + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_rigidbody_values + + Description: + ----------- + Gets the rigid body values for each part + + Specification: + ------------- + int USERD_rigidbody_values(int part_number, + float values[7]) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + (IN) part_number = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) values values[0] = IX (x location) + values[1] = IY (y location) + values[2] = IZ (z location) + values[3] = E0 (e0 euler value) + values[4] = E1 (e1 euler value) + values[5] = E2 (e2 euler value) + values[6] = E3 (e3 euler value) + + + Notes: + ----- + * This will be based on Current_time_step + * It will not be called unless USERD_rigidbody_existence indicates + that there are some values in the model by returning Z_OK. + + +-------------------------------------------------------------------- +USERD_set_right_side + + Description: + ----------- + Informs the reader that the time currently set is the right side of a time + span used for variable interpolation between time steps + + Specification: + ------------- + void USERD_set_right_side( void ) + + Returns: + ------- + + Arguments: + --------- + none + + Notes: + ----- + * Applies to Current_time_step + + + + + +------------------------------------------------------------------ + ENHANCED GUI ROUTINES + +-------------------------------------------------------------------- +USERD_get_extra_gui_numbers + + Description: + ----------- + The Enhanced GUI routines are added to allow + the user to customize a portion of the Data + Reader dialog to pass in options to their + user defined reader. + + Specification: + ------------- + void USERD__get_extra_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_extra_gui_numbers + USERD_get_extra_gui_defaults + USERD_set_extra_gui_data + + The existence of these routine indicates that + you wish to add customize entries to the + Data Reader dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_extra_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_extra_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_extra_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_extra_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_extra_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_extra_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_numbers + + Description: + ----------- + The Var_Extract_GUI routines are added to allow + the user to customize a extraction parameters + for variables "after" the file has been read. + These things can be modified and the variables will + be update/refreshed according to the new parameters set + + Specification: + ------------- + void USERD_get_var_extract_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults (this one) + USERD_set_var_extract_gui_data + + The existence of these routine indicates that + you wish to have the Var Extract Parameters dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_var_extract_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_var_extract_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_var_extract_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_var_extract_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_var_extract_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + + + +----------------------------------------------------------------------------------- +/* ---------------------------------------------------------- + * New in EnSight 8 is the capability to remove (fail) elements + * based on variable threshold values. Basically the variable + * name, a couple of thresholds, a couple of values and a logic + * criteria are read in from this routine. Every element that + * satisfies the failure criteria is removed and not used in + * EnSight calculations. + * + * Example Failure criteria + * Let fail_var_name = "fail_flag" + * threshold_val1 = 0 + * threshold_operator1 = Z_EQUAL_TO + * logic_criteria2 not used + * threshold_val2 not used + * threshold_operator2 not used + * For each value of "fail_flag" at each element, + * if fail flag == threshold_val1 (0.0) then element fails + * Return (Z_ERR) if this is not used. + * Return (Z_OK) if failed element feature should be used + * + * threshold_operator1 & 2 can be one of the following + * Z_ELE_FAILED_NONE, - disables checking + * Z_ELE_FAILED_GREATER, - greater than + * Z_ELE_FAILED_LESS, - less than + * Z_ELE_FAILED_EQUAL, - equal + * Z_ELE_FAILED_NOT_EQUAL, - not equal + * Z_ELE_FAILED_MANY - not used + * + * logic_criteria2 + * Z_ELE_FAILED_LOGIC_NONE, + * Z_ELE_FAILED_LOGIC_AND, + * Z_ELE_FAILED_LOGIC_OR, + * Z_ELE_FAILED_LOGIC_MANY + * + * ---------------------------------------------------------- */ +int USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + +/*-------------------------------------------------------------------- + * USERD_get_structured_reader_cinching - + *-------------------------------------------------------------------- + * + * Gets whether this reader will do structured cinching for block data + * This means that it will handle the min, max, and step values for a + * given block and return the coordinate components or variable components + * in their "cinched" state when partial extraction or striding is used. + * This is as opposed to returning the entire component (ignoring min, max + * and stride) and letting Ensight pick out the values actually used. + * + * returns: Z_OK if the reader will handle the + * min, max, and stride and return + * the cinched values only. + * + * Z_UNDEF or Z_ERR if will return entire component + * and rely on EnSight to cinch. + * + * Notes: + * Unless you can actually pull out the desired min, max, and stride + * without using a full component of memory, don't enable this feature. + *--------------------------------------------------------------------*/ +int +USERD_get_structured_reader_cinching( void ) + + + +/*-------------------------------------------------------------------- + * USERD_set_block_range_and_stride - + *-------------------------------------------------------------------- + * + * Sets the min, max, and step values in each of the i, j, and k, directions + * for the given part. + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in + * USERD_get_gold_part_build_info) + * + * (IN) mini = min i plane desired (zero based) + * maxi = max i plane desired (zero based) + * stepi = i stride + * minj = min j plane desired (zero based) + * maxj = max j plane desired (zero based) + * stepj = j stride + * mink = min k plane desired (zero based) + * maxk = max k plane desired (zero based) + * stepk = k stride + * + * + * returns: Z_OK if no problems + * Z_ERR if an error + * + * Notes: + * * It will not be called unless USERD_get_structured_reader_cinching + * indicates that this reader does structured cinching by returning + * a Z_OK. + * + * * It will actually be called before each geom component and before + * each part variable - so if you are storing things locally, you should + * make this routine be able to quickly check whether anything needs + * updated or not. + * + * * If the stride (step) does not hit right on the max, the last element + * in each direction will be shortened appropriately. + * For example, if a block had 0 to 12 in the i direction, + * and the user specified min = 1 + * max = 8 + * step = 3 + * + * 0 1 2 3 4 5 6 7 8 9 10 11 12 + * | | | | | | | | | | | | | + * + * | | | | + * + * Namely, the coarser cell boundaries in this direction would be at 1, 4, +7, and 8 + * + *--------------------------------------------------------------------*/ +int +USERD_set_block_range_and_stride(int part_number, + int mini, int maxi, int stepi, + int minj, int maxj, int stepj, + int mink, int maxk, int stepk) + + + +---- end of document ---- diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.08 b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.08 new file mode 100644 index 0000000000..29e185d4d0 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_2.08 @@ -0,0 +1,4653 @@ +README_USERD_2.08 +================= +-------------------------------------- +EnSight User Defined Reader Capability ===> (API 2.08) +-------------------------------------- +A user defined reader capability is included in EnSight which can allow +otherwise unsupported structured or unstructured data to be read. The user +defined reader capability utilizes dynamic shared libraries composed of +routines defined in this document but produced by you, the user, (or some +third party). This capability is currently available for dec, ibm, hp, sgi, +sun, linux, alpha linux, and NT servers. + +You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0 +for a discussion of the differences between API 1.0 and API 2.*. + +***>> API 2.08 invloves a slight change to API 2.05 and later: +Namely, rotational (yaw,pitch,roll) values were added to the values +argument of USERD_rigidbody_values routine. + +***>> API 2.07 additional capabilities (beyond API 2.06): +Optional routine to allow userd defined readers to indicate their auto +distribute preference when used with SOS. This is used to set the auto +distribute flag default in the client. If the function does not exist, +then it defaults to 'use auto distribute'. If the function does exist and +indicates 'no auto distribute', then it's up to the UDR to decompose a +distributed data set. + USERD_prefer_auto_distribute +Optional routine to allow userd defined readers to indicate their +preference for the 'Set file...' button labels in the client's File->Open +dialog. If the function does not exist or it returns a null string for +an argument, then the default values are used. + USERD_set_filename_button_labels + +***>> API 2.06 additional capabilities (beyond API 2.05): +Routines to allow userd defined readers for structured data +to deal with min, max, and stride within the reader itself +instead of within EnSight. + USERD_get_structured_reader_cinching + USERD_set_block_range_and_stride + + +***>> API 2.05 additional capabilities (beyond API 2.04): +Routines to handle material species. + USERD_get_number_of_species + USERD_get_matsp_info + +Routines to handle variable extraction parameters after a read, and then +update the variables accordingly. Similar to the extra GUI capabilities +(which are processed before a read). (Can actually be added to pre-2.05 readers) + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + +Routines to obtain rigid body values from a reader. +(Routines were added - EnSight is now using for Nastran and STL readers + with Dynasty rigid body motion data file) + USERD_rigidbody_existence + USERD_rigidbody_values + +Routine that lets reader know when EnSight is getting the right side of a time +interval for variable interpolation between steps. Not generally needed for +most readers - however, may be needed for those that implement rigid body, and +wish to cache left and right timespan information for interpolation within the +reader itself. (Can actually be added to pre-2.05 readers) + USERD_set_right_side + + +***>> API 2.04 additional capabilities (beyond API 2.03): +Routines to handle failed elements. Basically +a.One routine to return a flag indicating the existence of + failed elements in at least one part in at least one + timestep in the model. +b.A second routine to return a matrix of flags indexed by part and + element type indicating which parts and element types have failed + elements at the current time step. +c.Finally a third routine to return an array of flags for a given + part and element type that is number of elements of that type long + indicating which elements have failed, and which have not failed. + + +***>> API 2.03 additional capabilities (beyond API 2.01): +1. Routines to handle materials +2. Routines to handle nsided and nfaced elements +3. Modified routine to handle structured ranges + + +**************************************************************************** +Note: Only the the Ensight Gold example reader, has been moved to + this 2.06 API level. And it is purely for an example - it does not + actually provide a benefit. +**************************************************************************** + + +The process for producing a user defined reader is: +--------------------------------------------------- +1. Write code for all pertinent routines in the library (Unless someone else + has done this for you). + + This is of course where the work is done by the user. The word + "pertinent" is used because depending on the nature of the data, some + of the routines in the library may be dummy routines. + + The source code for a dummy_gold library and for various other + working or sample libraries is copied from the installation CD during + installation. These will be located in directories under: + + $CEI_HOME/ensight76/user_defined_src/readers + + examples: + -------- + Basic dummy_gold routines provide skeleton for a new reader + $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold + + Sample library which reads unstructured binary EnSight Gold data + $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold + + You may find it useful to place your library source in this area as + well, but are not limited to this location. + + * ===> The descriptions of each library routine and the order that the + routines are called, which is provided in this file, along with + the example libraries, should make it possible for you to produce + code for your own data reader. + + +2. Produce the dynamic shared library. + + This is a compiling and loading process which varies according to + the type of machine you are on. In the user-defined-reader source + tree we have tried to isolate the machine dependent parts of the + build process using a set of files in the 'config' directory. In this + directory there is a configuration file for each platform on which + EnSight is supported. Before you can compile the installed readers + you should run the script called 'init' in the config directory. + + i.e. (for UNIX) + cd config + ./init sgi_6.5_n64 + cd .. + make + + If you are compiling for Windows NT, there are two options. If you + have the Cygwin GNU utilities installed, you can use GNU make as for + Unix. Otherwise, there is a script called makeall.cmd which will + build all of the readers using nmake. The Makefiles in each reader + directory will work using either make or nmake. + + i.e. (WIN32 Cygwin) (using nmake) + cd config cd config + sh init win32 cp win32 config + cd .. cd .. + mkdir lib + make makeall.cmd + + If you have platform-specific portions of code in your reader, the + build system defines a set of flags which can be used within + #ifdef ... #endif regions in your source, as shown in the table + below. + + Because the readers are now dynamically opened by EnSight, you may + have to include dependent libraries on your link-line to avoid having + unresolved symbols. If you are having problems with a reader, start + ensight as "ensight7 -readerdbg" and you will get feedback on any + problems encountered in loading a reader. If there are unresolved + symbols, you need to find the library which contains the missing + symbols and link it into your reader by adding it to the example + link commands below. + + If you choose to use a different build environment for your reader, + you should take care to use compatible compilation flags to ensure + compatibilty with the EnSight executables, most notably on the SGI + and HP-UX 11.0 platforms, which should use the following flags: + + sgi_6.2_o32: -mips2 + sgi_6.2_n64: -mips4 -64 + sgi_6.5_n32: -mips3 + sgi_6.5_n64: -mips4 -64 + hp_11.0_32: +DA2.0 + hp_11.0_64: +DA2.0W + + ______________________________________________________________________ + | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED | + | TYPE |------------------------------------------------------------| + | | LD COMMAND USED IN MAKEFILE | + ====================================================================== + ______________________________________________________________________ + | sgi | -DSGI | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | hp | -DHP | libuserd-X.sl | + | |------------------------------------------------------------| + | | ld -b -o libuserd-X.sl libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | sun | -DSUN | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | dec | -DDEC | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | linux | -DLINUX | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | alpha | -DALINUX | libuserd-X.so | + | linux |------------------------------------------------------------| + | | ld -shared -o libuserd-X.so libuserd-X.o -lc | + ---------------------------------------------------------------------- + ______________________________________________________________________ + | ibm | -DIBM | libuserd-X.so | + | |------------------------------------------------------------| + | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc | + ---------------------------------------------------------------------- + + Once you have created your library, you should place it in a directory + of your choice or in the standard reader location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + For example, if you created a reader for "mydata", you should create + the reader libuserd-mydata.so and place the file in your own reader + directory (see section 3 below) or in the standard location: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so + + +3. By default EnSight will load all readers found in the directory: + + $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers + + Files with names "libuserd-X.so" (where X is a name unique to the reader) + are assumed to be user-defined readers. + + There are two methods which can be used to supplement the default + behavior. + + (1) A feature which is useful for site-level or user-level configuration + is the optional environment variable $ENSIGHT7_READER. This + variable directs EnSight to load all readers in the specified reader + directory (you should probably specify a full path) before loading + the built-in readers. If the same reader exists in both directories + (as determined by the name returned by USERD_get_name_of_reader(), + NOT by the filename), the locally configured reader will take + precedence. + + (2) A useful feature for end-users is the use of the libuserd-devel + reader. EnSight will search for a reader named libuserd-devel.so + (.sl for HP or .dll for NT). This reader can exist anywhere in the + library path (see below) of the user. This is useful for an + individual actively developing a reader because the existence of a + libuserd-devel library will take precedence over any other library + which returns the same name from USERD_get_name_of_reader(). + + As an example, a site may install commonly used readers in a common + location, and users can set the ENSIGHT7_READER variable to access them: + + setenv ENSIGHT7_READER /usr/local/lib/e7readers + + A user working on a new reader may compile the reader and place it in + a directory specified by the library path: + + cp libuserd-myreader.so ~/lib/libuserd-devel.so + setenv ~/lib:$ + + The user is responsible for correctly configuring the library path + variable in order to make use of the libuserd-devel feature. The + library environment variables used are: + + Machine type Environment variable to set + ------------ --------------------------- + sgi LD_LIBRARY_PATH + dec LD_LIBRARY_PATH + sun LD_LIBRARY_PATH + linux LD_LIBRARY_PATH + alpha linux LD_LIBRARY_PATH + hp SHLIB_PATH + ibm LIBPATH + +As always, EnSight support is available if you need it. + +------------------------------- +Quick Index of Library Routines +------------------------------- + +Generally Needed for UNSTRUCTURED data +-------------------------------------- +USERD_get_part_coords part's node coordinates +USERD_get_part_node_ids part's node ids +USERD_get_part_elements_by_type part's element connectivites +USERD_get_part_element_ids_by_type part's element ids + + +Generally Needed for BLOCK data +-------------------------------------- +USERD_get_block_coords_by_component block coordinates +USERD_get_block_iblanking block iblanking values +USERD_get_ghosts_in_block_flag block ghost cell existence? +USERD_get_block_ghost_flags block ghost cell flags + + These routines, which formerly were only for unstructured data, will now + also be called for structured data if you specify that ids will be given + in the USERD_get_node_label_status and USERD_get_element_label_status rotuines + ------------------------------------------------------------------------------ + USERD_get_part_node_ids part's node ids + USERD_get_part_element_ids_by_type part's element ids + + +Generally needed for either or both kinds of data +------------------------------------------------- +USERD_get_name_of_reader name of reader for GUI +USERD_get_reader_release release string of reader +USERD_get_reader_version provide reader version number +USERD_get_reader_descrip provide GUI more description (optional) + +USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields +USERD_get_extra_gui_defaults Gets the default values for the GUI members +USERD_set_extra_gui_data Returns the answers provided by the user + +USERD_set_filenames filenames entered in GUI +USERD_set_server_number server which of how many + +USERD_get_number_of_timesets number of timesets +USERD_get_timeset_description description of timeset +USERD_get_geom_timeset_number timeset # to use for geom + +USERD_get_num_of_time_steps number of time steps +USERD_get_sol_times solution time values +USERD_set_time_set_and_step current timeset and time step + +USERD_get_changing_geometry_status changing geometry? +USERD_get_node_label_status node labels? +USERD_get_element_label_status element labels? +USERD_get_model_extents provide model bounding extents +USERD_get_number_of_files_in_dataset number of files in model +USERD_get_dataset_query_file_info info about each model file +USERD_get_descrip_lines file associated description lines +USERD_get_number_of_model_parts number of model parts +USERD_get_gold_part_build_info Gets the info needed for part building process +USERD_get_part_build_info part/block type/descrip etc. +USERD_get_maxsize_info part/block allocation maximums +USERD_get_ghosts_in_model_flag model contains ghost cells? +USERD_get_nsided_conn Gets the element connectivities for nsided + elements. (utilizes the number of nodes + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced + elements (utilizes the number of faces + per element obtained in + USERD_get_part_elements_by_type) +USERD_get_nfaced_conn Gets the element connectivities for nfaced + elements (utilizes the number of nodes + per face obtained in + USERD_get_nfaced_nodes_per_face) + + +USERD_get_border_availability part border provided? +USERD_get_border_elements_by_type part border conn and parent info + +USERD_get_number_of_variables number of variables +USERD_get_gold_variable_info variable type/descrip etc. +USERD_get_var_by_component part or block variable values +USERD_get_constant_val constant variable's value +USERD_get_var_value_at_specific node's or element's variable value over time +USERD_stop_part_building cleanup after part build routine + +USERD_get_number_of_material_sets Gets the number of material sets +USERD_get_matf_set_info Gets the material set indices and names +USERD_get_number_of_materials Gets the number of materials +USERD_get_matf_var_info Gets the material indices and descriptions +USERD_size_matf_data Gets the length of either the + material ids list, + mixed-material ids list, or + mixed-material values list +USERD_load_matf_data Gets the material ids list, + mixed-material ids list, or + mixed-material values list + +USERD_bkup archive routine + +USERD_exit_routine cleanup upon exit routine + +USERD_get_uns_failed_params Gets thresholds/criteria for failure + +USERD_rigidbody_existence Returns whether rigid body transformation + data exists for the model. +USERD_rigidbody_values Returns the euler and location values for a + given part + +USERD_set_right_side Simply informs the reader when the time set + is for the right side of a time span during + variable interpolation between time steps. + +USERD_get_structured_reader_cinching Tells if the reader will do structured + cinching +USERD_set_block_range_and_stride Sets the min, max, and stride of a block + if doing structured cinching + + +------------------------- +Order Routines are called +------------------------- + +The various main operations are given basically in the order they will +be performed. Within each operation, the order the routines will be +called is given. + +1. Setting name in the gui, and specifying one or two input fields + + USERD_get_name_of_reader + USERD_get_reader_descrip (optional) + USERD_get_extra_gui_numbers (optional) + USERD_get_extra_gui_defaults (optional) + +2. Getting the reader version (also distinguishes between API's) + + USERD_get_reader_version + +3. Setting filenames and getting timeset and time info + + (optional if reader has + USERD_get_extra_gui_defaults routine) + USERD_get_structured_reader_cinching + USERD_set_server_number + USERD_set_extra_gui_data (optional) + USERD_set_filenames + USERD_get_number_of_timesets + USERD_get_geom_timeset_number + + for each timeset: + USERD_get_timeset_description + USERD_get_num_of_time_steps + USERD_get_sol_times + + USERD_set_time_set_and_step + +4. Gathering info for part builder + + USERD_set_time_set_and_step + USERD_get_changing_geometry_status + USERD_get_node_label_status + USERD_get_element_label_status + USERD_get_number_of_files_in_dataset + USERD_get_dataset_query_file_info + USERD_get_descrip_lines (for geometry) + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_maxsize_info + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR (for model extents) + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + +5. Gathering Variable info + + USERD_get_number_of_variables + USERD_get_gold_variable_info + +6. Part building (per part created) + + both unstructured and structured: + -------------------------------- + USERD_set_time_set_and_step + + if unstructured part: + -------------------- + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + + If any nsided elements: + + USERD_get_nsided_conn + + If any nfaced elements: + + USERD_get_nfaced_nodes_per_face + USERD_get_nfaced_conn + + USERD_get_part_coords + USERD_get_part_node_ids + + else if structured part: + ----------------------- + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + both again: + ---------- + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + USERD_stop_part_building (only once when part builder + dialog is closed) + +7. Loading Variables + + constants: + --------- + USERD_set_time_set_and_step + USERD_get_constant_val + + scalars/vectors/tensors: + ------------------------ + USERD_get_descrip_lines + USERD_set_time_set_and_step + (if doing structured reader cinching + USERD_get_var_by_component + +8. Changing geometry + + changing coords only (per part): + -------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_part_coords + (if doing structured reader cinching + USERD_get_block_coords_by_component + + changing connectivity (per part): + --------------------- + USERD_set_time_set_and_step + USERD_get_descrip_lines + USERD_get_number_of_model_parts + USERD_get_gold_part_build_info + USERD_get_ghosts_in_model_flag + USERD_get_get_ghosts_in_block_flag (if any ghost cells in model) + USERD_get_model_extents OR + USERD_get_part_coords AND/OR + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_part_element_ids_by_type + USERD_get_part_elements_by_type + USERD_get_part_coords + USERD_get_part_node_ids + USERD_get_block_iblanking + (if doing structured reader cinching + USERD_get_block_coords_by_component + USERD_get_block_ghost_flags (If ghost cells in part) + USERD_get_part_node_ids (If node ids given) + USERD_get_part_element_ids_by_type (If element ids given) + + USERD_get_border_availability (If border representation + USERD_get_border_elements_by_type is selected) + + +9. Node or Element queries over time + + USERD_get_var_value_at_specific + +10. To see if materials in the model + + USERD_get_number_of_material_sets + USERD_get_matf_set_info + + If any material sets in the model (calls these once per material set): + USERD_get_number_of_materials + USERD_get_matf_var_info + + For each elment type of each part containing material ids, calls: + USERD_size_matf_data + USERD_load_matf_data + + If there are any elements with mixed materials, when a domain or + interface is created, calls these again per part: + + USERD_size_matf_data + USERD_load_matf_data + +11. To modify the variable extraction parameters and have the variables + update accordingly. + + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults + USERD_set_var_extract_gui_data + + + +----------------------- +Detailed Specifications +----------------------- + +Include files: +-------------- +The following header file is required in any file containing these library +routines. + + #include "global_extern.h" + +And it references: + + #include "global_extern_proto.h" + + + +******************************************************************************* +****************************** Special Note *********************************** +******************************************************************************* + +Make sure you use the proper define in the global_extern.h header file, namely: +#define USERD_API_204 + +Also, Make sure the api version in the USERD_get_reader_version routine is set +to "2.04" or larger. + +Make sure your reader has access to the global_extern_proto.h This is a new +file which is accessed from the new global_extern.h + +******************************************************************************* +******************************************************************************* + + +Basis of arrays: +--------------- +Unless explicitly stated otherwise, all arrays are zero based - in true C +fashion. + + +Global variables: +---------------- +You will generally need to have a few global variables which are shared by +the various library routines. The detailed specifications below have assumed +the following are available. (Their names describe their purpose, and they +will be used in helping describe the details of the routines below). + +static int Numparts_available = 0; +static int Num_unstructured_parts = 0; +static int Num_structured_blocks = 0; + +/* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */ + +static int Num_timesets = 1; +static int Current_timeset = 1; +static int Geom_timeset_number = 1; + +static int Num_time_steps[Z_MAXSETS] = 1; +static int Current_time_step = 0; +static int Num_variables = 0; +static int Num_dataset_files = 0; + +static int Server_Number = 1; Which server of +static int Tot_Servers = 1; the total number of servers + + + +_________________________________________ +----------------------------------------- +Library Routines (in alphabetical order): +_________________________________________ +----------------------------------------- + +-------------------------------------------------------------------- +USERD_bkup + + Description: + ----------- + This routine is called during the EnSight archive process. You can + use it to save or restore info relating to your user defined reader. + + Specification: + ------------- + int USERD_bkup(FILE *archive_file, + int backup_type) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) archive_file = The archive file pointer + + (IN) backup_type = Z_SAVE_ARCHIVE for saving archive + Z_REST_ARCHIVE for restoring archive + + Notes: + ----- + * Since EnSight's archive file is saved in binary form, you should + also do any writing to it or reading from it in binary. + + * You should archive any variables, which will be needed for + future operations, that will not be read or computed again + before they will be needed. These are typically global + variables. + + * Make sure that the number of bytes that you write on a save and + the number of bytes that you read on a restore are identical!! + + * If any of the variables you save are allocated arrays, you must + do the allocations before restoring into them. + +-------------------------------------------------------------------- +USERD_exit_routine + + Description: + ----------- + This routine is called as EnSight is exiting. It can be used to clean + up anything needed - such as removing temporary files, etc. - or can simply + be a dummy. + + Specification: + ------------- + void USERD_exit_routine( void ) + + Arguments: + --------- + none + +-------------------------------------------------------------------- +USERD_get_block_coords_by_component + + Description: + ----------- + Get the coordinates of a given structured block, a component at a time. + + Specification: + ------------- + int USERD_get_block_coords_by_component(int block_number, + int which_component, + float *coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) which_component = Z_COMPX if x component wanted + = Z_COMPY if y component wanted + = Z_COMPZ if z component wanted + + (OUT) coord_array = 1D array containing x,y, or z + coordinate component of each node + + (Array will have been allocated + i*j*k for the block long) + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_block_iblanking + + Description: + ----------- + Get the iblanking value at each node of a block (if the block is + iblanked). + + Specification: + ------------- + int USERD_get_block_iblanking(int block_number, + int *iblank_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) iblank_array = 1D array containing iblank value + for each node. + + (Array will have been allocated + i*j*k for the block long) + + possible values are: Z_EXT = exterior + Z_INT = interior + Z_BND = boundary + Z_INTBND = internal boundary + Z_SYM = symmetry plane + + Notes: + ----- + * Not called unless Num_structured_blocks is > 0 and you have + some iblanked blocks + + * Will be based on Current_time_step + + + +---------------------------------------------------------------------- +USERD_get_block_ghost_flags + + Description: + ----------- + Get the ghost_flags value at each element of a block containing ghost cells. + + Specification: + ------------- + int USERD_get_block_ghost_flags(int block_number, + int *ghost_flags) + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) block_number = The block number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) ghost_flags = 1D array containing ghost flag value + for each block cell. + + (Array will have been allocated + (i-1)*(j-1)*(k-1) for the block long) + + possible values are: 0 = non-ghost cell (normal cell) + >0 = ghost cell + + Notes: + ----- + * This routine is new in the 2.01 API + + * This will be based on Current_time_step + + * Only called for structured "block" parts that have some ghost cells + as indicated by the USERD_get_ghost_in_block_flag. The model must + of course also have been indicated to have some ghost cells in the + USERD_get_ghost_in_model_flag routine. + + * It is sufficient to set the value to be 1 to flag as a ghost cell, + but the value can be any non-zero value, so you could use it to + indicate which block or which server (for Server-of-server use) the + cell is actually in. + + + +-------------------------------------------------------------------- +USERD_get_border_availability + + Description: + ----------- + Finds out if border elements are provided by the reader for the + desired part, or will need to be computed internally by EnSight. + + Specification: + ------------- + int USERD_get_border_availability(int part_number, + int number_of_elements[Z_MAXTYPE]) + + Returns: + ------- + Z_OK if border elements will be provided by the reader. + (number_of_elements array will be loaded and + USERD_get_border_elements_by_type will be called) + + Z_ERR if border elements are not available - thus EnSight must compute. + (USERD_get_border_elements_by_type will not be called) + + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) number_of_elements = 2D array containing number of + each type of border element in + the part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + + Notes: + ----- + * Only called if border representation is used. + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_border_elements_by_type + + Description: + ----------- + Provides border element connectivity and parent information. + + Specification: + ------------- + int USERD_get_border_elements_by_type(int part_number, + int element_type, + int **conn_array, + short *parent_element_type, + int *parent_element_num) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + + (OUT) conn_array = 2D array containing connectivity + of each border element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_QUA08] = 30 + as obtained in: + USERD_get_border_availability + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_QUA08 + + (OUT) parent_element_type = 1D array containing element type of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + (OUT) parent_element_num = 1D array containing element number of the + parent element (the one that the border + element is a face/edge of). + + (Array will have been allocated + num_of_elements of the type long) + + + Notes: + ----- + * Not called unless USERD_get_border_availability returned Z_OK + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_changing_geometry_status + + Description: + ----------- + Gets the changing geometry status for the model + + Specification: + ------------- + int USERD_get_changing_geometry_status( void ) + + Returns: + ------- + Z_STATIC if geometry does not change + Z_CHANGE_COORDS if changing coordinates only + Z_CHANGE_CONN if changing connectivity + + Arguments: + --------- + none + + Notes: + ----- + * EnSight does not support changing number of parts. But the + coords and/or the connectivity of the parts can change. Note that + a part is allowed to be empty (number of nodes and elements equal + to zero). + + +-------------------------------------------------------------------- +USERD_get_constant_val + + Description: + ----------- + Get the value of a constant at a time step + + Specification: + ------------- + float USERD_get_constant_value(int which_var, + int imag_data) + + Returns: + ------- + Value of the requested constant variable + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) imag_data = TRUE if want imaginary data value. + FALSE if want real data value. + + Notes: + ----- + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_dataset_query_file_info + + Description: + ----------- + Get the information about files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_dataset_query_file_info(Z_QFILES *qfiles) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) qfiles = Structure containing information about each file + of the dataset. The Z_QFILES structure is defined + in the global_extern.h file + + (The structure will have been allocated + Num_dataset_files long, with 10 description + lines per file). + + qfiles[].name = The name of the file + (Z_MAXFILENP is the dimensioned length + of the name) + + qfiles[].sizeb = The number of bytes in the file + (Typically obtained with a call to the + "stat" system routine) (Is a long) + + qfiles[].timemod = The time the file was last modified + (Z_MAXTIMLEN is the dimensioned length + of this string) + (Typically obtained with a call to the + "stat" system routine) + + qfiles[].num_d_lines = The number of description lines you + are providing from the file. Max = 10 + + qfiles[].f_desc[] = The description line(s) per file, + qfiles[].num_d_lines of them + (Z_MAXFILENP is the allocated length of + each line) + + Notes: + ----- + * If Num_dataset_files is 0, this routine will not be called. + (See USERD_get_number_of_files_in_dataset) + + +-------------------------------------------------------------------- +USERD_get_descrip_lines + + Description: + ----------- + Get two description lines associated with geometry per time step, + or one description line associated with a variable per time step. + + Specification: + ------------- + int USERD_get_descrip_lines(int which_type, + int which_var, + int imag_data, + char line1[Z_BUFL], + char line2[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_type = Z_GEOM for geometry (2 lines) + = Z_VARI for variable (1 line) + + (IN) which_var = If it is a variable, which one. + Ignored if geometry type. + + (IN) imag_data = TRUE if want imaginary data file. + FALSE if want real data file. + + (OUT) line1 = The 1st geometry description line, + or the variable description line. + + (OUT) line2 = The 2nd geometry description line + Not used if variable type. + + Notes: + ----- + * Will be based on Current_time_step + + * These are the lines EnSight can echo to the screen in + annotation mode. + + + +-------------------------------------------------------------------- +USERD_get_element_label_status + + Description: + ----------- + Answers the question as to whether element labels will be provided. + + Specification: + ------------- + int USERD_get_element_label_status( void ) + + Returns: + ------- + TRUE if element labels will be provided + FALSE if element labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * element lables are needed in order to do any element querying, or + element labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. + + API 1.0: + USERD_get_element_ids_for_part is used to obtain the ids, + on a part by part basis, if TRUE status is returned here. + + API 2.0: + USERD_get_part_element_ids_by_type is used to obtain the ids, + on a per part, per type basis, if TRUE status is returned here. + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them youself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model (especially + if you are dealing with a decomposed dataset). + + USERD_get_part_element_ids_by_type is used to obtain the ids, + on an element type by part basis, if TRUE status is returned here. + + * Will call USERD_get_part_element_ids_by_type for each type of + of each part if this routine returns TRUE. +-------------------------------------------------------------------- +USERD_get_geom_timeset_number - + + Description: + ----------- + Gets the timeset number to be used for geometry + + Specification: + ------------- + int USERD_get_geom_timeset_number( void ) + + Returns: + ------- + Geom_timeset_number = The timeset number that will be used for geometry. + For example, if USERD_get_number_of timesets + returns 2, the valid timeset numbers would be + 1 or 2. + + Arguments: + --------- + none + + Notes: + ----- + * If your model is static, which you indicated by returning a zero + in USERD_get_number_of_timesets, you can return a zero here as well. + + + +-------------------------------------------------------------------- +USERD_get_gold_part_build_info + + Description: + ----------- + Gets the info needed for the part building process. + + Specification: + ------------- + int USERD_get_gold_part_build_info(int *part_id, + int *part_types, + char *part_description[Z_BUFL], + int *number_of_nodes, + int *number_of_elements[Z_MAXTYPE], + int *ijk_dimensions[9], + int *iblanking_options[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) part_id = Array containing the external part + ids for each of the model parts. + + IMPORTANT: + Parts numbers must be >= 1, because + of the way they are used in the GUI + + ******************************************* + The ids provided here are the numbers by + which the parts will be referred to in the + GUI (if possible). They are basically + labels as far as you are concerned. + + Note: The part numbers you pass to routines + which receive a part_number or block_number + or which_part as an argument are the 1-based + table index of the parts! + + example: If Numparts_available = 3 + + Table index part_id + ----------- ------- + 1 13 + 2 57 + 3 125 + + ^ ^ + | | + | These are placed in: + | part_id[0] = 13 + | part_id[1] = 57 + | part_id[2] = 125 + | for GUI labeling purposes. + | + These implied table indices are the part_number, + block_number, or which_part numbers that you would + pass to routines like: + + USERD_get_part_coords(int part_number,... + USERD_get_part_node_ids(int part_number,... + USERD_get_part_elements_by_type(int part_number,... + USERD_get_part_element_ids_by_type(int part_number,... + USERD_get_block_coords_by_component(int block_number,... + USERD_get_block_iblanking(int block_number,... + USERD_get_block_ghost_flags(int block_number,... + USERD_get_ghosts_in_block_flag(int block_number) + USERD_get_border_availability(int part_number,... + USERD_get_border_elements_by_type(int part_number,... + USERD_get_var_by_component(int which_variable, + int which_part,... + USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part,... + ******************************************** + + (Array will have been allocated + Numparts_available long) + + (OUT) part_types = Array containing one of the + following for each model part: + + Z_UNSTRUCTURED or + Z_STRUCTURED or + Z_IBLANKED + + (Array will have been allocated + Numparts_available long) + + (OUT) part_description = Array containing a description + for each of the model parts + + (Array will have been allocated + Numparts_available by Z_BUFL + long) + + (OUT) number_of_nodes = Number of unstructured nodes in the part + + (Array will have been allocated + Numparts_available long) + + (OUT) number_of_elements = 2D array containing number of + each type of element for each + unstructured model part. + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) ijk_dimensions = 2D array containing ijk dimension info + for structured blocks + + For Z_UNSTRUCTURED - is ignored + + For Z_STRUCTURED or Z_IBLANKED + + Prior to version 2.03: + ---------------------- + (Array will have been allocated + Numparts_available by 3 long) + + ijk_dimensions[][0] = I dimension + ijk_dimensions[][1] = J dimension + ijk_dimensions[][2] = K dimension + + + Starting at version 2.03: + ------------------------ + (Array will have been allocated + Numparts_available by 9 long) + + There are two ways to do this: + ------------------------------ + 1. The simple one, without ranges. + + This is good for all structured models + that will NOT be used in EnSight's + Server of Servers + + Simply provide the ijk dimensions in the + first three slots and place a -1 in + the 4th slot. (The remaining slots will + be ignored). + + Thus, + ijk_dimensions[][0] = I dimension of block + ijk_dimensions[][1] = J dimension of block + ijk_dimensions[][2] = K dimension of block + ijk_dimensions[][3] = -1 + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][4] = -1 + | | | + | | | + 2 *-------*-------* + | | | + | | | + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + + 2. Using ranges. + + This one can be used anytime, but MUST + be used if EnSight's Server of Servers + is to be used! + + The first 3 slots contain the ijk dimension + of the complete block (of which this may be + a portion). The last 6 slots contain the + ijk min and max ranges within the complete. + + Thus, + ijk_dimensions[][0] = I dim of complete block + ijk_dimensions[][1] = J dim of complete block + ijk_dimensions[][2] = K dim of complete block + + ijk_dimensions[][3] = Imin of portion (1-based) + ijk_dimensions[][4] = Imax of portion (1-based) + ijk_dimensions[][5] = Jmin of portion (1-based) + ijk_dimensions[][6] = Jmax of portion (1-based) + ijk_dimensions[][7] = Kmin of portion (1-based) + ijk_dimensions[][8] = Kmax of portion (1-based) + + + example1: (Model has one part, a simple 2D block, + and want whole thing) + + (J planes) + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[0][3] = 1 + | | | ijk_dimension[0][4] = 3 + | | | ijk_dimension[0][5] = 1 + 2 *-------*-------* ijk_dimension[0][6] = 4 + | | | ijk_dimension[0][7] = 1 + | | | ijk_dimension[0][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + example2: (Want to have the block represented + in two portions - 2 parts) + + (J planes) top portion + 4 *-------*-------* + | | | ijk_dimension[0][0] = 3 + | | | ijk_dimension[0][1] = 4 + | | | ijk_dimension[0][2] = 1 + 3 *-------*-------* + . . . ijk_dimension[0][3] = 1 + . . . ijk_dimension[0][4] = 3 + . . . ijk_dimension[0][5] = 3 + 2 ................. ijk_dimension[0][6] = 4 + . . . ijk_dimension[0][7] = 1 + . . . ijk_dimension[0][8] = 1 + . . . + 1 ................. + 1 2 3 (I planes) + + + (J planes) bottom portion + 4 ................. + . . . ijk_dimension[1][0] = 3 + . . . ijk_dimension[2][1] = 4 + . . . ijk_dimension[3][2] = 1 + 3 *-------*-------* + | | | ijk_dimension[1][3] = 1 + | | | ijk_dimension[1][4] = 3 + | | | ijk_dimension[1][5] = 1 + 2 *-------*-------* ijk_dimension[1][6] = 3 + | | | ijk_dimension[1][7] = 1 + | | | ijk_dimension[1][8] = 1 + | | | + 1 *-------*-------* + 1 2 3 (I planes) + + + And note that if you were partioning this block for + EnSight's Server of Servers, you would only have one part, + instead of two. Each SOS server would return its appropriate + ranges in the last 6 slots. The first 3 slots would remain constant. + + + (OUT) iblanking_options = 2D array containing iblanking + options possible for each + structured model part. + ---------- + (Ignored unless Z_IBLANKED type) + + (Array will have been allocated + Numparts_available by 6 long) + + iblanking_options[][Z_EXT] = TRUE if external (outside) + [][Z_INT] = TRUE if internal (inside) + [][Z_BND] = TRUE if boundary + [][Z_INTBND] = TRUE if internal boundary + [][Z_SYM] = TRUE if symmetry surface + + + Notes: + ----- + * If you haven't built a table of pointers to the different parts, + you might want to do so here as you gather the needed info. + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_gold_variable_info + + Description: + ----------- + Get the variable descriptions, types and filenames + + Specification: + ------------- + int USERD_get_gold_variable_info(char **var_description, + char **var_filename, + int *var_type, + int *var_classify, + int *var_complex, + char **var_ifilename, + float *var_freq, + int *var_contran, + int *var_timeset) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) var_description = Variable descriptions + + (Array will have been allocated + Num_variables by Z_BUFL long) + + variable description restrictions: + ---------------------------------- + 1. Only first 19 characters used in EnSight. + 2. Leading and trailing whitespace will be removed by EnSight. + 3. Illegal characters will be replaced by underscores. + 4. Thay may not start with a numeric digit. + 4. No two variables may have the same description. + + + (OUT) var_filename = Variable real filenames + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_type = Variable type + + (Array will have been allocated + Num_variables long) + + types are: Z_CONSTANT + Z_SCALAR + Z_VECTOR + Z_TENSOR + Z_TENSOR9 + + (OUT) var_classify = Variable classification + + (Array will have been allocated + Num_variables long) + + types are: Z_PER_NODE + Z_PER_ELEM + + (OUT) var_complex = TRUE if complex, FALSE otherwise + + (Array will have been allocated + Num_variables long) + + (OUT) var_ifilename = Variable imaginary filenames (if complex) + + (Array will have been allocated + Num_variables by Z_BUFL long) + + (OUT) var_freq = complex frequency (if complex) + + (Array will have been allocated + Num_variables long) + + (OUT) var_contran = TRUE if constant changes per time step + FALSE if constant truly same at all time steps + + (Array will have been allocated + Num_variables long) + + (OUT) var_timeset = Timeset the variable will use (1 based). + (For static models, set it to 1) + + (Array will have been allocated + Num_variables long) + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 or 2 + + + Notes: + ----- + * The implied variable numbers apply, but be aware that the + arrays are zero based. + So for variable 1, will need to provide var_description[0] + var_filename[0] + var_type[0] + var_classify[0] + var_complex[0] + var_ifilename[0] + var_freq[0] + var_contran[0] + var_timeset[0] + + + for variable 2, will need to provide var_description[1] + var_filename[1] + var_type[1] + var_classify[1] + var_complex[1] + var_ifilename[1] + var_freq[1] + var_contran[1] + var_timeset[1] + etc. + + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_block_flag + + Description: + ----------- + Gets whether ghost cells present in block or not + + Specification: + ------------- + int USERD_get_ghosts_in_block_flag(int block_number) + + Returns: + ------- + TRUE if any ghost cells in this structured part + FALSE if no ghost cells in this structured part + + Arguments: + --------- + (IN) block_number = The block part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Notes: + ----- + * This routine is new in the 2.01 API + * This will be based on Current_time_step + + * Intended for structured parts only, value will be ignored for + unstructured parts + + + +-------------------------------------------------------------------- +USERD_get_ghosts_in_model_flag + + Description: + ----------- + Answers the question as to whether any ghost cells in the model. + + Specification: + ------------- + int USERD_get_ghosts_in_model_flag( void ) + + Returns: + ------- + TRUE if any ghost cells in the model + FALSE if no ghost cells in the model + + Arguments: + --------- + + Notes: + ----- + * This routine is new in the 2.01 API + +------------------------------------------------------------------------- +USERD_get_matf_set_info + + Description: + ----------- + Get the material set ids and names + + Specification: + ------------- + int USERD_get_matf_set_info(int *mat_set_ids, + char **mat_set_name) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) mat_set_ids = 1D material set ids array + + (Array will have been allocated + Num_material_sets long) + + (OUT) mat_set_name = 2D material set name array + + (Array will have been allocated + Num_material_sets by Z_BUFL long) + + Notes: + ----- + * Will not be called if Num_material_sets is zero + * See USERD_get_number_of_material_sets header for explanatory example + + +-------------------------------------------------------------------- +USERD_get_matf_var_info + + Description: + ----------- + Gets the material ids and descriptions for the material set + + Specification: + ------------- + int USERD_get_matf_var_info(int set_index, + int *mat_ids, + char **mat_desc) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (OUT) mat_ids[set_index] = 1D integer array containing the material + ids to associated with each material + + (Array will have been allocated + Num_materials[set_index] long) + + (OUT) mat_desc[set_index] = 2D char array containing the material + descriptions to associated with each material + + (Array will have been allocated + Num_materials[set_index] by Z_BUFL long) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_get_maxsize_info + + Description: + ----------- + Gets maximum part sizes for efficient memory allocation. + + Transient models (especially those that increase in size) can cause + reallocations, at time step changes, to keep chewing up more and + more memory. The way to avoid this is to know what the maximum + size of such memory will be, and allocate for this maximum initially. + + Accordingly, if you choose to provide this information (it is optional), + EnSight will take advantage of it. + + + Specification: + ------------- + int USERD_get_maxsize_info(int *max_number_of_nodes, + int *max_number_of_elements[Z_MAXTYPE], + int *max_ijk_dimensions[3]) + + Returns: + ------- + Z_OK if supplying maximum data + Z_ERR if not supplying maximum data, or some error occurred + while trying to obtain it. + + Arguments: + --------- + (OUT) max_number_of_nodes = Maximum number of unstructured nodes + in the part (over all time). + + (Array will have been allocated + Numparts_available long) + + (OUT) max_number_of_elements = 2D array containing maximum number of + each type of element for each + unstructured model part (over all time). + ------------ + Possible types are: + + Z_POINT = point + Z_BAR02 = 2-noded bar + Z_BAR03 = 3-noded bar + Z_TRI03 = 3-noded triangle + Z_TRI06 = 6-noded triangle + Z_QUA04 = 4-noded quadrilateral + Z_QUA08 = 8-noded quadrilateral + Z_TET04 = 4-noded tetrahedron + Z_TET10 = 10-noded tetrahedron + Z_PYR05 = 5-noded pyramid + Z_PYR13 = 13-noded pyramid + Z_PEN06 = 6-noded pentahedron + Z_PEN15 = 15-noded pentahedron + Z_HEX08 = 8-noded hexahedron + Z_HEX20 = 20-noded hexahedron + + Z_G_POINT = ghost node point element + Z_G_BAR02 = 2 node ghost bar + Z_G_BAR03 = 3 node ghost bar + Z_G_TRI03 = 3 node ghost triangle + Z_G_TRI06 = 6 node ghost triangle + Z_G_QUA04 = 4 node ghost quad + Z_G_QUA08 = 8 node ghost quad + Z_G_TET04 = 4 node ghost tetrahedron + Z_G_TET10 = 10 node ghost tetrahedron + Z_G_PYR05 = 5 node ghost pyramid + Z_G_PYR13 = 13 node ghost pyramid + Z_G_PEN06 = 6 node ghost pentahedron + Z_G_PEN15 = 15 node ghost pentahedron + Z_G_HEX08 = 8 node ghost hexahedron + Z_G_HEX20 = 20 node ghost hexahedron + + (Ignored unless Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by + Z_MAXTYPE long) + + (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions + for each structured model part (over all time). + ---------- + (Ignored if Z_UNSTRUCTURED type) + + (Array will have been allocated + Numparts_available by 3 long) + + max_ijk_dimensions[][0] = maximum I dimension + max_ijk_dimensions[][1] = maximum J dimension + max_ijk_dimensions[][2] = maximum K dimension + + Notes: + ----- + * You need to have first called USERD_get_number_of_model_parts and + USERD_get_gold_part_build_info, so Numparts_available is known and + so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED, + or Z_IBLANKED) of each part. + + * This will NOT be based on Current_time_step - it is to be the maximum + values over all time!! + + * This information is optional. If you return Z_ERR, Ensight will still + process things fine, reallocating as needed, etc. However, for + large transient models you will likely use considerably more memory + and take more processing time for the memory reallocations. So, if it + is possible to provide this information "up front", it is recommended + to do so. + + +-------------------------------------------------------------------- +USERD_get_model_extents + + Description: + ----------- + Gets the model bounding box extents. If this routine supplys them + EnSight will not have to spend time doing so. If this routine + returns Z_ERR, EnSight will have to take the time to touch all the + nodes and gather the extent info. + + Specification: + ------------- + int USERD_get_model_extents(float extents[6]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (whereupon EnSight will determine by reading + all coords of all parts) + + Arguments: + --------- + (OUT) extents[0] = min x + [1] = max x + [2] = min y + [3] = max y + [4] = min z + [5] = max z + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_name_of_reader + + Description: + ----------- + Gets the name of your user defined reader. The user interface will + ask for this and include it in the available reader list. + + Specification: + ------------- + int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], + int *two_fields) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) reader_name = the name of the your reader or data format. + (max length is Z_MAX_USERD_NAME, which is 20) + + (OUT) two_fields = FALSE if only one data field is + required. + TRUE if two data fields required + + -1 if one field (Geom) required + and one field (Param) is optional + Param field can contain any text + for example a file name, modifiers, + etc. that can be used to modify the + reader's behavior. + + + Notes: + ----- + * Always called. Please be sure to provide a name for your custom + reader format. + +-------------------------------------------------------------------- +USERD_get_nfaced_conn + + Description: + ----------- + Gets the array containing the connectivity of nsided faces of nfaced elements + + Specification: + -------------int + int USERD_get_nfaced_conn(int part_number, + int *nfaced_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced + elements + + (int array will have been allocated long enough to + hold all the nsided face connectivities. Which is + the sum of all the nodes per face values in the + nfaced_npf_array of USERD_get_nfaced_nodes_per_face) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In USERD_get_faced_nodes_per_face: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In this function: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + +-------------------------------------------------------------------- +USERD_get_nfaced_nodes_per_face - + + Description: + ----------- + Gets the array containing the number of nodes per face for each face + of the nfaced elements. + + Specification: + ------------- + int USERD_get_nfaced_nodes_per_face(int part_number, + int *nfaced_npf_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of + nfaced elements + + (int array will have been allocated long enough + to hold all the nodes_per_face values. Which is + the sum of all the number of faces per element + values in the conn_array of + USERD_get_part_elements_by_type) + + Notes: + ----- + * Will not be called unless there are some nfaced elements in the + the part + + * Providing nfaced information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nfaced + polyhedral elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of faces per nfaced element. (as if connectivity + length of an nfaced element is one) + + 3. In this routine, provide the streamed number of nodes per face + for each of the faces of the nfaced elements. + + + Simple example: 11 10 12 + +--------+-----+ + 2 nfaced elements: /| |\ /| + (1 7-faced / | | \ / | + 1 5-sided) / | | +9 | + / | | /| | + /7 | 8 / | | + +-----------+/ | | | + | |5 | |4 | |6 + | +-----|--+--|--+ + | / | \ | / + | / | \|/3 + | / | + + | / | / + |/1 |2 / + +-----------+/ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NFACED] = 2 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 2 x 1 + for element_type of Z_NFACED: + conn_array[0][0] = 7 (for the 7-faced element) + conn_array[1][0] = 5 (for the 5-faced element) + + == + Sum 12 <---------+ + | + 3. In this routine: | + length of nfaced_npf_array will be: 12 + + nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element) + nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element) + nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element) + nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element) + nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element) + nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element) + nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element) + + nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element) + nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element) + nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element) + nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element) + nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element) + + == + Sum 48 <-------------+ + | + 4. In USERD_get_nfaced_conn: | + length of the nfaced_conn_array will be: 48 + + nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem) + nsided_conn_array[1] = 8 + nsided_conn_array[2] = 9 + nsided_conn_array[3] = 10 + nsided_conn_array[4] = 11 + + nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem) + nsided_conn_array[6] = 5 + nsided_conn_array[7] = 4 + nsided_conn_array[8] = 3 + nsided_conn_array[9] = 2 + + nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem) + nsided_conn_array[11] = 2 + nsided_conn_array[12] = 8 + nsided_conn_array[13] = 7 + + nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem) + nsided_conn_array[15] = 1 + nsided_conn_array[16] = 7 + nsided_conn_array[17] = 11 + + nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem) + nsided_conn_array[19] = 5 + nsided_conn_array[20] = 11 + nsided_conn_array[21] = 10 + + nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced) + nsided_conn_array[23] = 3 + nsided_conn_array[24] = 9 + nsided_conn_array[25] = 8 + + nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced) + nsided_conn_array[27] = 4 + nsided_conn_array[28] = 10 + nsided_conn_array[29] = 9 + + nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem) + nsided_conn_array[32] = 12 + nsided_conn_array[32] = 10 + + nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem) + nsided_conn_array[34] = 4 + nsided_conn_array[35] = 6 + + nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem) + nsided_conn_array[37] = 4 + nsided_conn_array[38] = 10 + nsided_conn_array[39] = 12 + + nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem) + nsided_conn_array[41] = 6 + nsided_conn_array[42] = 12 + nsided_conn_array[43] = 9 + + nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced) + nsided_conn_array[45] = 3 + nsided_conn_array[46] = 9 + nsided_conn_array[47] = 10 + + + + +-------------------------------------------------------------------- +USERD_get_node_label_status + + Description: + ----------- + Answers the question as to whether node labels will be provided. + + Specification: + ------------- + int USERD_get_node_label_status( void ) + + Returns: + ------- + TRUE if node labels will be provided + FALSE if node labels will NOT be provided + + Arguments: + --------- + none + + Notes: + ----- + * Node ids are needed in order to do any node querying, or node + labeling on-screen within EnSight. + + * Prior to API 2.01: + ----------------- + For unstructured parts, you can read them from your file if + available, or can assign them, etc. They need to be unique + per part, and are often unique per model. They must also be + positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + (Unlike API 1.0, where the connectivity of elements had to be + according to the node ids - API 2.0's element connectivities + are not affected either way by the status here.) + + For structured parts, EnSight will assign ids if you return a + status of TRUE here. You cannot assign them yourself!! + + * Starting at API 2.01: + -------------------- + For both unstructured and structured parts, you can read them + from your file if available, or can assign them, etc. They need + to be unique per part, and are often unique per model. They must + also be positive numbers greater than zero. + + USERD_get_part_node_ids is used to obtain the ids, if the + status returned here is TRUE. + + * Will call USERD_get_part_node_ids for each part if this routine + returns TRUE. + +-------------------------------------------------------------------- +USERD_get_nsided_conn - + + Description: + ----------- + Gets the array containing the connectivity of nsided elements + + Specification: + ------------- + int USERD_get_nsided_conn(int part_number, + int *nsided_conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = the part number + + (OUT) nsided_conn_array = 1D array of nsided connectivies + + (int array will have been allocated long enough + to hold all the nsided connectivities. Which is + the sum of all the nodes_per_element values in + the conn_array of USERD_get_part_elements_by_type) + + + Notes: + ----- + * Will not be called unless there are some nsided elements in the the part. + + * Providing nsided information to Ensight: + + 1. In USERD_get_gold_part_build_info, provide the number of nsided + elements in the part. + + 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + the number of nodes per nsided element. (as if connectivity + length of an nsided element is one) + + 3. In this routine, provide the streamed connectivities for each of the + nsided elements. + + + Simple example: 5 6 + +--------+ + 3 nsided elements: /| \ + (1 4-sided / | \ + 1 3-sided / | \ + 1 7-sided) / | \ 7 + /3 |4 + + +-----+ | + | | | + | | |8 + | | + + | | / + | | / + | | / + |1 |2 /9 + +-----+--------+ + + 1. In USERD_get_gold_part_build_info: + number_of_elements[Z_NSIDED] = 3 + . + /|\ + | + 2. In USERD_get_part_elements_by_type: + length of conn_array will be: 3 x 1 + + for element_type of Z_NSIDED: + conn_array[0][0] = 4 (for the 4-sided element) + conn_array[1][0] = 3 (for the 3-sided element) + conn_array[2][0] = 7 (for the 7-sided element) + + Sum === + 14 <---------+ + | + 3. In this routine: | + length of nsided_conn_array will be: 14 + + nsided_conn_array[0] = 1 (connectivity of 4-sided element) + nsided_conn_array[1] = 2 + nsided_conn_array[2] = 4 + nsided_conn_array[3] = 3 + + nsided_conn_array[4] = 3 (connectivity of 3-sided element) + nsided_conn_array[5] = 4 + nsided_conn_array[6] = 5 + + nsided_conn_array[7] = 2 (connectivity of 7-sided element) + nsided_conn_array[8] = 9 + nsided_conn_array[9] = 8 + nsided_conn_array[10] = 7 + nsided_conn_array[11] = 6 + nsided_conn_array[12] = 5 + nsided_conn_array[13] = 4 + + + + +-------------------------------------------------------------------- +USERD_get_num_of_time_steps + + Description: + ----------- + Gets the number of time steps of data available for desired timeset. + + Specification: + ------------- + int USERD_get_num_of_time_steps( int timeset_number ) + + Returns: + ------- + Number of time steps in timeset (>0 if okay, <=0 if problems). + + Arguments: + --------- + (IN) timeset number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + Notes: + ----- + * This should be >= 1 1 indicates a static model + >1 indicates a transient model + + * Num_time_steps[timeset_number] would be set here + + + +-------------------------------------------------------------------- +USERD_get_number_of_files_in_dataset + + Description: + ----------- + Get the total number of files in the dataset. Used for the + dataset query option within EnSight. + + Specification: + ------------- + int USERD_get_number_of_files_in_dataset( void ) + + Returns: + ------- + The total number of files in the dataset. + + Arguments: + --------- + none + + Notes: + ----- + * You can be as complete as you want about this. If you don't + care about the dataset query option, return a value of 0 + If you only want certain files, you can just include them. But, + you will need to supply the info in USERD_get_dataset_query_file_info + for each file you include here. + + * Num_dataset_files would be set here + + +-------------------------------------------------------------------- +USERD_get_number_of_material_sets - + + Description: + ----------- + Get the number of material sets in the model + + Specification: + ------------- + int USERD_get_number_of_material_sets( void ) + + + Returns: + ------- + Num_material_sets = number of material sets + (Zero would indicate that you have no materials + to deal with in the model) + + or + + -1 if an error condition + + Arguments: + --------- + none + + Notes: + ----- + * You may want to keep this as a global for use in other routines. + + ############################################################### + NOTE: For EnSight 7.6, only one material set is supported + within EnSight. + Thus the only valid returns here are: + 0 (no materials) + 1 (for the one material set allowed) + or -1 (if an error) + + If the casefile has more than this, this reader will + read them, but EnSight will issue an error message and + choke on them! + ############################################################### + + ================================================================ + A very simple explanatory example, to use as a reference for the + materials routines: + + Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials. + Most of the model is material 1, but the top left corner is material 9 - + basically as shown: + + + *--------*--------*--------* + | | / | | + | Mat 9 / | | + | | / | | + | |/ | | + | e7 / e8 | e9 | + | /| | | + | / | | | + | / | | | + *----/---*--------*--------* + | / | | | + | / | | | + | / | Mat 1 | + |/ | | | + | e4 | e5 | e6 | + | | | | + | | | | + | | | | + *--------*--------*--------* + | | | | + | | | | + | | | | + | | | | + | e1 | e2 | e3 | + | | | | + | | | | + | | | | + *--------*--------*--------* + + + Thus, in this routine, set: + Num_material_sets = 1 + + In USERD_get_matf_set_info, set: + mat_set_ids[0] = 1 + mat_set_name[0] = "Material Set 1" (or whatever name desired) + + In USERD_get_number_of_materials, input would be set_index = 0, and + would need to set: + Num_materials[0] = 2 + + For simplicity, the ids and descriptions that would be returned in + USERD_get_matf_var_info could be: + mat_ids[0] = 1 + mat_ids[1] = 9 + mat_desc[0] = "mat 1" (or whatever desired) + mat_desc[2] = "mat 9" + + The per element material ids list would need to be: + + material ids: + ------------- + ids_list[0] = 1 (material id 1, for elem e1) + ids_list[1] = 1 ( " e2) + ids_list[2] = 1 ( " e3) + ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4) + ids_list[5] = 1 (material id 1, for elem e5) + ids_list[5] = 1 ( " e6) + ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7) + ids_list[5] = -9 ( " e8) + ids_list[5] = 1 (material id 1, for elem e9) + + Finally we need the mixed material ids list and the mixed materials values list, + which would need to be: + + mixed-material ids: + ------------------- + ==> 1 ids_list[0] = 2 (the -1 in the material variable points here, + 2 indicates that two materials are present) + 2 ids_list[1] = 1 (1st material is 1) + 3 ids_list[2] = 9 (2nd material is 9) + 4 ids_list[3] = -1 (negative of index into mixed-material val_list) + ==> 5 ids_list[4] = 2 (the -5 in the material variable points here, + 2 indicates that two materials are present) + 6 ids_list[5] = 1 (1st material is 1) + 7 ids_list[6] = 9 (2nd material is 9) + 8 ids_list[7] = -3 (negative of index into mixed-material val_list) + ==> 9 ids_list[8] = 2 etc. + 10 ids_list[9] = 1 + 11 ids_list[10] = 9 + 12 ids_list[11] = -5 + + mixed-material values: + ---------------------- + ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here, + and this is the value for material 1) + 2 val_list[1] = 0.125 (the value for material 9) + ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here) + 4 val_list[3] = 0.875 + ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here) + 6 val_list[5] = 0.125 + + So, USERD_size_matf_data would need to return + matf_size = 8, when called with set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX + + matf_size = 12, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX + + = 6, when called with set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE + + And, USERD_load_matf_data would need to return: + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + wtyp = Z_QUA04 + mat_type = Z_MAT_INDEX (indicating id list). + + the int array ids_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_INDEX (indicating id list). + + the float array val_list as shown above when called with: + set_id = 1 + part_id = 1 + mat_type = Z_MIX_VALUE (indicating val list). + + +------------------------------------------------------------------------- +USERD_get_number_of_materials + + Description: + ----------- + Gets the number of materials in the material set + + Specification: + ------------- + int USERD_get_number_of_materials( int set_index ) + + Returns: + ------- + Num_materials[set_index] = Number of materials in the set + 0 indicates no materials information present + -1 indicates an error + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero + * You may want to keep this as a global for use in other routines. + + + +-------------------------------------------------------------------- +USERD_get_number_of_model_parts + + Description: + ----------- + Gets the total number of unstructured and structured parts + in the model, for which you can supply information. + + Specification: + ------------- + int USERD_get_number_of_model_parts( void ) + + Returns: + ------- + Number of parts (>0 if okay, <=0 if problems). + + Arguments: + --------- + none + + Notes: + ----- + * If going to have to read down through the parts in order to + know how many, you may want to build a table of pointers to + the various parts, so you can easily get to particular parts in + later processes. If you can simply read the number of parts + at the head of the file, then you would probably not build the + table at this time. + + * This routine would set Numparts_available, which is equal to + Num_unstructured_parts + Num_structured_blocks. + + + +-------------------------------------------------------------------- +USERD_get_number_of_timesets + + Description: + ----------- + Gets the number of timesets used in the model. + + Specification: + ------------- + int USERD_get_number_of_timesets( void ) + + Returns: + ------- + Number of timesets in the model + + Arguments: + --------- + none + + Notes: + ----- + * Num_timesets would be set here + + * If you have a static model, both geometry and variables, you should + return a value of zero. + + * If you have a transient model, then you should return one or more. + + For example: + + Geometry Variables No. of timesets + --------- ------------------------------ --------------- + static static 0 + static transient, all using same timeset 1 + + transient transient, all using same timeset as geom 1 + + static transient, using 3 different timesets 3 + + transient transient, using 3 different timesets and + none of them the same as the + geometry timeset 4 + etc. + + NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide + the timeset number to use + for geometry in: + USERD_get_geom_timeset_number + + Variables can use the same timeset as the geometry, or can use + other timesets. More than one variable can use the same timeset. + + example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0 + variable 1 provided at these same five steps + variable 2 provided at 3 steps, 0.5, 1.25, 3.33 + + This routine should return a value of 2, because only + two different timesets are needed. Timeset 1 would be for the + geometry and variable 1 (they both use it). Timeset 2 would + be for variable 2, which needs its own in this case. + + + + + +-------------------------------------------------------------------- +USERD_get_number_of_variables + + Description: + ----------- + Get the number of variables for which you will be providing info. + + Specification: + ------------- + int USERD_get_number_of_variables( void ) + + Returns: + ------- + Number of variables (includes constant, scalar, vector and tensor types) + (>=0 if okay, <0 if problem) + + Arguments: + --------- + none + + Notes: + ----- + ***************************************************************** + * Variable numbers, by which references will be made, are implied + here. If you say there are 3 variables, the variable numbers + will be 1, 2, and 3. + ***************************************************************** + + * Num_variables would be set here + + + +-------------------------------------------------------------------- +USERD_get_part_coords + + Description: + ----------- + Gets the coordinates for an unstructured part. + + Specification: + ------------- + int USERD_get_part_coords(int part_number, float **coord_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) coord_array = 2D float array which contains, + x,y,z coordinates of each node + in the part. + + (IMPORTANT: The second dimension of this aray is 1-based!!!) + + (Array will have been allocated + 3 by (number_of_nodes + 1) for the part + long - see USERD_get_gold_part_build_info) + + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + coord_array[3][101] + + Ignore the coord_array[0][0] + coord_array[1][0] + coord_array[2][0] locations and start + the node coordinates at: + coord_array[0][1] + coord_array[1][1] + coord_array[2][1] + + coord_array[0][2] + coord_array[1][2] + coord_array[2][2] + + etc. + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_element_ids_by_type + + Description: + ----------- + Gets the ids for the elements of a particular type for an unstructured + or structured part. + + Specification: + ------------- + int USERD_get_part_element_ids_by_type(int part_number, + int element_type, + int *elemid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (OUT) elemid_array = 1D array containing id of each + element of the type. + + (Array will have been allocated + number_of_elements of the type long) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25] when called with Z_TRI03 + + conn_array[100] when called with Z_QUA04 + + conn_array[30] when called with Z_HEX08 + + Notes: + ----- + * Not called unless element label status is set to TRUE in + USERD_get_element_label_status + + * Will be based on Current_time_step + + + +-------------------------------------------------------------------- +USERD_get_part_elements_by_type + + Description: + ----------- + Gets the connectivities for the elements of a particular type in an + unstructured part + + Specification: + ------------- + int USERD_get_part_elements_by_type(int part_number, + int element_type, + int **conn_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (IN) element_type = One of the following (See global_extern.h) + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + + (OUT) conn_array = 2D array containing connectivity + of each element of the type. + + (Array will have been allocated + num_of_elements of the type by + connectivity length of the type) + + ex) If number_of_elements[Z_TRI03] = 25 + number_of_elements[Z_QUA04] = 100 + number_of_elements[Z_HEX08] = 30 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions available + for this routine will be: + conn_array[25][3] when called with Z_TRI03 + + conn_array[100][4] when called with Z_QUA04 + + conn_array[30][8] when called with Z_HEX08 + + Notes: + ----- + * Not called unless Num_unstructured_parts is > 0 + + * Will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_get_part_node_ids + + Description: + ----------- + Gets the node ids of an unstructured or structured part. + + Specification: + ------------- + int USERD_get_part_node_ids(int part_number, int *nodeid_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) part_number = The part number + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) nodeid_array = 1D array containing node ids of + each node in the part. + + (IMPORTANT: This array is 1-based!!!) + + (Array will have been allocated + (number_of_nodes + 1) for the part long + see USERD_get_gold_part_build_info) + + ex) If number_of_nodes = 100 + as obtained in: + USERD_get_gold_part_build_info + + Then the allocated dimensions of the + pointer sent to this routine will be: + nodeid_array[101] + + Ignore the nodeid_array[0] location and start + the node ids at: + nodeid_array[1] + + nodeid_array[2] + + etc. + + Notes: + ----- + * Not called unless node label status is TRUE, as returned from + USERD_get_node_label_status + + * Will be based on Current_time_step + + * The ids are purely labels, used when displaying or querying node ids. + However, any node id < 0 will never be displayed + + +-------------------------------------------------------------------- +USERD_get_reader_descrip + + Description: + ----------- + Gets the description of the reader, so gui can give more info + + Specification: + ------------- + int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) descrip = the description of the reader (max length is MAXFILENP, + which is 255) + + Notes: + ----- + * OPTIONAL ROUTINE! You can have it or not. + + + +-------------------------------------------------------------------- +USERD_get_reader_version + + Description: + ----------- + Gets the version number of the user defined reader + + Specification: + ------------- + int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful (and will assume is version 1.0) + + Arguments: + --------- + (OUT) version_number = the version number of the reader + (max length is Z_MAX_USERD_NAME, which + is 20) + + Notes: + ----- + * This needs to be "2.000" or greater. Otherwise EnSight will assume + this reader is API 1.0 + + * should set it to "2.010" for this version of the API + + + + +-------------------------------------------------------------------- +USERD_get_sol_times + + Description: + ----------- + Get the solution times associated with each time step for + desired timeset. + + Specification: + ------------- + int USERD_get_sol_times(int timeset_number, + float *solution_times) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) solution_times = 1D array of solution times per time step + + (Array will have been allocated + Num_time_steps[timeset_number] long) + + Notes: + ----- + * The solution times must be non-negative and increasing. + + + +-------------------------------------------------------------------- +USERD_get_timeset_description - + + Description: + ----------- + Get the description to associate with the desired timeset. + + Specification: + ------------- + int USERD_get_timeset_description(int timeset_number, + char timeset_description[Z_BUFL]) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) timeset_number = the timeset number + + For example: If USERD_get_number_of_timesets + returns 2, the valid + timeset_number's would be 1 and 2 + + (OUT) timeset_description = timeset description string + + + Notes: + ----- + * A string of NULLs is valid for timeset_description + + + + +-------------------------------------------------------------------- +USERD_get_var_by_component + + Description: + ----------- + Gets the values of a variable component. Both unstructured and structured + parts use this routine. + + if Z_PER_NODE: + Get the component value at each node for a given variable in the part. + + or if Z_PER_ELEM: + Get the component value at each element of a specific part and type + for a given variable. + + Specification: + ------------- + int USERD_get_var_by_component(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + or: Z_UNDEF, in which case you need not load any values into var_array + + + Arguments: + --------- + (IN) which_variable = The variable number + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + (IN) var_type = Z_SCALAR + Z_VECTOR + Z_TENSOR (symmetric tensor) + Z_TENSOR9 (asymmetric tensor) + + (IN) which_type + + if Z_PER_NODE: Not used + + if Z_PER_ELEM: = The element type + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + + (IN) imag_data = TRUE if imag component + FALSE if real component + + (IN) component = The component: (0 if Z_SCALAR) + (0 - 2 if Z_VECTOR) + (0 - 5 if Z_TENSOR) + (0 - 8 if Z_TENSOR9) + + * 6 Symmetric Indicies, 0:5 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 22 23 | = | 1 5 | * + * | | | | * + * | 33 | | 2 | * + + + * 9 General Indicies, 0:8 * + * ---------------------------- * + * | 11 12 13 | | 0 3 4 | * + * | | | | * + * T = | 21 22 23 | = | 6 1 5 | * + * | | | | * + * | 31 32 33 | | 7 8 2 | * + + (OUT) var_array + + ----------------------------------------------------------------------- + (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!) + ----------------------------------------------------------------------- + + if Z_PER_NODE: = 1D array containing variable component value + for each node. + + (Array will have been allocated + (number_of_nodes + 1) long) + + Info stored in this fashion: + var_array[0] = not used + var_array[1] = var component for node 1 of part + var_array[2] = var_component for node 2 of part + var_array[3] = var_component for node 3 of part + etc. + + if Z_PER_ELEM: = 1D array containing variable component + value for each element of a particular + part and type. + + (Array will have been allocated + (number_of_elements[which_part][which_type] + 1) + long. See USERD_get_gold_part_build_info) + + Info stored in this fashion: + var_array[1] = var component for elem 1 (of part and type) + var_array[2] = var component for elem 2 (of part and type) + var_array[3] = var component for elem 3 (of part and type) + etc. + + Notes: + ----- + * Not called unless Num_variables is > 0 + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * Will be based on Current_time_step + + * If the variable is not defined for this part, simply return with a + value of Z_UNDEF. EnSight will treat the variable as undefined for + this part. + + +-------------------------------------------------------------------- +USERD_get_var_value_at_specific + + Description: + ----------- + if Z_PER_NODE: + Get the value of a particular variable at a particular node in a + particular part at a particular time. + + or if Z_PER_ELEM: + Get the value of a particular variable at a particular element of + a particular type in a particular part at a particular time. + + + Specification: + ------------- + int USERD_get_var_value_at_specific(int which_var, + int which_node_or_elem, + int which_part, + int which_elem_type, + int time_step, + float values[3], + int imag_data) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) which_var = The variable number + + (IN) which_node_or_elem + + If Z_PER_NODE: + = The node number. This is not the id, but is + the index of the global node + list (1 based), or the block's + node list (1 based). + + Thus, coord_array[1] + coord_array[2] + coord_array[3] + . | + . |which_node_or_elem index + . ---- + + + If Z_PER_ELEM: + = The element number. This is not the id, but is + the element number index + of the number_of_element array + (see USERD_get_gold_part_build_info), + or the block's element list (1 based). + + Thus, for which_part: + conn_array[which_elem_type][0] + conn_array[which_elem_type][1] + conn_array[which_elem_type][2] + . | + . which_node_or_elem index + . ---- + + + (IN) which_part Since EnSight Version 7.4 + ------------------------- + = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + Prior to EnSight Version 7.4 + ---------------------------- + = The part id This is the part_id label loaded + in USERD_get_gold_part_build_info. + It is NOT the part table index. + + + (IN) which_elem_type + + If Z_PER_NODE, or block part: + = Not used + + If Z_PER_ELEM: + = The element type. This is the element type index + of the number_of_element array + (see USERD_get_gold_part_build_info) + + (IN) time_step = The time step + + (IN) imag_data = TRUE if want imaginary value. + FALSE if want real value. + + (OUT) values = scalar or vector component value(s) + values[0] = scalar or vector[0] + values[1] = vector[1] + values[2] = vector[2] + + + Notes: + ----- + * This routine is used in node querys over time (or element querys over + time for Z_PER_ELEM variables). If these operations are not critical + to you, this can be a dummy routine. + + * The per_node or per_elem classification must be obtainable from the + variable number (a var_classify array needs to be retained) + + * The time step given is for the proper variable timeset. + + +---------------------------------------------------------------------- +USERD_load_matf_data + + Description: + ----------- + Get the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_load_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *ids_list, + float *val_list) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) ids_list = If mat_type is Z_MAT_INDEX: + --------------------------- + 1D material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MAT_INDEX) + + If mat_type is Z_MIX_INDEX: + --------------------------- + 1D mixed-material id list + (Int array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_INDEX) + + (OUT) val_list = 1D mixed-materials values list + (only used if mat_type is Z_MIX_VALUE) + + (Float array will have been allocated + the appropriate size, as returned in + USERD_size_matf_data for mat_type Z_MIX_VALUE) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, + or Num_materials[set_index] is zero, + or the appropriate size from USERD_size_matf_data is zero + + + +-------------------------------------------------------------------- +USERD_set_filenames + + Description: + ----------- + Receives the geometry and result filenames entered in the data + dialog. The user written code will have to store and use these + as needed. The user written code must manage its own files!! + + Specification: + ------------- + int USERD_set_filenames(char filename_1[], + char filename_2[], + char the_path[], + int swapbytes) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) filename_1 = the filename entered into the geometry + field of the data dialog. + + (IN) param_2 = The usage of this string depends on + 'two_fields' in USERD_get_name_of_reader. + + If two_fields is FALSE then it's empty. + + If two_fields is TRUE, this is the + manditory results file entered + into the result field of the data dialog. + + If two_fields is -1, then this contains + optional text (filenames, modifiers, etc.) + that can be parsed and used to modify + reader + + (IN) the_path = the path info from the data dialog. + Note: filename_1 and filename_2 have already + had the path prepended to them. This + is provided in case it is needed for + filenames contained in one of the files + + (IN) swapbytes = TRUE if should swap bytes when reading data. + = FALSE normally. + + Notes: + ----- + * Since you must manage everything from the input that is entered in + these data dialog fields, this is an important routine! + + * It may be that you will need to have an executive type file that contains + info and other filenames within it, like EnSight6's case file. + + +-------------------------------------------------------------------- +USERD_set_server_number + + Description: + ----------- + Receives the server number of how many total servers. + + Specification: + ------------- + int USERD_set_server_number(int cur_serv, + int tot_servs) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) cur_serv = the current server. + + (IN) tot_servs = the total number of servers. + + Notes: + ----- + * Only useful if your user defined reader is being used with EnSight's + Server-of-Server capability. And even then, it may or may not be + something that you can take advantage of. If your data is already + partitioned in some manner, such that you can access the proper + portions using this information. + + For all non-SOS uses, this will simply be 1 of 1 + + + +-------------------------------------------------------------------- +USERD_set_time_set_and_step + + Description: + ----------- + Set the current time step in the desired timeset. All functions that + need time, and that do not explicitly pass it in, will use the timeset + and step set by this routine, if needed. + + Specification: + ------------- + void USERD_set_time_set_and_step(int timeset_number, + int time_step) + + Returns: + ------- + nothing + + Arguments: + --------- + (IN) timeset_number = the timeset number (1 based). + + For example: If USERD_get_number_of_timesets + returns 2, the valid timeset_number's + would be 1 and 2. + + (IN) time_step = The current time step to set + + Notes: + ----- + * Current_time_step and Current_timeset would be set here + + +-------------------------------------------------------------------- +USERD_size_matf_data + + Description: + ----------- + Get the length of the material id list, mixed-material id list, or + mixed-material values list for the given material set and part (and + element type if material id list) + + Specification: + ------------- + int USERD_size_matf_data( int set_index, + int part_id, + int wtyp, + int mat_type, + int *matf_size) + + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (IN) set_index = the material set index (zero based) + + (IN) part_id = the part number desired + + (IN) wtyp = the element type (used for Z_MAT_INDEX only) + + Z_POINT node point element + Z_BAR02 2 node bar + Z_BAR03 3 node bar + Z_TRI03 3 node triangle + Z_TRI06 6 node triangle + Z_QUA04 4 node quad + Z_QUA08 8 node quad + Z_TET04 4 node tetrahedron + Z_TET10 10 node tetrahedron + Z_PYR05 5 node pyramid + Z_PYR13 13 node pyramid + Z_PEN06 6 node pentahedron + Z_PEN15 15 node pentahedron + Z_HEX08 8 node hexahedron + Z_HEX20 20 node hexahedron + Z_NSIDED nsided polygon + Z_NFACED nfaced polyhedron + + Z_G_POINT ghost node point element + Z_G_BAR02 2 node ghost bar + Z_G_BAR03 3 node ghost bar + Z_G_TRI03 3 node ghost triangle + Z_G_TRI06 6 node ghost triangle + Z_G_QUA04 4 node ghost quad + Z_G_QUA08 8 node ghost quad + Z_G_TET04 4 node ghost tetrahedron + Z_G_TET10 10 node ghost tetrahedron + Z_G_PYR05 5 node ghost pyramid + Z_G_PYR13 13 node ghost pyramid + Z_G_PEN06 6 node ghost pentahedron + Z_G_PEN15 15 node ghost pentahedron + Z_G_HEX08 8 node ghost hexahedron + Z_G_HEX20 20 node ghost hexahedron + Z_G_NSIDED ghost nsided polygon + Z_G_NFACED ghost nfaced polyhedron + + (IN) mat_type = Z_MAT_INDEX for material ids list + Z_MIX_INDEX for mixed-material ids list + Z_MIX_VALUE for mixed-material values list + + (OUT) matf_size = the length of the material id list, or + mixed-material id list, or + mixed-material values list + for the given material set and part number + (and element type if Z_MAT_INDEX) + + Notes: + ----- + * See USERD_get_number_of_material_sets header for explanatory example + * Will not be called if Num_material_sets is zero, or + Num_materials[set_index] is zero + + + + +-------------------------------------------------------------------- +USERD_stop_part_building + + Description: + ----------- + This routine called when the part building dialog is closed. It is + provided in case you desire to release memory, etc. that was only needed + during the part building process. + + Specification: + ------------- + void USERD_stop_part_building( void ) + + Returns: + ------- + nothing + + Arguments: + --------- + none + + Notes: + ----- + +-------------------------------------------------------------------- +USERD_rigidbody_existence + + Description: + ----------- + Gets the existence of rigid body values or not in the model + + Specification: + ------------- + int USERD_rigidbody_existence( void ) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + none + + Notes: + ----- + * This will be based on Current_time_step + + +-------------------------------------------------------------------- +USERD_rigidbody_values + + Description: + ----------- + Gets the rigid body values for each part + + Specification: + ------------- + int USERD_rigidbody_values(int part_number, + float values[14]) + + Returns: + ------- + Z_OK if rigid body values exist for the model + Z_UNDEF if no rigid body values exist + Z_ERR if an error + + Arguments: + --------- + (IN) part_number = The part number + + (1-based index of part table, namely: + + 1 ... Numparts_available. + + It is NOT the part_id that + is loaded in USERD_get_gold_part_build_info) + + (OUT) values values[0] = IX (x location) + values[1] = IY (y location) + values[2] = IZ (z location) + values[3] = E0 (e0 euler value) + values[4] = E1 (e1 euler value) + values[5] = E2 (e2 euler value) + values[6] = E3 (e3 euler value) + + The next 3 are for an optional cg offset. If none is + needed or desired (namely the first 7 values above + contain all that is needed), then these should be + set to 0.0 + + values[7] = xoff (initial cg x offset) + values[8] = yoff (initial cg y offset) + values[9] = z0ff (initial cg z offset) + + The next 4 values are for and optional initial yaw, pitch, roll + operation. This is useful to get parts from one + standard layout to a different standard layout. + (example, flex body parts computed in an axis system + different than that of rigid body parts manipulation) + If not needed or desired, set these to 0.0 + + values[10] = rot_order (order the roations are applied + 0.0 = no rotations + 1.0 = xyz order + 2.0 = xzy order + 3.0 = yxz order + 4.0 = yzx order + 5.0 = zxy order + 6.0 = zyx order) + values[11] = xrot (initial x rotation - degrees) + values[12] = yrot (initial y rotation - degrees) + values[13] = zrot (initial z rotation - degrees) + + Notes: + ----- + * This will be based on Current_time_step + * It will not be called unless USERD_rigidbody_existence indicates + that there are some values in the model by returning Z_OK. + * Order that transformations will be applied is: + 1. The yaw,pitch,roll rotations, if present (values[11] through values[13] + in the order specified in rot_order, values[10]) + 2. The cg offsets, if present (values[7] through values[9]) + 3. The euler parameter rotations (values[3] through values[6]) + 4. The translations (values[0] through values[2]) + +-------------------------------------------------------------------- +USERD_set_right_side + + Description: + ----------- + Informs the reader that the time currently set is the right side of a time + span used for variable interpolation between time steps + + Specification: + ------------- + void USERD_set_right_side( void ) + + Returns: + ------- + + Arguments: + --------- + none + + Notes: + ----- + * Applies to Current_time_step + + + + + +------------------------------------------------------------------ + ENHANCED GUI ROUTINES + +-------------------------------------------------------------------- +USERD_get_extra_gui_numbers + + Description: + ----------- + The Enhanced GUI routines are added to allow + the user to customize a portion of the Data + Reader dialog to pass in options to their + user defined reader. + + Specification: + ------------- + void USERD__get_extra_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_extra_gui_numbers + USERD_get_extra_gui_defaults + USERD_set_extra_gui_data + + The existence of these routine indicates that + you wish to add customize entries to the + Data Reader dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_extra_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_extra_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_extra_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_extra_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_extra_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_extra_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_numbers + + Description: + ----------- + The Var_Extract_GUI routines are added to allow + the user to customize a extraction parameters + for variables "after" the file has been read. + These things can be modified and the variables will + be update/refreshed according to the new parameters set + + Specification: + ------------- + void USERD_get_var_extract_gui_numbers(int *num_Toggles, + int *num_pulldowns, + int *num_fields) + + + Returns: + ------- + + Arguments: + --------- + (OUT) num_Toggles = number of toggles that will be provided + + num_pulldowns = number of pulldowns that will be provided + + num_fields = number of fields that will be provided + + Notes: + ----- + There are three routines that work together: + USERD_get_var_extract_gui_numbers + USERD_get_var_extract_gui_defaults (this one) + USERD_set_var_extract_gui_data + + The existence of these routine indicates that + you wish to have the Var Extract Parameters dialog. + + If you don't want the extra GUI features, + simply delete these routines, or change their + names to something such as + USERD_DISABLED_get_var_extract_gui_defaults + + The presence of these routines + will ensure that EnSight will call them and + use their data to modify the extraction parameters set + with some or all of the following: + toggles, pulldown menu and fields. + + The user can then interact with the enhanced + GUI and then send their choices to + USERD_set_extra_gui_data + + Therefore if USERD_get_var_extract_gui_numbers + exists then the other two must exist. + + If none exist, then the GUI will be unchanged. + + Toggle data will return an integer + TRUE if checked + FALSE if unchecked + + Pulldown menu will return an integer representing + the menu item selected + + Field will return a string Z_LEN_GUI_FIELD_STR long. + + If all the enhanced GUI features are enabled it + might look something like this + + =================================================== + [] Title 1 [X] Title 3 + [X]Title 2 [X] Title 4 + + Pulldown Menu -> + Menu Choice 1 + Menu Choice 2 + Menu Choice 3 + + Data Field Title 1 ____________________________ + + Data Field Title 2 ____________________________ + ===================================================== + + This routine defines the numbers of toggles, pulldowns & fields + + The following are defined in the global_extern.h + Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns + Z_LEN_GUI_PULL_STR max length of GUI pulldown string + Z_LEN_GUI_FIELD_STR max length of field string + Z_LEN_GUI_TITLE_STR max length of title string + + The library is loaded, this routine is + called, then the library is unloaded. + + Do not define globals in this routine + as when the library is unloaded, you'll + lose them. + + +-------------------------------------------------------------------- +USERD_get_var_extract_gui_defaults + + Description: + ----------- + This routine defines the Titles, status, + List choices, strings, etc that are fed + up to the GUI. + + Specification: + ------------- + int USERD_get_var_extract_gui_defaults(char **toggle_Title, + int *toggle_default_status, + char **pulldown_Title, + int *pulldown_number_in_list, + int *pulldown_default_selection, + char ***pulldown_item_strings, + char **field_Title, + char **field_user_string) + + Returns: + ------- + Z_OK if successful + Z_ERR if not successful + + Arguments: + --------- + (OUT) toggle_Title = title for each toggle + array dimension is [num_toggles] by + [Z_LEN_GUI_TITLE_STR] long + + toggle_default_status = Setting for each toggle (TRUE or FALSE) + array dimension is [num_toggles] long + + pulldown_Title = title for each pulldown + array dimension is [num_pulldowns] by + [Z_LEN_GUI_TITLE_STR] long + + pulldown_number_in_list = number of items in each pulldown + array dimension is [num_pulldowns] long + + pulldown_default_selection = pulldown item selection for each pulldown + array dimension is [num_pulldowns] long + + pulldown_item_strings = pulldown item strings + array is [num_pulldowns] by + [Z_MAX_NUM_GUI_PULL_ITEMS] by + [Z_LEN_GUI_PULL_STR] long + + field_Title = title for each field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + field_user_string = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + + Notes: + ----- + * The library is loaded, this routine is called, then the library is unloaded. + + * Do not define globals in this routine as when the library is unloaded, you'll + lose them. + + + +-------------------------------------------------------------------- +USERD_set_var_extract_gui_data + + Description: + ----------- + This routine sets the new values for the toggles, pulldowns, and fields. + + Specification: + ------------- + void USERD_set_var_extract_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/) + + Returns: + ------- + + Arguments: + --------- + (IN) toggle = setting for each toggle. TRUE or FALSE + array dimension is [num_toggles] long + + pulldown = item chosen in each pulldown. (0 based) + array dimension is [num_pulldowns] long + + field_text = content of the field + array dimension is [num_fields] by + [Z_LEN_GUI_TITLE_STR] long + + + Notes: + ----- + * This routine is called when the library is permanently + loaded to the EnSight session, so define your globals + in this and later routines. + + * It's up to you to change your reader behavior according to + user entries! + + + + + +----------------------------------------------------------------------------------- +/* ---------------------------------------------------------- + * New in EnSight 8 is the capability to remove (fail) elements + * based on variable threshold values. Basically the variable + * name, a couple of thresholds, a couple of values and a logic + * criteria are read in from this routine. Every element that + * satisfies the failure criteria is removed and not used in + * EnSight calculations. + * + * Example Failure criteria + * Let fail_var_name = "fail_flag" + * threshold_val1 = 0 + * threshold_operator1 = Z_EQUAL_TO + * logic_criteria2 not used + * threshold_val2 not used + * threshold_operator2 not used + * For each value of "fail_flag" at each element, + * if fail flag == threshold_val1 (0.0) then element fails + * Return (Z_ERR) if this is not used. + * Return (Z_OK) if failed element feature should be used + * + * threshold_operator1 & 2 can be one of the following + * Z_ELE_FAILED_NONE, - disables checking + * Z_ELE_FAILED_GREATER, - greater than + * Z_ELE_FAILED_LESS, - less than + * Z_ELE_FAILED_EQUAL, - equal + * Z_ELE_FAILED_NOT_EQUAL, - not equal + * Z_ELE_FAILED_MANY - not used + * + * logic_criteria2 + * Z_ELE_FAILED_LOGIC_NONE, + * Z_ELE_FAILED_LOGIC_AND, + * Z_ELE_FAILED_LOGIC_OR, + * Z_ELE_FAILED_LOGIC_MANY + * + * ---------------------------------------------------------- */ +int USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + +/*-------------------------------------------------------------------- + * USERD_get_structured_reader_cinching - + *-------------------------------------------------------------------- + * + * Gets whether this reader will do structured cinching for block data + * This means that it will handle the min, max, and step values for a + * given block and return the coordinate components or variable components + * in their "cinched" state when partial extraction or striding is used. + * This is as opposed to returning the entire component (ignoring min, max + * and stride) and letting Ensight pick out the values actually used. + * + * returns: Z_OK if the reader will handle the + * min, max, and stride and return + * the cinched values only. + * + * Z_UNDEF or Z_ERR if will return entire component + * and rely on EnSight to cinch. + * + * Notes: + * Unless you can actually pull out the desired min, max, and stride + * without using a full component of memory, don't enable this feature. + *--------------------------------------------------------------------*/ +int +USERD_get_structured_reader_cinching( void ) + + + +/*-------------------------------------------------------------------- + * USERD_set_block_range_and_stride - + *-------------------------------------------------------------------- + * + * Sets the min, max, and step values in each of the i, j, and k, directions + * for the given part. + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in + * USERD_get_gold_part_build_info) + * + * (IN) mini = min i plane desired (zero based) + * maxi = max i plane desired (zero based) + * stepi = i stride + * minj = min j plane desired (zero based) + * maxj = max j plane desired (zero based) + * stepj = j stride + * mink = min k plane desired (zero based) + * maxk = max k plane desired (zero based) + * stepk = k stride + * + * + * returns: Z_OK if no problems + * Z_ERR if an error + * + * Notes: + * * It will not be called unless USERD_get_structured_reader_cinching + * indicates that this reader does structured cinching by returning + * a Z_OK. + * + * * It will actually be called before each geom component and before + * each part variable - so if you are storing things locally, you should + * make this routine be able to quickly check whether anything needs + * updated or not. + * + * * If the stride (step) does not hit right on the max, the last element + * in each direction will be shortened appropriately. + * For example, if a block had 0 to 12 in the i direction, + * and the user specified min = 1 + * max = 8 + * step = 3 + * + * 0 1 2 3 4 5 6 7 8 9 10 11 12 + * | | | | | | | | | | | | | + * + * | | | | + * + * Namely, the coarser cell boundaries in this direction would be at 1, 4, +7, and 8 + * + *--------------------------------------------------------------------*/ +int +USERD_set_block_range_and_stride(int part_number, + int mini, int maxi, int stepi, + int minj, int maxj, int stepj, + int mink, int maxk, int stepk) + + + +---- end of document ---- diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_IN_BUFFERS b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_IN_BUFFERS new file mode 100644 index 0000000000..8b80e6a645 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/README_USERD_IN_BUFFERS @@ -0,0 +1,1447 @@ +README_USERD_IN_BUFFERS +======================== +Five optional routines for normal elements, + + USERD_get_part_coords_in_buffers | + USERD_get_part_node_ids_in_buffers | + USERD_get_part_elements_by_type_in_buffers |If any of these are implemented, + USERD_get_part_element_ids_by_type_in_buffers |all 5 of them must be implemented + USERD_get_var_by_component_in_buffers | + + + +one optional routine for nsided elements, + + USERD_get_nsided_conn_in_buffers + + + +and one optional routine for nfaced elements, + + USERD_get_nfaced_conn_in_buffers + + +can be added into any API 2.* reader to be used by the +Unstructured Auto Distribute capability in EnSight 8.2 and later. + +Unstructured Auto Distribute is a capability requiring Server of Servers (SOS) +that will partition an unstructured model for you automatically across a set of +servers. + +If you do not implement the routines listed above (and described below) in your +reader, EnSight can still perform this operation but will require much more memory on +each server to read in the data (somewhat like each server having to read the +whole model). You will however, get the execution advantage of having your model +partitioned across multiple servers. + +If you do implement these routines in your reader (in a proper manner), you +should be able to not only get the execution advantages, but also memory usage +on each server which is proportional to the subset that it is assigned to deal with. + + +Note that the optional routines are functionally quite similar +to the following functions. And thus their implementation should +not be too difficult to add to any existing reader that has already +implemented these: +------------------------------------------ +USERD_get_part_coords +USERD_get_part_node_ids +USERD_get_part_elements_by_type +USERD_get_part_element_ids_by_type +USERD_get_var_by_component + +USERD_get_nsided_conn + +USERD_get_nfaced_conn + + + +Routine Details: +================ + +/*-------------------------------------------------------------------- + * USERD_get_part_coords_in_buffers - + *-------------------------------------------------------------------- + * + * Get the coordinates for an unstructured part in buffers. + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, get to + * the correct starting spot, initialize, etc. + * + * (IN) n_beg = Zero based, first node index + * of the buffered set + * + * (IN) n_end = Zero based, last node index + * of the buffered set + * + * Thus, for first five nodes: + * n_beg = 0 + * n_end = 4 + * total_number = (n_end - n_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five nodes, would be: + * n_beg = 5 + * n_end = 9 + * total_number = (n_end - n_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all nodes of a part, would be: + * n_beg = 0 + * n_end = num_nodes - 1 + * + * (IN) buffer_size = The size of the buffer. + * Namely: coord_array[3][buffer_size] + * + * (OUT) coord_array = 2D float buffer array which is set up to hold + * x,y,z coordinates of nodes. + * + * (IMPORTANT: the second dimension of of this array is 0-based!!!) + * + * (IMPORTANT: in the sister routine (USERD_get_part_coords) - which + * does not use buffers. This array is 1-based. So pay attention.) + * + * (Array will have been allocated + * 3 by buffer_size long + * + * Example, if we had a part with 645 nodes and the buffer size was set to 200 + * + * first invocation: + * first = TRUE Will be TRUE the first time! + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * coord_array[3][200] fill with values for nodes 1 - 200 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * second invocation: which occurs because we returned a 0 last time + * first = FALSE will now be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * coord_array[3][200] fill with values for nodes 201 - 400 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * third invocation: which occurs because we returned a 0 last time + * first = FALSE will still be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * coord_array[3][200] fill with values for nodes 401 - 600 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * fourth invocation: which occurs because we returned a 0 last time + * first = FALSE will still be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * coord_array[3][200] fill with values for nodes 601 - 645 (zero-based) + * *num_returned = 45 set this + * return(1) return this (indicates done!) + * + * (OUT) *num_returned = The number of nodes whose coordinates are returned + * in the buffer. This will normally be equal to + * buffer_size except for that last buffer - + * which could be less than a full buffer. + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Not called unless number_of_nodes for the part > 0 + * + * * Again, make sure each buffer is zero based. For our example above: + * + * Invocation: + * 1 2 3 4 + * ------- ------- -------- ------- + * coord_array[0][0] x for node 1 node 201 node 401 node 601 + * coord_array[1][0] y for " " " " + * coord_array[2][0] z for " " " " + * + * coord_array[0][1] x for node 2 node 202 node 402 node 602 + * coord_array[1][1] y for " " " " + * coord_array[2][1] z for " " " " + * + * ... + * + * coord_array[0][199] x for node 200 node 400 node 600 node 645 + * coord_array[1][199] y for " " " " + * coord_array[2][199] z for " " " " + *--------------------------------------------------------------------*/ +int +USERD_get_part_coords_in_buffers(int part_number, + float **coord_array, + int first, + int n_beg, + int n_end, + int buffer_size, + int *num_returned) + + + + + +/*-------------------------------------------------------------------- + * USERD_get_part_node_ids_in_buffers - + *-------------------------------------------------------------------- + * + * Get the node ids for an unstructured part in buffers. + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, get to + * the correct starting spot, initialize, etc. + * + * (IN) n_beg = Zero based, first node index + * of the buffered set + * + * (IN) n_end = Zero based, last node index + * of the buffered set + * + * Thus, for first five nodes: + * n_beg = 0 + * n_end = 4 + * total_number = (n_end - n_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five nodes, would be: + * n_beg = 5 + * n_end = 9 + * total_number = (n_end - n_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all nodes of a part, would be: + * n_beg = 0 + * n_end = num_nodes - 1 + * + * (IN) buffer_size = The size of the buffer. + * Namely: nodeid_array[buffer_size] + * + * (OUT) nodeid_array = 1D buffer array which is set up to hold + * node ids of nodes + * + * (IMPORTANT: this array is 0-based!!!) + * + * (IMPORTANT: in the sister routine (USERD_get_part_node_ids) - which + * does not use buffers. This array is 1-based. So pay attention.) + * + * (Array will have been allocated + * buffer_size long) + * + * Example, if we had a part with 645 nodes and the buffer size was set to 200 + * + * first invocation: + * first = TRUE Will be TRUE the first time! + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * nodeid_array[200] fill with values for nodes 1 - 200 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * second invocation: which occurs because we returned a 0 last time + * first = FALSE will now be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * nodeid_array[200] fill with values for nodes 201 - 400 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * third invocation: which occurs because we returned a 0 last time + * first = FALSE will still be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * nodeid_array[200] fill with values for nodes 401 - 600 (zero-based) + * *num_returned = 200 set this + * return(0) return this (indicates more to do) + * + * fourth invocation: which occurs because we returned a 0 last time + * first = FALSE will still be FALSE + * n_beg = 0 + * n_end = 644 + * buffer_size = 200 + * nodeid_array[200] fill with values for nodes 601 - 645 (zero-based) + * *num_returned = 45 set this + * return(1) return this (indicates done!) + * + * + * (OUT) *num_returned = The number of nodes whose ids are returned + * in the buffer. This will normally be equal + * to buffer_size except for that last buffer + * - which could be less than a full buffer. + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Not called unless number_of_nodes for the part > 0 + * + * * Again, make sure each buffer is zero based. For our example above: + * + * Invocation: + * 1 2 3 4 + * ------- ------- -------- ------- + * nodeid_array[0] id for node 1 node 201 node 401 node 601 + * + * nodeid_array[1] id for node 2 node 202 node 402 node 602 + * + * ... + * + * nodeid_array[199] id for node 200 node 400 node 600 node 645 + *--------------------------------------------------------------------*/ +int +USERD_get_part_node_ids_in_buffers(int part_number, + int *nodeid_array, + int first, + int n_beg, + int n_end, + int buffer_size, + int *num_returned) + + + + +/*-------------------------------------------------------------------- + * USERD_get_part_elements_by_type_in_buffers - + *-------------------------------------------------------------------- + * + * Gets the connectivities for the elements of a particular type + * in an unstructured part in buffers + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) element_type = One of the following (See global_extern.h) + * Z_POINT node point element + * Z_BAR02 2 node bar + * Z_BAR03 3 node bar + * Z_TRI03 3 node triangle + * Z_TRI06 6 node triangle + * Z_QUA04 4 node quad + * Z_QUA08 8 node quad + * Z_TET04 4 node tetrahedron + * Z_TET10 10 node tetrahedron + * Z_PYR05 5 node pyramid + * Z_PYR13 13 node pyramid + * Z_PEN06 6 node pentahedron + * Z_PEN15 15 node pentahedron + * Z_HEX08 8 node hexahedron + * Z_HEX20 20 node hexahedron + * + * Starting at API 2.01: + * ==================== + * Z_G_POINT ghost node point element + * Z_G_BAR02 2 node ghost bar + * Z_G_BAR03 3 node ghost bar + * Z_G_TRI03 3 node ghost triangle + * Z_G_TRI06 6 node ghost triangle + * Z_G_QUA04 4 node ghost quad + * Z_G_QUA08 8 node ghost quad + * Z_G_TET04 4 node ghost tetrahedron + * Z_G_TET10 10 node ghost tetrahedron + * Z_G_PYR05 5 node ghost pyramid + * Z_G_PYR13 13 node ghost pyramid + * Z_G_PEN06 6 node ghost pentahedron + * Z_G_PEN15 15 node ghost pentahedron + * Z_G_HEX08 8 node ghost hexahedron + * Z_G_HEX20 20 node ghost hexahedron + * Z_NSIDED n node ghost nsided polygon + * Z_NFACED n face ghost nfaced polyhedron + * + * Starting at API 2.02: + * ==================== + * Z_NSIDED n node nsided polygon + * Z_NFACED n face nfaced polyhedron + * Z_G_NSIDED n node ghost nsided polygon + * Z_G_NFACED n face ghost nfaced polyhedron + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, get to + * the correct starting spot, initialize, etc. + * + * (IN) e_beg = Zero based, first element number + * of the buffered set + * + * (IN) e_end = Zero based, last element number + * of the buffered set + * + * Thus, for first five elements of a type: + * e_beg = 0 + * e_end = 4 + * total_number = (e_end - e_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five elements of a type, would be: + * e_beg = 5 + * e_end = 9 + * total_number = (e_end - e_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all elements of the type of a part, would be: + * n_beg = 0 + * n_end = num_elements_of_type - 1 + * + * (IN) buffer_size = The size of the buffer. + * Namely: conn_array[buffer_size][element_size] + * + * (OUT) conn_array = 2D buffer array which is set up to hold + * connectivity of elements of the type. + * + * (Array will have been allocated + * buffer_size of + * the type by connectivity length + * of the type) + * + * ex) The allocated dimensions available + * for this routine will be: + * conn_array[buffer_size][3] when called with Z_TRI03 + * + * conn_array[buffer_size][4] when called with Z_QUA04 + * + * conn_array[buffer_size][8] when called with Z_HEX08 + * + * etc. + * + * * Example, (if 158 quad elements, and buffer size is 200) + * + * (get all 158 quad4s in one invocation) + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 (zero based, first element index) + * e_end = 157 (zero based, last element index) + * buffer_size = 200 + * conn_array[200][4] Use first 158 locations of the array + * *num_returned = 158 set this + * return(1) return this (indicates no more to do) + * + * * Example, (if 158 quad elements, and buffer size is 75) + * + * first invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * conn_array[75][4] load in conn for elements 1 - 75 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * second invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * conn_array[75][4] load in conn for elements 76 - 150 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * third invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * conn_array[75][4] load in conn for elements 151 - 158 + * *num_returned = 8 set this + * return(1) return this (indicates no more to do) + * + * + * (OUT) *num_returned = The number of elements whose connectivities + * are returned in the buffer. This will + * normally be equal to buffer_size except for + * that last buffer - which could be less than + * a full buffer. + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Again, make sure each buffer is zero based. For our example using buffers above: + * + * Invocation: + * 1 2 3 + * ------- ------- -------- + * conn_array[0][0] node 1 in conn for quad 1 quad 76 quad 151 + * conn_array[0][1] node 2 in conn for quad 1 quad 76 quad 151 + * conn_array[0][2] node 3 in conn for quad 1 quad 76 quad 151 + * conn_array[0][3] node 4 in conn for quad 1 quad 76 quad 151 + * + * conn_array[1][0] node 1 in conn for quad 2 quad 77 quad 152 + * conn_array[1][1] node 2 in conn for quad 2 quad 77 quad 152 + * conn_array[1][2] node 3 in conn for quad 2 quad 77 quad 152 + * conn_array[1][3] node 4 in conn for quad 2 quad 77 quad 152 + * + * ... + * + * conn_array[74][0] node 1 in conn for quad 75 quad 150 quad 158 + * conn_array[74][1] node 2 in conn for quad 75 quad 150 quad 158 + * conn_array[74][2] node 3 in conn for quad 75 quad 150 quad 158 + * conn_array[74][3] node 4 in conn for quad 75 quad 150 quad 158 + *--------------------------------------------------------------------*/ +int +USERD_get_part_elements_by_type_in_buffers(int part_number, + int element_type, + int **conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned) + + + + + +/*-------------------------------------------------------------------- + * USERD_get_part_element_ids_by_type_in_buffers - + *-------------------------------------------------------------------- + * + * Gets the ids for the elements of a particular type + * in an unstructured part in buffers + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) element_type = One of the following (See global_extern.h) + * Z_POINT node point element + * Z_BAR02 2 node bar + * Z_BAR03 3 node bar + * Z_TRI03 3 node triangle + * Z_TRI06 6 node triangle + * Z_QUA04 4 node quad + * Z_QUA08 8 node quad + * Z_TET04 4 node tetrahedron + * Z_TET10 10 node tetrahedron + * Z_PYR05 5 node pyramid + * Z_PYR13 13 node pyramid + * Z_PEN06 6 node pentahedron + * Z_PEN15 15 node pentahedron + * Z_HEX08 8 node hexahedron + * Z_HEX20 20 node hexahedron + * + * Starting at API 2.01: + * ==================== + * Z_G_POINT ghost node point element + * Z_G_BAR02 2 node ghost bar + * Z_G_BAR03 3 node ghost bar + * Z_G_TRI03 3 node ghost triangle + * Z_G_TRI06 6 node ghost triangle + * Z_G_QUA04 4 node ghost quad + * Z_G_QUA08 8 node ghost quad + * Z_G_TET04 4 node ghost tetrahedron + * Z_G_TET10 10 node ghost tetrahedron + * Z_G_PYR05 5 node ghost pyramid + * Z_G_PYR13 13 node ghost pyramid + * Z_G_PEN06 6 node ghost pentahedron + * Z_G_PEN15 15 node ghost pentahedron + * Z_G_HEX08 8 node ghost hexahedron + * Z_G_HEX20 20 node ghost hexahedron + * Z_NSIDED n node ghost nsided polygon + * Z_NFACED n face ghost nfaced polyhedron + * + * Starting at API 2.02: + * ==================== + * Z_NSIDED n node nsided polygon + * Z_NFACED n face nfaced polyhedron + * Z_G_NSIDED n node ghost nsided polygon + * Z_G_NFACED n face ghost nfaced polyhedron + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, get to + * the correct starting spot, initialize, etc. + * + * (IN) e_beg = Zero based, first element number + * of the buffered set + * + * (IN) e_end = Zero based, last element number + * of the buffered set + * + * Thus, for first five elements of a type: + * e_beg = 0 + * e_end = 4 + * total_number = (e_end - e_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five elements of a type, would be: + * e_beg = 5 + * e_end = 9 + * total_number = (e_end - e_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all elements of the type of a part, would be: + * n_beg = 0 + * n_end = num_elements_of_type - 1 + * + * (IN) buffer_size = The size of the buffer. + * Namely: elemid_array[buffer_size] + * + * (OUT) elemid_array = 1D buffer array which is set up to hold ids + * of elements of the type. + * + * (Array will have been allocated + * buffer_size long) + * + * * Example, (if 158 quad elements, and buffer size is 200) + * + * (get all 158 quad4 ids in one invocation) + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 (zero based, first element index) + * e_end = 157 (zero based, last element index) + * buffer_size = 200 + * elemeid_array[200] Use first 158 locations of the array + * *num_returned = 158 set this + * return(1) return this (indicates no more to do) + * + * * Example, (if 158 quad elements, and buffer size is 75) + * + * first invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * elemid_array[75] load in ids for elements 1 - 75 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * second invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * elemid_array[75] load in ids for elements 76 - 150 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * third invocation: + * element_type = Z_QUA04 + * first = TRUE Will be TRUE the first time! + * e_beg = 0 + * e_end = 157 + * buffer_size = 75 + * elemid_array[75] load in ids for elements 151 - 158 + * *num_returned = 8 set this + * return(1) return this (indicates no more to do) + * + * + * (OUT) *num_returned = The number of elements whose ids are returned + * in the buffer. This will normally be equal + * to buffer_size except for that last buffer + * - which could be less than a full buffer. + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Again, make sure each buffer is zero based. For our example using buffers above: + * + * Invocation: + * 1 2 3 + * ------- ------- -------- + * elemid_array[0] elem id for quad 1 quad 76 quad 151 + * + * elemid_array[1] elem id for quad 2 quad 77 quad 152 + * + * ... + * + * elemid_array[74] elem id for quad 75 quad 150 quad 158 + *--------------------------------------------------------------------*/ +int +USERD_get_part_element_ids_by_type_in_buffers(int part_number, + int element_type, + int *elemid_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned) + + + + + + +/*-------------------------------------------------------------------- + * USERD_get_var_by_component_in_buffers - used by unstructured parts + *-------------------------------------------------------------------- + * + * if Z_PER_NODE: + * Get the component value at each node for a given variable in the part + * in buffers. + * + * or if Z_PER_ELEM: + * Get the component value at each element of a specific part and type for + * a given variable in buffers. + * + * (IN) which_variable = The variable number + * + * (IN) which_part Since EnSight Version 7.4 + * ------------------------- + * = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * Prior to EnSight Version 7.4 + * ---------------------------- + * = The part id This is the part_id label loaded + * in USERD_get_gold_part_build_inf\o. + * It is NOT the part table index. + * + * (IN) var_type = Z_SCALAR + * Z_VECTOR + * Z_TENSOR ( symmetric tensor) + * Z_TENSOR9 (asymmetric tensor) + * + * (IN) which_type + * + * if Z_PER_NODE: Not used + * + * if Z_PER_ELEM: = The element type + * Z_POINT node point element + * Z_BAR02 2 node bar + * Z_BAR03 3 node bar + * Z_TRI03 3 node triangle + * Z_TRI06 6 node triangle + * Z_QUA04 4 node quad + * Z_QUA08 8 node quad + * Z_TET04 4 node tetrahedron + * Z_TET10 10 node tetrahedron + * Z_PYR05 5 node pyramid + * Z_PYR13 13 node pyramid + * Z_PEN06 6 node pentahedron + * Z_PEN15 15 node pentahedron + * Z_HEX08 8 node hexahedron + * Z_HEX20 20 node hexahedron + * + * Starting at API 2.01: + * ==================== + * Z_G_POINT ghost node point element + * Z_G_BAR02 2 node ghost bar + * Z_G_BAR03 3 node ghost bar + * Z_G_TRI03 3 node ghost triangle + * Z_G_TRI06 6 node ghost triangle + * Z_G_QUA04 4 node ghost quad + * Z_G_QUA08 8 node ghost quad + * Z_G_TET04 4 node ghost tetrahedron + * Z_G_TET10 10 node ghost tetrahedron + * Z_G_PYR05 5 node ghost pyramid + * Z_G_PYR13 13 node ghost pyramid + * Z_G_PEN06 6 node ghost pentahedron + * Z_G_PEN15 15 node ghost pentahedron + * Z_G_HEX08 8 node ghost hexahedron + * Z_G_HEX20 20 node ghost hexahedron + * Starting at API 2.02: + * ==================== + * Z_NSIDED n node nsided polygon + * Z_NFACED n face nfaced polyhedron + * Z_G_NSIDED n node ghost nsided polygon + * Z_G_NFACED n face ghost nfaced polyhedron + * + * + * + * (IN) imag_data = TRUE if imag component + * FALSE if real component + * + * (IN) component = The component: (0 if Z_SCALAR) + * (0 - 2 if Z_VECTOR) + * (0 - 5 if Z_TENSOR) + * (0 - 8 if Z_TENSOR9) + * + * * 6 Symmetric Indicies, 0:5 * + * * ---------------------------- * + * * | 11 12 13 | | 0 3 4 | * + * * | | | | * + * * T = | 22 23 | = | 1 5 | * + * * | | | | * + * * | 33 | | 2 | * + * + * * 9 General Indicies, 0:8 * + * * ---------------------------- * + * * | 11 12 13 | | 0 1 2 | * + * * | | | | * + * * T = | 21 22 23 | = | 3 4 5 | * + * * | | | | * + * * | 31 32 33 | | 6 7 8 | * + * + * (IN) ne_beg + * if Z_PER_NODE: = Zero based, first node index of the buffered set + * if Z_PER_ELEM: = Zero based, first element index of the buffered set + * + * (IN) ne_end + * if Z_PER_NODE: = Zero based, last node index of the buffered set + * if Z_PER_ELEM: = Zero based, last element index of the buffered set + * + * Thus, for first five elements or nodes: + * e_beg = 0 + * e_end = 4 + * total_number = (e_end - e_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five elements or nodes, would be: + * e_beg = 5 + * e_end = 9 + * total_number = (e_end - e_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all elements or nodes of a part, would be: + * n_beg = 0 + * n_end = num_elements_or_nodes - 1 + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, get to + * the correct starting spot, initialize, etc. + * + * (IN) buffer_size = The size of the buffer. + * Namely: var_array[buffer_size] + * + * (IN) leftside = TRUE if current time is at a timestep or + * when getting the left side of a time + * span that encloses the current time. + * = FALSE when getting the right side of a time + * span that encloses the current time. + * + * Timeline: + * step1 step2 step3 + * |-------------|--------------|-------... requires no interpolation + * ^ get values at step2 (leftside = TRUE) + * current time (leftside = TRUE) + * + * + * Timeline: + * step1 step2 step3 + * |-------------|--------------|-------... requires interpolation + * ^ get values at step2 (leftside = TRUE) + * current time and get values at step3 (leftside = FALSE) + * + * Note that it would generally be easier for this routine if EnSight got all + * of the left side, then all of the right side, and then did its + * interpolation. But, in the spirit of doing things in buffers (to save + * memory) it gets a left side buffer (and the corresponding right side + * buffer and interpolates these), if needed, before going to the next + * buffer of the set. Thus, you need to be able to handle that situation. + * + * Note also that EnSight will have called the routine to change the current + * time step between the two invocations when interpolation is required. + * And Ensight does the interpolating. This variable is provided so + * that you can deal with two different files or pointers between the + * corresponding invocations for the two times + * + * (OUT) var_array + * + * ----------------------------------------------------------------------- + * (IMPORTANT: this array is 0-based for both Z_PER_NODE and Z_PER_ELEM!!! + * ----------------------------------------------------------------------- + * + * if Z_PER_NODE: = 1D buffer array set up to hold a variable + * component value for nodes. + * + * if Z_PER_ELEM: = 1D buffer array set up to hold a variable + * component value for elements. + * + * (Array will have been allocated + * buffer_size long) + * + * Info stored in this fashion: + * var_array[0] = var component for node or element 1 of part + * var_array[1] = var component for node or element 2 of part + * var_array[2] = var component for node or element 3 of part + * etc. + * + * * Example, (if 158 quad elements with a real Z_PER_ELEM scalar, + * current time is between steps, and buffer size is 75) + * + * first invocation: (for left side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = TRUE Will be TRUE the first time! + * buffer_size = 75 + * leftside = TRUE <== + * var_array[75] load in scalar value for elements 1 - 75 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * second invocation: (for right side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = TRUE Note: Will still be TRUE (because is right side) + * buffer_size = 75 + * leftside = FALSE <== + * var_array[75] load in scalar value for elements 1 - 75 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * ------------------------------- + * third invocation: (for left side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = FALSE Will be FALSE now + * buffer_size = 75 + * leftside = TRUE <== + * var_array[75] load in scalar value for elements 76 - 150 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + * fourth invocation: (for right side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = FALSE + * buffer_size = 75 + * leftside = FALSE <== + * var_array[75] load in scalar value for elements 76 - 150 + * *num_returned = 75 set this + * return(0) return this (indicates more to do) + * + *------------------------------------ + * fifth invocation: (for left side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = FALSE Will still be FALSE + * buffer_size = 75 + * leftside = TRUE <== + * var_array[75] load in scalar value for elements 151 - 158 + * *num_returned = 8 set this + * return(1) return this (indicates no more to do) + * + * sixth invocation: (for right side of time span) + * var_type = Z_SCALAR + * which_type = Z_PER_ELEM + * imag_data = FALSE + * component = 0 + * ne_beg = 0 + * ne_end = 157 + * first = FALSE + * buffer_size = 75 + * leftside = FALSE <== + * var_array[75] load in scalar value for elements 151 - 158 + * *num_returned = 8 set this + * return(1) return this (indicates no more to do) + * + * + * (OUT) *num_returned = The number of nodes or elements whose variable + * values are returned in the buffer. This will + * normally be equal to buffer_size except for + * that last buffer - which could be less than + * a full buffer. + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Again, make sure each buffer is zero based. For our example using buffers above: + * + * Invocation: + * ---------------- ------------------ ------------------- + * 1 2 3 4 5 6 + * ------- ------- -------- -------- --------- --------- + * var_array[0] scalar of quad 1L quad 1R quad 76L quad 76R quad 151L quad 151R + * + * var_array[1] scalar of quad 2L quad 2R quad 77L quad 77R quad 152L quad 152R + * + * ... + * + * var_array[74] scalar of quad 75L quad 75R quad 150L quad 150R quad 158L quad 158R + * + * Where: L indicates left time step + * R indicates right time step + *--------------------------------------------------------------------*/ +int +USERD_get_var_by_component_in_buffers(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array, + int first, + int ne_beg, + int ne_end, + int buffer_size, + int leftside, + int *num_returned) + + + + +/*-------------------------------------------------------------------- + * USERD_get_nsided_conn_in_buffers - + *-------------------------------------------------------------------- + * + * Gets the two arrays containing the connectivity information + * of nsided elements in buffers + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, + * get to the correct starting spot, + * initialize, etc. + * + * (IN) e_beg = Zero based, first element number + * of the buffered set + * + * (IN) e_end = Zero based, last element number + * of the buffered set + * + * Thus, for first five elements of a type: + * e_beg = 0 + * e_end = 4 + * total_number = (e_end - e_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five elements of a type, would be: + * e_beg = 5 + * e_end = 9 + * total_number = (e_end - e_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all elements of the type of a part, would be: + * n_beg = 0 + * n_end = num_elements_of_type - 1 + * + * (IN) buffer_size = The size of the num_nodes_per_elem_array buffer. + * Namely: num_nodes_per_elem_array[buffer_size] + * + * (OUT) num_nodes_per_elem_array = 1D buffer array of the number of nodes + * per nsided element. + * + * (OUT) nsided_conn_array = 1D buffer array of nsided connectivies + * + * (int array will have been allocated + * long enough to hold all the nsided + * connectivities in the buffered chunk) + * + * (OUT) *num_returned = The number of elements whose connectivities + * are returned in the buffer. This will + * normally be equal to buffer_size except for + * that last buffer - which could be less than + * a full buffer. + * + * Providing nsided information to Ensight: + * + * NOTE: for other nsided operations you need these first two, but we + * don't actually use them in this routine. + * + * 1. In USERD_get_gold_part_build_info, provide the number of nsided + * elements in the part. + * + * 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + * the number of nodes per nsided element. (as if connectivity + * length of an nsided element is one) + * + * We do use the following: + * 3. In this routine, provide the corresponding num_nodes_per_element and + * streamed connectivities for each of the nsided elements in this + * buffered portion. + * + * + * Simple example: 5 6 + * +--------+ + * 3 nsided elements: /| \ + * (1 4-sided / | \ + * 1 3-sided / | \ + * 1 7-sided) / | \ 7 + * /3 |4 + + * +-----+ | + * | | | + * | | |8 + * | | + + * | | / + * | | / + * | | / + * |1 |2 /9 + * +-----+--------+ + * + * NOTE, don't really use these first two here (See USERD_get_nsided_conn) + * + * 1. In USERD_get_gold_part_build_info: + * number_of_elements[Z_NSIDED] = 3 + * . + * /|\ + * | + * 2. In USERD_get_part_elements_by_type: + * length of conn_array will be: 3 x 1 + * + * for element_type of Z_NSIDED: + * conn_array[0][0] = 4 (for the 4-sided element) + * conn_array[1][0] = 3 (for the 3-sided element) + * conn_array[2][0] = 7 (for the 7-sided element) + * + * Sum === + * 14 + * + * But for our example, lets assume that that our buffer is just 2 + * ================ + * 3. In this routine: + * + * first invocation: + * first = TRUE + * e_beg = 0 + * e_end = 2 + * buffer_size = 2 + * num_nodes_per_elem_array[2] load it: num_nodes_per_elem_array[0] = 4 + * num_nodes_per_elem_array[1] = 3 + * + * nsided_conn_array[at least 7] load it: nsided_conn_array[0] = 1 + * nsided_conn_array[1] = 2 + * nsided_conn_array[2] = 4 + * nsided_conn_array[3] = 3 + * + * nsided_conn_array[4] = 3 + * nsided_conn_array[5] = 4 + * nsided_conn_array[6] = 5 + * *num_returned = 2 + * return(0) return this (indicates more to do) + * + * second invocation: + * first = FALSE + * e_beg = 0 + * e_end = 2 + * buffer_size = 2 + * num_nodes_per_elem_array[2] load it: num_nodes_per_elem_array[0] = 7 + * + * nsided_conn_array[at least 7] load it: nsided_conn_array[0] = 2 + * nsided_conn_array[1] = 9 + * nsided_conn_array[2] = 8 + * nsided_conn_array[3] = 7 + * nsided_conn_array[4] = 6 + * nsided_conn_array[5] = 5 + * nsided_conn_array[6] = 4 + * *num_returned = 1 + * return(1) return this (indicates no more to do) + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Will not be called unless there are some nsided elements in the + * the part + *--------------------------------------------------------------------*/ +int +USERD_get_nsided_conn_in_buffers(int part_number, + int *num_nodes_per_elem_array, + int *nsided_conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned) + + + + +/*-------------------------------------------------------------------- + * USERD_get_nfaced_conn_in_buffers - + *-------------------------------------------------------------------- + * + * Gets three arrays containing the number of faces per element, + * number of nodes per face, and connectivity per face of nfaced + * elements in buffers + * + * (IN) part_number = The part number + * + * (1-based index of part table, namely: + * + * 1 ... Numparts_available. + * + * It is NOT the part_id that + * is loaded in USERD_get_gold_part_build_info) + * + * (IN) first = TRUE if first invocation of a buffered set. + * Will be FALSE for all subsequent invocations + * of the set. This is so you can open files, + * get to the correct starting spot, + * initialize, etc. + * + * (IN) e_beg = Zero based, first element number + * of the buffered set + * + * (IN) e_end = Zero based, last element number + * of the buffered set + * + * Thus, for first five elements of a type: + * e_beg = 0 + * e_end = 4 + * total_number = (e_end - e_beg) + 1 = (4 - 0) + 1 = 5 + * + * for second five elements of a type, would be: + * e_beg = 5 + * e_end = 9 + * total_number = (e_end - e_beg) + 1 = (9 - 5) + 1 = 5 + * + * for all elements of the type of a part, would be: + * n_beg = 0 + * n_end = num_elements_of_type - 1 + * + * (IN) buffer_size = The size of the num_nodes_per_elem_array buffer. + * Namely: num_nodes_per_elem_array[buffer_size] + * + * (OUT) nfaced_fpe_array = 1D buffer array of the number of faces per nfaced + * element. + * + * (int array will have been allocated + * buffer_size long) + * + * (OUT) nfaced_npf_array = 1D buffer array of the number of nodes per face + * for nfaced elements. + * + * (int array will have been allocated long + * enough to hold a buffer's size of values) + * + * (OUT) nfaced_conn_array = 1D array of nsided face connectivies of + * nfaced elements + * + * (int array will have been allocated + * long enough to hold a buffer's worth of values) + * + * Providing nfaced information to Ensight: + * + * NOTE: for other nfaced operations you need these first two, but we + * don't actually use them in this routine. + * + * 1. In USERD_get_gold_part_build_info, provide the number of nfaced + * polyhedral elements in the part. + * + * 2. In USERD_get_part_elements_by_type, provide (in the conn_array), + * the number of faces per nfaced element. (as if connectivity + * length of an nfaced element is one) + * + * We do use the following: + * 3. In this routine, provide the corresponding number of faces per nfaced + * element, streamed number of nodes per face, and streamed face + * connectivities for each of the faces of the nfaced elements in the + * bufferred portion. + * + * + * Simple example: 11 10 12 + * +--------+-----+ + * 2 nfaced elements: /| |\ /| + * (1 7-faced / | | \ / | + * 1 5-sided) / | | +9 | + * / | | /| | + * /7 | 8 / | | + * +-----------+/ | | | + * | |5 | |4 | |6 + * | +-----|--+--|--+ + * | / | \ | / + * | / | \|/3 + * | / | + + * | / | / + * |/1 |2 / + * +-----------+/ + * + * Note, don't really use these first two here (See USERD_get_nfaced_conn) + * + * 1. In USERD_get_gold_part_build_info: + * number_of_elements[Z_NFACED] = 2 + * . + * /|\ + * | + * 2. In USERD_get_part_elements_by_type: + * length of conn_array will be: 2 x 1 + * for element_type of Z_NFACED: + * conn_array[0][0] = 7 (for the 7-faced element) + * conn_array[1][0] = 5 (for the 5-faced element) + * == + * Sum 12 + * + * + * But for our simple example, lets assume that that our buffer is just 1 + * so that we have multiple invocations. ================ + * + * 3. In this routine: + * + * first invocation: + * first = TRUE + * e_beg = 0 + * e_end = 1 + * buffer_size = 1 + * nfaced_fpe_array[1] load it: nfaced_fpe_array[0] = 7 + * + * nfaced_npf_array[at least 7] load it: nfaced_npf_array[0] = 5 + * nfaced_npf_array[1] = 5 + * nfaced_npf_array[2] = 4 + * nfaced_npf_array[3] = 4 + * nfaced_npf_array[4] = 4 + * nfaced_npf_array[5] = 4 + * nfaced_npf_array[6] = 4 + * + * nsided_conn_array[at least 30] load it: nsided_conn_array[0] = 7 + * nsided_conn_array[1] = 8 + * nsided_conn_array[2] = 9 + * nsided_conn_array[3] = 10 + * nsided_conn_array[4] = 11 + * + * nsided_conn_array[5] = 1 + * nsided_conn_array[6] = 5 + * nsided_conn_array[7] = 4 + * nsided_conn_array[8] = 3 + * nsided_conn_array[9] = 2 + * + * nsided_conn_array[10] = 1 + * nsided_conn_array[11] = 2 + * nsided_conn_array[12] = 8 + * nsided_conn_array[13] = 7 + * + * nsided_conn_array[14] = 5 + * nsided_conn_array[15] = 1 + * nsided_conn_array[16] = 7 + * nsided_conn_array[17] = 11 + * + * nsided_conn_array[18] = 4 + * nsided_conn_array[19] = 5 + * nsided_conn_array[20] = 11 + * nsided_conn_array[21] = 10 + * + * nsided_conn_array[22] = 2 + * nsided_conn_array[23] = 3 + * nsided_conn_array[24] = 9 + * nsided_conn_array[25] = 8 + * + * nsided_conn_array[26] = 3 + * nsided_conn_array[27] = 4 + * nsided_conn_array[28] = 10 + * nsided_conn_array[29] = 9 + * *num_returned = 1; + * return(0) + * + * second invocation: + * first = FALSE + * e_beg = 0 + * e_end = 1 + * buffer_size = 1 + * nfaced_fpe_array[1] load it: nfaced_fpe_array[0] = 5 + * + * nfaced_npf_array[at least 7] load it: nfaced_npf_array[0] = 3 + * nfaced_npf_array[1] = 3 + * nfaced_npf_array[2] = 4 + * nfaced_npf_array[3] = 4 + * nfaced_npf_array[4] = 4 + * + * nsided_conn_array[at least 18] load it: nsided_conn_array[0] = 9 + * nsided_conn_array[1] = 12 + * nsided_conn_array[2] = 10 + * + * nsided_conn_array[3] = 3 + * nsided_conn_array[4] = 4 + * nsided_conn_array[5] = 6 + * + * nsided_conn_array[6] = 6 + * nsided_conn_array[7] = 4 + * nsided_conn_array[8] = 10 + * nsided_conn_array[9] = 12 + * + * nsided_conn_array[10] = 3 + * nsided_conn_array[11] = 6 + * nsided_conn_array[12] = 12 + * nsided_conn_array[13] = 9 + * + * nsided_conn_array[14] = 4 + * nsided_conn_array[15] = 3 + * nsided_conn_array[16] = 9 + * nsided_conn_array[17] = 10 + * *num_returned = 1; + * return(1) + * + * returns 0 if got some, more to do + * 1 if got some, done + * -1 if an error + * + * Notes: + * * This will be based on Current_time_step + * + * * Will not be called unless there are some nfaced elements in the + * the part + *--------------------------------------------------------------------*/ +int +USERD_get_nfaced_conn_in_buffers(int part_number, + int *nfaced_fpe_array, + int *nfaced_npf_array, + int *nfaced_conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned) diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_API.H b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_API.H new file mode 100644 index 0000000000..0a76de2333 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_API.H @@ -0,0 +1,2 @@ +#define DO_READER +#define USERD_API_203 diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_release.H b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_release.H new file mode 100644 index 0000000000..3a75b16675 --- /dev/null +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_release.H @@ -0,0 +1,18 @@ +int USERD_get_reader_release +( + char release_number[Z_MAX_USERD_NAME] +) +{ + +#ifdef ENSIGHTDEBUG + Info << "Entering: USERD_get_reader_release" << endl; +#endif + + strncpy(release_number, Foam::FOAMbuild, Z_MAX_USERD_NAME); + +#ifdef ENSIGHTDEBUG + Info << "Leaving: USERD_get_reader_release" << endl; +#endif + + return Z_OK; +} diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_version.H b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_version.H index 9debdb474e..7c8206664b 100644 --- a/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_version.H +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/USERD_get_reader_version.H @@ -2,7 +2,7 @@ int USERD_get_reader_version ( char version_number[Z_MAX_USERD_NAME] ) -{ +{ #ifdef ENSIGHTDEBUG Info << "Entering: USERD_get_reader_version" << endl; @@ -13,6 +13,6 @@ int USERD_get_reader_version #ifdef ENSIGHTDEBUG Info << "Leaving: USERD_get_reader_version" << endl; #endif - + return Z_OK; } diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/globalFoam.H b/applications/utilities/postProcessing/graphics/ensightFoamReader/globalFoam.H index 7c7f2b16d8..40fb28d949 100644 --- a/applications/utilities/postProcessing/graphics/ensightFoamReader/globalFoam.H +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/globalFoam.H @@ -7,7 +7,7 @@ static char readerName[] = "OpenFOAM"; static char meshName[] = "cells"; static char readerVersion[] = "2.03"; -// everything is one part in foam, except the spray +// everything is one part in OpenFOAM, except the spray static int Num_unstructured_parts = 1; static int Num_structured_parts = 0; static int Numparts_available = 1; diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern.h b/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern.h index 4e33501129..07514c06aa 100644 --- a/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern.h +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern.h @@ -18,21 +18,27 @@ #ifndef GLOBAL_EXTERN_H #define GLOBAL_EXTERN_H +#ifdef __cplusplus +extern "C" { +#endif + /*-------------------------------- * Set the reader version define * (only one can be set at a time) *--------------------------------*/ +#if 0 +#define USERD_API_100 +#define USERD_API_200 +#define USERD_API_201 +#define USERD_API_202 #define USERD_API_203 - -/*---------------------------------------- - * Set this appropriately: - * DO_ENSIGHT if using for EnSight itself - * DO_READER if using in a reader - *----------------------------------------*/ -#if 1 -#define DO_READER -#else -#define DO_ENSIGHT +#define USERD_API_204 +#define USERD_API_205 +#define USERD_API_206 +#define USERD_API_207 +#define USERD_API_208 +#define USERD_API_209 +#define USERD_API_210 #endif /*---------------------------------------*/ @@ -73,6 +79,28 @@ #define Z_MAX_SETS (300) +#define Z_MX_MATERIALS (60) + +#define Z_MXVARIABLEDESC 20 /*Interface Variables Max Name.*/ + +/* Useful macros for handling IEEE floats */ +#define FLT_SGN_MASK 0x80000000U +#define FLT_EXP_MASK 0x7F800000U +#define FLT_MAN_MASK 0x007FFFFFU +#define FLT_EXP_BIAS 127 +#define FLT_EXP_SHIFT 23 + +#define FLT_IS_FINITE(v) \ + (((*((unsigned int*)&(v))) & FLT_EXP_MASK) != FLT_EXP_MASK) + +#define FLT_IS_NAN(v) \ + ((((*((unsigned int*)&(v))) & FLT_EXP_MASK) == FLT_EXP_MASK) && \ + ((((*((unsigned int*)&(v))) & FLT_MAN_MASK) != 0U) + +#define FLT_IS_INF(v) \ + ((((*((unsigned int*)&(v))) & FLT_EXP_MASK) == FLT_EXP_MASK) && \ + ((((*((unsigned int*)&(v))) & FLT_MAN_MASK) == 0U) + #ifndef GLOBALDEFS_H /*-----------------------------------*/ /* Unstructured coordinate structure */ @@ -80,6 +108,12 @@ typedef struct { float xyz[3]; }CRD; +/*-----------------------------------*/ +/* Unstructured double coordinate structure */ +/*-----------------------------------*/ +typedef struct { + double xyz[3]; +}DBLCRD; #endif /*----------------*/ @@ -95,6 +129,23 @@ enum z_var_type MAX_Z_VAR_TYPES }; +/*------------------- + * Vector Glyph enums + *-------------------*/ +enum vg_time { + VG_STATIC, + VG_TRANSIENT, + VG_UNDEF, + VG_NEAREST, + VG_INTERPOLATE +}; + +enum vg_type { + VG_FORCE, + VG_MOMENT +}; + + /*--------------- * Element Types *--------------- @@ -104,7 +155,7 @@ enum z_var_type * to_int_elem_type routines * in userd_read.c *----------------------------------------*/ -#if (defined USERD_API_100 || defined USERD_API_200) && defined DO_READER +#if (defined USERD_API_100 || defined USERD_API_200) enum z_elem_types { Z_POINT, /* 00: 1 node point element */ Z_BAR02, /* 01: 2 node bar */ @@ -124,7 +175,7 @@ enum z_elem_types { Z_MAXTYPE }; -#elif defined USERD_API_201 && defined DO_READER +#elif defined USERD_API_201 enum z_elem_types { Z_POINT, /* 00: 1 node point element */ Z_G_POINT, /* 01: 1 node point element (ghost call) */ @@ -265,17 +316,97 @@ enum z_material_file_index Z_MAT_INDEX, Z_MIX_INDEX, Z_MIX_VALUE, + Z_SPE_VALUE, Z_NUM_MAT_FILES }; +/*------------------------------------------- + * Material type enum + * + * (Must be comparable to matset_via_file_type + * in mat_defs.h of EnSight server) + *--------------------------------------------*/ +enum z_matset_via_file_type +{ + Z_MISET_VIA_SPARSE_MIX, /* Original method prior to 07Feb07:mel*/ + Z_MISET_VIA_ESCAL_VARS, /* Materials via element scalar variables*/ + Z_MISET_VIA_MAX_FTYPES +}; + + +/* --------------------------------------- + * Extra GUI size stuff + * _EGS + * This is the maximum number of + * Extra GUI items that you are + * allowed of each type. + * + * Don't change these values! + * ------------------------------------- */ +#define Z_MAX_NUM_GUI_PULL_ITEMS 20 /* max num GUI pulldowns */ +#define Z_LEN_GUI_PULL_STR 80 /* max length of GUI pulldown string */ +#define Z_LEN_GUI_FIELD_STR 256 /* max length of field string */ +#define Z_LEN_GUI_TITLE_STR 40 /* max length of title string */ + +/* --------------------------------------- + * Extra data function defines (for "target") + * + * Don't change these values! + * ------------------------------------- */ +#define DATA_TARGET_NONE 0 +#define DATA_TARGET_SERVER 1 +#define DATA_TARGET_SOS 2 +#define DATA_TARGET_CLIENT 3 +#define DATA_TARGET_PYTHON 0x10000000 +#define DATA_TARGET_CMDLANG 0x20000000 +#define DATA_TARGET_UNDEF_VAL 0x40000000 +#define DATA_TARGET_OTHER 0x00000000 +#define DATA_TARGET_MASK 0x0000000f + +/* --------------------------------------- + * Failed elemenet enums + * --------------------------------------- */ + +enum z_element_failure_criteria +{ + Z_ELE_FAILED_NONE, + Z_ELE_FAILED_GREATER, + Z_ELE_FAILED_LESS, + Z_ELE_FAILED_EQUAL, + Z_ELE_FAILED_NOT_EQUAL, + Z_ELE_FAILED_MANY +}; + + +enum z_element_failure_logic +{ + Z_ELE_FAILED_LOGIC_NONE, + Z_ELE_FAILED_LOGIC_AND, + Z_ELE_FAILED_LOGIC_OR, + Z_ELE_FAILED_LOGIC_MANY +}; /*---------------------------------------------------------- - * For readers, we need to include the prototype header file + * We include the prototype header file *----------------------------------------------------------*/ -#if defined DO_READER #include "global_extern_proto.h" -#endif +/* --------------------- + * export the file pointer if windows + * because windows can't open a file in the + * server and pass the FILE * pointer properly. + * --------------------- */ +#ifdef WIN32 +typedef struct _USERD_globals_struct { + char arch_filename[256]; + unsigned long arch_fileptr; +} _USERD_globals; +#endif + +#ifdef __cplusplus +} +#endif + /*--------------------------------------------------------------------*/ #endif /*GLOBAL_EXTERN_H*/ diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern_proto.h b/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern_proto.h index 6a08f5a67f..e64a466230 100644 --- a/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern_proto.h +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/global_extern_proto.h @@ -21,6 +21,8 @@ #ifndef GLOBAL_EXTERN_PROTO_H #define GLOBAL_EXTERN_PROTO_H +#include + #ifdef WIN32 #define W32IMPORT __declspec( dllimport ) #define W32EXPORT __declspec( dllexport ) @@ -32,67 +34,260 @@ /*---------------------- * Same in All Versions *----------------------*/ -W32IMPORT int +W32EXPORT int USERD_get_number_of_model_parts( void ); -W32IMPORT int +W32EXPORT int USERD_get_block_coords_by_component(int block_number, int which_component, float *coord_array); -W32IMPORT int +W32EXPORT int USERD_get_block_iblanking(int block_number, int *iblank_array); -W32IMPORT int +W32EXPORT int USERD_get_block_scalar_values(int block_number, int which_scalar, float *scalar_array); -W32IMPORT int +W32EXPORT int USERD_get_block_vector_values_by_component(int block_number, int which_vector, int which_component, float *vector_array); -W32IMPORT int +W32EXPORT int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME], int *two_fields); + +/* + * This mechanism is used to mark the fact that a given + * reader cannot be unloaded. We set this by default for + * C++ based readers as there are known issues with unloading + * a C++ DLL on certain platforms (Linux). + */ +W32EXPORT int +USERD_reader_unloadable(void); + +#ifdef __cplusplus +/* + * Define a macro that defines the cpp function as part of the + * USERD_get_name_of_reader declaration + */ +#ifndef NO_AUTO_UNLOADABLE_CODE + +#if defined(LINUX) || defined(SGI) + +#define USERD_get_name_of_reader \ + USERD_reader_unloadable(void) { return(0); } \ +int USERD_get_name_of_reader + +#endif + +#endif + +#endif -W32IMPORT int +W32EXPORT int USERD_get_reader_descrip(char descrip[Z_MAXFILENP]); -W32IMPORT int +W32EXPORT int USERD_set_filenames(char filename_1[], char filename_2[], char the_path[], int swapbytes); -W32IMPORT int +W32EXPORT int USERD_get_number_of_files_in_dataset( void ); -W32IMPORT int +W32EXPORT int USERD_get_dataset_query_file_info(Z_QFILES *qfiles); -W32IMPORT int +W32EXPORT int USERD_get_changing_geometry_status( void ); -W32IMPORT int +W32EXPORT int USERD_get_node_label_status( void ); -W32IMPORT int +W32EXPORT int USERD_get_element_label_status( void ); -W32IMPORT int +W32EXPORT int USERD_get_number_of_variables( void ); -W32IMPORT void +W32EXPORT void USERD_stop_part_building( void ); -W32IMPORT int +W32EXPORT int USERD_bkup(FILE *archive_file, int backup_type); +/* ----------------------------------- + * Optional routine allows getting data + * from the reader to modify server/client behavior + * ------------------------------------ */ +W32EXPORT int +USERD_get_extra_data(int *target, + int *nints, int *nflts, int *nchrs, + int *pints, float *pflts, char *pchrs); + +/* ---------------------------- + * Extra "Before" GUI stuff available for all versions of API + * Note: this API suite is entirely optional... + * --------------------------- */ +W32EXPORT void USERD_get_extra_gui_numbers( + int *num_Toggles, + int *num_pulldowns, + int *num_fields +); + +W32EXPORT int USERD_get_extra_gui_defaults( + char **toggle_Title, /* [num_toggles][Z_LEN_GUI_TITLE_STR] */ + int *toggle_default_status, /* [num_toggles] */ + char **pulldown_Title, /* [num_pulldowns][Z_LEN_GUI_TITLE_STR] */ + int *pulldown_number_in_list, /* [num_pulldowns] */ + int *pulldown_default_selection, /* [num_pulldowns] */ + char ***pulldown_item_strings, /* [num_pulldowns][Z_MAX_NUM_GUI_PULL_ITEMS][Z_LEN_GUI_PULL_STR] */ + char **field_Title, /* [num_fields][Z_LEN_GUI_TITLE_STR] */ + char **field_user_string /* [num_fields][Z_LEN_GUI_FIELD_STR] */ +); + +W32EXPORT void USERD_set_extra_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR] */ +); + +/* ---------------------------- + * Extra "After" GUI stuff available for all versions of API + * Note: this API suite is entirely optional... + * --------------------------- */ +W32EXPORT void USERD_get_var_extract_gui_numbers( + int *num_Toggles, + int *num_pulldowns, + int *num_fields +); + +W32EXPORT int USERD_get_var_extract_gui_defaults( + char **toggle_Title, /* [num_toggles][Z_LEN_GUI_TITLE_STR] */ + int *toggle_default_status, /* [num_toggles] */ + char **pulldown_Title, /* [num_pulldowns][Z_LEN_GUI_TITLE_STR] */ + int *pulldown_number_in_list, /* [num_pulldowns] */ + int *pulldown_default_selection, /* [num_pulldowns] */ + char ***pulldown_item_strings, /* [num_pulldowns][Z_MAX_NUM_GUI_PULL_ITEMS][Z_LEN_GUI_PULL_STR] */ + char **field_Title, /* [num_fields][Z_LEN_GUI_TITLE_STR] */ + char **field_user_string /* [num_fields][Z_LEN_GUI_FIELD_STR] */ +); + +W32EXPORT void USERD_set_var_extract_gui_data( + int *toggle, /* [num_toggle] */ + int *pulldown, /* [num_pulldown] */ + char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR] */ ); + +/* -------------------- + * xy-query data routines + * -------------------- */ +W32EXPORT int USERD_get_num_xy_queries(void); + +W32EXPORT int USERD_get_xy_query_info( + int query_num, + char *query_name, + char *query_xtitle, + char *query_ytitle, + int *query_num_pairs); + +W32EXPORT int USERD_get_xy_query_data( + int query_num, + int num_vals, + float *x_vals, + float *y_vals); + + +/* This routine added so the reader can know if we are at the "right" side of + * an interval - namely, interpolation between steps is being done in EnSight + * (It can be in any version of EnSight) + *----------------------------------------------------------------------------*/ +W32EXPORT void +USERD_set_right_side( void ); + +/*--------------------------------------------- + * Routines that get the geometry in buffers, + * used for Unstructured Auto Distribute + * (Optional) + *---------------------------------------------*/ +W32EXPORT int +USERD_get_part_coords_in_buffers(int part_number, + float **coord_array, + int first, + int n_beg, + int n_end, + int buffer_size, + int *num_returned); + +W32EXPORT int +USERD_get_part_node_ids_in_buffers(int part_number, + int *nodeid_array, + int first, + int n_beg, + int n_end, + int buffer_size, + int *num_returned); + +W32EXPORT int +USERD_get_part_elements_by_type_in_buffers(int part_number, + int element_type, + int **conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned); + +W32EXPORT int +USERD_get_part_element_ids_by_type_in_buffers(int part_number, + int element_type, + int *elemid_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned); +W32EXPORT int +USERD_get_var_by_component_in_buffers(int which_variable, + int which_part, + int var_type, + int which_type, + int imag_data, + int component, + float *var_array, + int first, + int ne_beg, + int ne_end, + int buffer_size, + int leftside, + int *num_returned); + +W32EXPORT int +USERD_get_nsided_conn_in_buffers(int part_number, + int *num_nodes_per_elem_array, + int *nsided_conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned); + +W32EXPORT int +USERD_get_nfaced_conn_in_buffers(int part_number, + int *nfaced_fpe_arrray, + int *nfaced_npf_arrray, + int *nfaced_conn_array, + int first, + int e_beg, + int e_end, + int buffer_size, + int *num_returned); /*----------------------- @@ -100,30 +295,30 @@ USERD_bkup(FILE *archive_file, *-----------------------*/ #if defined USERD_API_100 -W32IMPORT int +W32EXPORT int USERD_get_number_of_global_nodes( void ); -W32IMPORT int +W32EXPORT int USERD_get_global_coords(CRD *coord_array); -W32IMPORT int +W32EXPORT int USERD_get_global_node_ids(int *nodeid_array); -W32IMPORT int +W32EXPORT int USERD_get_element_connectivities_for_part(int part_number, int **conn_array[Z_MAXTYPE]); -W32IMPORT int +W32EXPORT int USERD_get_element_ids_for_part(int part_number, int *elemid_array[Z_MAXTYPE]); -W32IMPORT int +W32EXPORT int USERD_get_vector_values(int which_vector, int which_part, int which_type, float *vector_array); -W32IMPORT int +W32EXPORT int USERD_get_part_build_info(int *part_id, int *part_types, char *part_descriptions[Z_BUFL], @@ -131,25 +326,25 @@ USERD_get_part_build_info(int *part_id, int *ijk_dimensions[3], int *iblanking_options[6]); -W32IMPORT int +W32EXPORT int USERD_get_scalar_values(int which_scalar, int which_part, int which_type, float *scalar_array); -W32IMPORT int +W32EXPORT int USERD_get_variable_info(char **var_description, char **var_filename, int *var_type, int *var_classify); -W32IMPORT int +W32EXPORT int USERD_get_description_lines(int which_type, int which_var, char line1[Z_BUFL], char line2[Z_BUFL]); -W32IMPORT int +W32EXPORT int USERD_get_variable_value_at_specific(int which_var, int which_node_or_elem, int which_part, @@ -157,15 +352,15 @@ USERD_get_variable_value_at_specific(int which_var, int time_step, float values[3]); -W32IMPORT float +W32EXPORT float USERD_get_constant_value(int which_var); -W32IMPORT int +W32EXPORT int USERD_get_solution_times(float *solution_times); -W32IMPORT void +W32EXPORT void USERD_set_time_step(int time_step); -W32IMPORT int +W32EXPORT int USERD_get_number_of_time_steps(void); #endif @@ -176,30 +371,30 @@ USERD_get_number_of_time_steps(void); *----------------------*/ #if !defined USERD_API_100 -W32IMPORT int +W32EXPORT int USERD_get_part_coords(int part_number, float **coord_array); -W32IMPORT int +W32EXPORT int USERD_get_part_node_ids(int part_number, int *nodeid_array); -W32IMPORT int +W32EXPORT int USERD_get_part_elements_by_type(int part_number, int element_type, int **conn_array); -W32IMPORT int +W32EXPORT int USERD_get_part_element_ids_by_type(int part_number, int element_type, int *elemid_array); -W32IMPORT int +W32EXPORT int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME]); -W32IMPORT int +W32EXPORT int USERD_get_reader_release(char version_number[Z_MAX_USERD_NAME]); -W32IMPORT int +W32EXPORT int USERD_get_var_by_component(int which_variable, int which_part, int var_type, @@ -208,15 +403,15 @@ USERD_get_var_by_component(int which_variable, int component, float *var_array); -W32IMPORT int +W32EXPORT int USERD_get_maxsize_info(int *max_number_of_nodes, int *max_number_of_elements[Z_MAXTYPE], int *max_ijk_dimensions[3]); -W32IMPORT void +W32EXPORT void USERD_exit_routine( void ); -W32IMPORT int +W32EXPORT int USERD_get_gold_variable_info(char **var_description, char **var_filename, int *var_type, @@ -226,17 +421,17 @@ USERD_get_gold_variable_info(char **var_description, float *var_freq, int *var_contran, int *var_timeset); -W32IMPORT int +W32EXPORT int USERD_get_model_extents( float extents[6] ); -W32IMPORT int +W32EXPORT int USERD_get_descrip_lines(int which_type, int which_var, int imag_data, char line1[Z_BUFL], char line2[Z_BUFL]); -W32IMPORT int +W32EXPORT int USERD_get_var_value_at_specific(int which_var, int which_node_or_elem, int which_part, @@ -245,40 +440,40 @@ USERD_get_var_value_at_specific(int which_var, float values[3], int imag_data); -W32IMPORT float +W32EXPORT float USERD_get_constant_val(int which_var, int imag_data); -W32IMPORT int +W32EXPORT int USERD_get_geom_timeset_number(void); -W32IMPORT int +W32EXPORT int USERD_get_number_of_timesets(void); -W32IMPORT int +W32EXPORT int USERD_get_timeset_description(int timeset_number, char timeset_description[Z_BUFL]); -W32IMPORT int +W32EXPORT int USERD_get_sol_times(int timeset_number, float *solution_times); -W32IMPORT void +W32EXPORT void USERD_set_time_set_and_step(int timeset_number, int time_step); -W32IMPORT int +W32EXPORT int USERD_get_num_of_time_steps(int timeset_number); -W32IMPORT int +W32EXPORT int USERD_get_border_availability(int part_number, int number_of_elements[Z_MAXTYPE]); -W32IMPORT int +W32EXPORT int USERD_get_border_elements_by_type(int part_number, int element_type, int **conn_array, short *parent_element_type, int *parent_element_num); -W32IMPORT void +W32EXPORT void USERD_set_server_number(int serv_num, int tot_servs); @@ -288,14 +483,14 @@ USERD_set_server_number(int serv_num, /*---------------------- * New For Version 2.010 *----------------------*/ -#if defined USERD_API_201 || defined USERD_API_202 || defined USERD_API_203 -W32IMPORT int +#if defined USERD_API_201 || defined USERD_API_202 || defined USERD_API_203 || defined USERD_API_204 || defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 +W32EXPORT int USERD_get_ghosts_in_model_flag( void ); -W32IMPORT int +W32EXPORT int USERD_get_ghosts_in_block_flag(int block_number); -W32IMPORT int +W32EXPORT int USERD_get_block_ghost_flags(int block_number, int *ghost_flags); #endif @@ -303,9 +498,9 @@ USERD_get_block_ghost_flags(int block_number, /*-------------------------- * Modified at Version 2.030 *--------------------------*/ -#if defined USERD_API_201 || defined USERD_API_202 +#if defined USERD_API_200 || defined USERD_API_201 || defined USERD_API_202 -W32IMPORT int +W32EXPORT int USERD_get_gold_part_build_info(int *part_id, int *part_types, char *part_descriptions[Z_BUFL], @@ -315,8 +510,8 @@ USERD_get_gold_part_build_info(int *part_id, int *iblanking_options[6]); #endif -#if defined USERD_API_203 -W32IMPORT int +#if defined USERD_API_203 || defined USERD_API_204 || defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 +W32EXPORT int USERD_get_gold_part_build_info(int *part_id, int *part_types, char *part_descriptions[Z_BUFL], @@ -330,30 +525,30 @@ USERD_get_gold_part_build_info(int *part_id, /*---------------------- * New For Version 2.030 *----------------------*/ -#if defined USERD_API_203 -W32IMPORT int +#if defined USERD_API_203 || defined USERD_API_204 || defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 +W32EXPORT int USERD_get_number_of_material_sets( void ); -W32IMPORT int +W32EXPORT int USERD_get_matf_set_info(int *mat_set_ids, char **mat_set_name); -W32IMPORT int +W32EXPORT int USERD_get_number_of_materials( int set_index ); -W32IMPORT int +W32EXPORT int USERD_get_matf_var_info(int set_index, int *mat_ids, char **mat_desc); -W32IMPORT int +W32EXPORT int USERD_size_matf_data(int set_index, int part_id, int wtyp, int mat_type, int *matf_size ); -W32IMPORT int +W32EXPORT int USERD_load_matf_data( int set_index, int part_id, int wtyp, @@ -361,22 +556,180 @@ USERD_load_matf_data( int set_index, int *ids_list, float *val_list ); -W32IMPORT int +W32EXPORT int USERD_get_nsided_conn( int part_number, int *nsided_conn_array ); -W32IMPORT int +W32EXPORT int USERD_get_nfaced_nodes_per_face( int part_number, int *nfaced_npf_array ); -W32IMPORT int +W32EXPORT int USERD_get_nfaced_conn( int part_number, int *nfaced_conn_array ); +#endif + +/*---------------------- + * New For Version 2.040 + *----------------------*/ +#if defined USERD_API_204 || defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 + +W32EXPORT int +USERD_get_uns_failed_params( + char *fail_var_name, /* variable name to be used in failure + must be scalar, per elem */ + float *threshold_val1, /* number to compare for failure */ + float *threshold_val2, /* number to compare for failure */ + int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN, + Z_EQUAL_TO */ + int *logic_criteria2 + + ); #endif +/*---------------------- +** New For Version 2.050 +**----------------------*/ +#if defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 + +W32EXPORT int +USERD_get_number_of_species( int set_index ); + +W32EXPORT int +USERD_get_matsp_info(int set_index, + int *sp_ids, + char **sp_desc, + int *sppermatcnt, + int *sppermatlis); + +W32EXPORT int +USERD_rigidbody_existence( void ); + +#endif + +/*-------------------------------------------- + * New at 2.05, but modified for Version 2.080 + *-------------------------------------------- */ +#if defined USERD_API_205 || defined USERD_API_206 || defined USERD_API_207 +W32EXPORT int +USERD_rigidbody_values(int part_number, + float values[10]); +#endif + +#if defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 +W32EXPORT int +USERD_rigidbody_values(int part_number, + float values[14]); +#endif + + + + +/*---------------------- +** New For Version 2.060 +**----------------------*/ +#if defined USERD_API_206 || defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 + +W32EXPORT int +USERD_get_structured_reader_cinching( void ); + +W32EXPORT int +USERD_set_block_range_and_stride(int file_pn, + int mini, int maxi, int stepi, + int minj, int maxj, int stepj, + int mink, int maxk, int stepk); +#endif +/*---------------------- +** New For Version 2.070 +**----------------------*/ +#if defined USERD_API_207 || defined USERD_API_208 || defined USERD_API_209 || defined USERD_API_210 + +/* non-optional functions go here */ + +#endif + +/* This is optional; defaults to 'Set file' and 'Set results' if not + * defined. If 'two_fields' is true, then both labels must have a + * non-NULL string otherwise the defaults will be used. + */ +W32EXPORT void +USERD_set_filename_button_labels(char filename_label_1[Z_MAX_USERD_NAME], + char filename_label_2[Z_MAX_USERD_NAME]); + +/* This is optional; defaults to TRUE if not defined. */ +W32EXPORT int +USERD_prefer_auto_distribute(void); + + + +/*---------------------- +** New For Version 2.090 +**----------------------*/ +#if defined USERD_API_209 || defined USERD_API_210 + +/* non-optional functions go here */ + +#endif + +/* These are optional */ +W32EXPORT int +USERD_get_vglyph_counts(int *num_vglyph_vectors, + int *num_vglyph_timelines); + +W32EXPORT int +USERD_get_vglyph_timeline_info(int vtl, + int *id, + int *numtimes, + int *before, + int *amidst, + int *after); + +W32EXPORT int +USERD_get_vglyph_timeline_times(int vtl, + float *times); + +W32EXPORT int +USERD_get_vglyph_vector_info(int vg, + int *id, + char *description, + int *type, + int *time_condition, + int *time_line, + int *part, + int *nidloc, + int *eidloc); + +W32EXPORT int +USERD_get_vglyph_vector_values(int vg, + float **values); + +W32EXPORT int +USERD_get_vglyph_vector_xyzloc(int vg, + float **xyzloc); + +/*---------------------- +** New For Version 2.100 +**----------------------*/ +#if defined USERD_API_210 + +W32EXPORT int +USERD_get_mat_scalars_desc(int set_index, + char **mesv_desc); +#endif + +/* These are optional */ +W32EXPORT int +USERD_get_matf_set_type(int set_index); + +/* special, optional functions */ +W32EXPORT void +USERD_reset_routine(void); + /*--------------------------------------------------------------------*/ #endif /*GLOBAL_EXTERN_PROTO_H*/ diff --git a/applications/utilities/postProcessing/graphics/ensightFoamReader/libuserd.C b/applications/utilities/postProcessing/graphics/ensightFoamReader/libuserd.C index 0a48995579..e65381a637 100644 --- a/applications/utilities/postProcessing/graphics/ensightFoamReader/libuserd.C +++ b/applications/utilities/postProcessing/graphics/ensightFoamReader/libuserd.C @@ -52,6 +52,7 @@ Description extern "C" { +#include "USERD_API.H" #include "global_extern.h" // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * // @@ -104,6 +105,7 @@ extern "C" #include "USERD_exit_routine.H" #include "USERD_get_model_extents.H" #include "USERD_get_reader_version.H" +#include "USERD_get_reader_release.H" #include "USERD_get_number_timesets.H" #include "USERD_get_timeset_description.H" #include "USERD_get_geom_timeset_number.H" @@ -130,7 +132,7 @@ extern "C" //********************************************************************** //====================================================================== -// STRUCTURED DATA STUFF - not used in foam +// STRUCTURED DATA STUFF - not used in OpenFOAM //====================================================================== //**********************************************************************