[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.05
| blob | b92bb1c988a6b4b337f05feefcd9ddb4f3f9c892 |
1 README_USERD_2.05
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.05)
5 --------------------------------------
6 A user defined reader capability is included in EnSight which can allow
7 otherwise unsupported structured or unstructured data to be read. The user
8 defined reader capability utilizes dynamic shared libraries composed of
9 routines defined in this document but produced by you, the user, (or some
10 third party). This capability is currently available for dec, ibm, hp, sgi,
11 sun, linux, alpha linux, and NT servers.
13 You should refer to beginning of README_USERD_2.0 and/or README_1.0_to_2.0
14 for a discussion of the differences between API 1.0 and API 2.*.
16 ***>> API 2.05 additional capabilities (beyond API 2.04):
17 Routines to handle material species.
18 USERD_get_number_of_species
19 USERD_get_matsp_info
21 Routines to handle variable extraction parameters after a read, and then
22 update the variables accordingly. Similar to the extra GUI capabilities
23 (which are processed before a read). (Can actually be added to pre-2.05 readers)
24 USERD_get_var_extract_gui_numbers
25 USERD_get_var_extract_gui_defaults
26 USERD_set_var_extract_gui_data
28 Routines to obtain rigid body values from a reader.
29 (Routines were added - EnSight is now using for Nastran and STL readers
30 with Dynasty rigid body motion data file)
31 USERD_rigidbody_existence
32 USERD_rigidbody_values
34 Routine that lets reader know when EnSight is getting the right side of a time
35 interval for variable interpolation between steps. Not generally needed for
36 most readers - however, may be needed for those that implement rigid body, and
37 wish to cache left and right timespan information for interpolation within the
38 reader itself. (Can actually be added to pre-2.05 readers)
39 USERD_set_right_side
42 ***>> API 2.04 additional capabilities (beyond API 2.03):
43 Routines to handle failed elements. Basically
44 a.One routine to return a flag indicating the existence of
45 failed elements in at least one part in at least one
46 timestep in the model.
47 b.A second routine to return a matrix of flags indexed by part and
48 element type indicating which parts and element types have failed
49 elements at the current time step.
50 c.Finally a third routine to return an array of flags for a given
51 part and element type that is number of elements of that type long
52 indicating which elements have failed, and which have not failed.
55 ***>> API 2.03 additional capabilities (beyond API 2.01):
56 1. Routines to handle materials
57 2. Routines to handle nsided and nfaced elements
58 3. Modified routine to handle structured ranges
61 ****************************************************************************
62 Note: The dummy_gold reader, the Ensight Gold example reader, the
63 ABAQUS_ODB reader and the LS-DYNA reader have been moved to
64 this 2.04 API level.
65 ****************************************************************************
68 The process for producing a user defined reader is:
69 ---------------------------------------------------
70 1. Write code for all pertinent routines in the library (Unless someone else
71 has done this for you).
73 This is of course where the work is done by the user. The word
74 "pertinent" is used because depending on the nature of the data, some
75 of the routines in the library may be dummy routines.
77 The source code for a dummy_gold library and for various other
78 working or sample libraries is copied from the installation CD during
79 installation. These will be located in directories under:
81 $CEI_HOME/ensight76/user_defined_src/readers
83 examples:
84 --------
85 Basic dummy_gold routines provide skeleton for a new reader
86 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
88 Sample library which reads unstructured binary EnSight Gold data
89 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
91 You may find it useful to place your library source in this area as
92 well, but are not limited to this location.
94 * ===> The descriptions of each library routine and the order that the
95 routines are called, which is provided in this file, along with
96 the example libraries, should make it possible for you to produce
97 code for your own data reader.
100 2. Produce the dynamic shared library.
102 This is a compiling and loading process which varies according to
103 the type of machine you are on. In the user-defined-reader source
104 tree we have tried to isolate the machine dependent parts of the
105 build process using a set of files in the 'config' directory. In this
106 directory there is a configuration file for each platform on which
107 EnSight is supported. Before you can compile the installed readers
108 you should run the script called 'init' in the config directory.
110 i.e. (for UNIX)
111 cd config
112 ./init sgi_6.5_n64
113 cd ..
114 make
116 If you are compiling for Windows NT, there are two options. If you
117 have the Cygwin GNU utilities installed, you can use GNU make as for
118 Unix. Otherwise, there is a script called makeall.cmd which will
119 build all of the readers using nmake. The Makefiles in each reader
120 directory will work using either make or nmake.
122 i.e. (WIN32 Cygwin) (using nmake)
123 cd config cd config
124 sh init win32 cp win32 config
125 cd .. cd ..
126 mkdir lib
127 make makeall.cmd
129 If you have platform-specific portions of code in your reader, the
130 build system defines a set of flags which can be used within
131 #ifdef ... #endif regions in your source, as shown in the table
132 below.
134 Because the readers are now dynamically opened by EnSight, you may
135 have to include dependent libraries on your link-line to avoid having
136 unresolved symbols. If you are having problems with a reader, start
137 ensight as "ensight7 -readerdbg" and you will get feedback on any
138 problems encountered in loading a reader. If there are unresolved
139 symbols, you need to find the library which contains the missing
140 symbols and link it into your reader by adding it to the example
141 link commands below.
143 If you choose to use a different build environment for your reader,
144 you should take care to use compatible compilation flags to ensure
145 compatibilty with the EnSight executables, most notably on the SGI
146 and HP-UX 11.0 platforms, which should use the following flags:
148 sgi_6.2_o32: -mips2
149 sgi_6.2_n64: -mips4 -64
150 sgi_6.5_n32: -mips3
151 sgi_6.5_n64: -mips4 -64
152 hp_11.0_32: +DA2.0
153 hp_11.0_64: +DA2.0W
155 ______________________________________________________________________
156 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
157 | TYPE |------------------------------------------------------------|
158 | | LD COMMAND USED IN MAKEFILE |
159 ======================================================================
160 ______________________________________________________________________
161 | sgi | -DSGI | libuserd-X.so |
162 | |------------------------------------------------------------|
163 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
164 ----------------------------------------------------------------------
165 ______________________________________________________________________
166 | hp | -DHP | libuserd-X.sl |
167 | |------------------------------------------------------------|
168 | | ld -b -o libuserd-X.sl libuserd-X.o |
169 ----------------------------------------------------------------------
170 ______________________________________________________________________
171 | sun | -DSUN | libuserd-X.so |
172 | |------------------------------------------------------------|
173 | | ld -G -o libuserd-X.so libuserd-X.o |
174 ----------------------------------------------------------------------
175 ______________________________________________________________________
176 | dec | -DDEC | libuserd-X.so |
177 | |------------------------------------------------------------|
178 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
179 ----------------------------------------------------------------------
180 ______________________________________________________________________
181 | linux | -DLINUX | libuserd-X.so |
182 | |------------------------------------------------------------|
183 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
184 ----------------------------------------------------------------------
185 ______________________________________________________________________
186 | alpha | -DALINUX | libuserd-X.so |
187 | linux |------------------------------------------------------------|
188 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
189 ----------------------------------------------------------------------
190 ______________________________________________________________________
191 | ibm | -DIBM | libuserd-X.so |
192 | |------------------------------------------------------------|
193 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
194 ----------------------------------------------------------------------
196 Once you have created your library, you should place it in a directory
197 of your choice or in the standard reader location:
199 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
201 For example, if you created a reader for "mydata", you should create
202 the reader libuserd-mydata.so and place the file in your own reader
203 directory (see section 3 below) or in the standard location:
205 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
208 3. By default EnSight will load all readers found in the directory:
210 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
212 Files with names "libuserd-X.so" (where X is a name unique to the reader)
213 are assumed to be user-defined readers.
215 There are two methods which can be used to supplement the default
216 behavior.
218 (1) A feature which is useful for site-level or user-level configuration
219 is the optional environment variable $ENSIGHT7_READER. This
220 variable directs EnSight to load all readers in the specified reader
221 directory (you should probably specify a full path) before loading
222 the built-in readers. If the same reader exists in both directories
223 (as determined by the name returned by USERD_get_name_of_reader(),
224 NOT by the filename), the locally configured reader will take
225 precedence.
227 (2) A useful feature for end-users is the use of the libuserd-devel
228 reader. EnSight will search for a reader named libuserd-devel.so
229 (.sl for HP or .dll for NT). This reader can exist anywhere in the
230 library path (see below) of the user. This is useful for an
231 individual actively developing a reader because the existence of a
232 libuserd-devel library will take precedence over any other library
233 which returns the same name from USERD_get_name_of_reader().
235 As an example, a site may install commonly used readers in a common
236 location, and users can set the ENSIGHT7_READER variable to access them:
238 setenv ENSIGHT7_READER /usr/local/lib/e7readers
240 A user working on a new reader may compile the reader and place it in
241 a directory specified by the library path:
243 cp libuserd-myreader.so ~/lib/libuserd-devel.so
244 setenv <librarypath> ~/lib:$<librarypath>
246 The user is responsible for correctly configuring the library path
247 variable in order to make use of the libuserd-devel feature. The
248 library environment variables used are:
250 Machine type Environment variable to set
251 ------------ ---------------------------
252 sgi LD_LIBRARY_PATH
253 dec LD_LIBRARY_PATH
254 sun LD_LIBRARY_PATH
255 linux LD_LIBRARY_PATH
256 alpha linux LD_LIBRARY_PATH
257 hp SHLIB_PATH
258 ibm LIBPATH
260 As always, EnSight support is available if you need it.
262 -------------------------------
263 Quick Index of Library Routines
264 -------------------------------
266 Generally Needed for UNSTRUCTURED data
267 --------------------------------------
268 USERD_get_part_coords part's node coordinates
269 USERD_get_part_node_ids part's node ids
270 USERD_get_part_elements_by_type part's element connectivites
271 USERD_get_part_element_ids_by_type part's element ids
274 Generally Needed for BLOCK data
275 --------------------------------------
276 USERD_get_block_coords_by_component block coordinates
277 USERD_get_block_iblanking block iblanking values
278 USERD_get_ghosts_in_block_flag block ghost cell existence?
279 USERD_get_block_ghost_flags block ghost cell flags
281 These routines, which formerly were only for unstructured data, will now
282 also be called for structured data if you specify that ids will be given
283 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
284 ------------------------------------------------------------------------------
285 USERD_get_part_node_ids part's node ids
286 USERD_get_part_element_ids_by_type part's element ids
289 Generally needed for either or both kinds of data
290 -------------------------------------------------
291 USERD_get_name_of_reader name of reader for GUI
292 USERD_get_reader_version provide reader version number
293 USERD_get_reader_descrip provide GUI more description (optional)
295 USERD_set_filenames filenames entered in GUI
296 USERD_set_server_number server which of how many
298 USERD_get_number_of_timesets number of timesets
299 USERD_get_timeset_description description of timeset
300 USERD_get_geom_timeset_number timeset # to use for geom
302 USERD_get_num_of_time_steps number of time steps
303 USERD_get_sol_times solution time values
304 USERD_set_time_set_and_step current timeset and time step
306 USERD_get_gold_part_build_info Gets the info needed for part building process
307 USERD_get_changing_geometry_status changing geometry?
308 USERD_get_node_label_status node labels?
309 USERD_get_element_label_status element labels?
310 USERD_get_model_extents provide model bounding extents
311 USERD_get_number_of_files_in_dataset number of files in model
312 USERD_get_dataset_query_file_info info about each model file
313 USERD_get_descrip_lines file associated description lines
314 USERD_get_number_of_model_parts number of model parts
315 USERD_get_part_build_info part/block type/descrip etc.
316 USERD_get_maxsize_info part/block allocation maximums
317 USERD_get_ghosts_in_model_flag model contains ghost cells?
318 USERD_get_nsided_conn Gets the element connectivities for nsided
319 elements. (utilizes the number of nodes
320 per element obtained in
321 USERD_get_part_elements_by_type)
322 USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced
323 elements (utilizes the number of faces
324 per element obtained in
325 USERD_get_part_elements_by_type)
326 USERD_get_nfaced_conn Gets the element connectivities for nfaced
327 elements (utilizes the number of nodes
328 per face obtained in
329 USERD_get_nfaced_nodes_per_face)
332 USERD_get_border_availability part border provided?
333 USERD_get_border_elements_by_type part border conn and parent info
335 USERD_get_number_of_variables number of variables
336 USERD_get_gold_variable_info variable type/descrip etc.
337 USERD_get_var_by_component part or block variable values
338 USERD_get_constant_val constant variable's value
339 USERD_get_var_value_at_specific node's or element's variable value over time
340 USERD_stop_part_building cleanup after part build routine
342 USERD_get_number_of_material_sets Gets the number of material sets
343 USERD_get_matf_set_info Gets the material set indices and names
344 USERD_get_number_of_materials Gets the number of materials
345 USERD_get_matf_var_info Gets the material indices and descriptions
346 USERD_size_matf_data Gets the length of either the
347 material ids list,
348 mixed-material ids list, or
349 mixed-material values list
350 USERD_load_matf_data Gets the material ids list,
351 mixed-material ids list, or
352 mixed-material values list
354 USERD_bkup archive routine
356 USERD_exit_routine cleanup upon exit routine
359 ---------------------------
360 Optional Extra GUI Info
361 Adds Toggle(s), Pulldown(s) Field(s)
362 that can be used for additonal input
363 ---------------------------
364 USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields
365 USERD_get_extra_gui_defaults Gets the default values for the GUI members
366 USERD_set_extra_gui_data Returns the answers provided by the user
368 USERD_rigidbody_existence Returns whether rigid body transformation
369 data exists for the model.
370 USERD_rigidbody_values Returns the euler and location values for a
371 given part
373 USERD_set_right_side Simply informs the reader when the time set
374 is for the right side of a time span during
375 variable interpolation between time steps.
377 New at 2.04
378 -----------
380 /* ----------------------------------------------------------
381 *
382 * Failure criteria in LS-DYNA
383 * if fail flag == threshold_val1 (0.0) then element fails
384 * logic_criteria2 not used
385 * threshold_val2 not used
386 * threshold_operator2 not used
387 * Return (Z_ERR) if this is not used.
388 * Return Z_OK if failed element feature should be used
389 *
390 * threshold_operator1 & 2 can be one of the following
391 * Z_ELE_FAILED_NONE, - disables checking
392 * Z_ELE_FAILED_GREATER, - greater than
393 * Z_ELE_FAILED_LESS, - less than
394 * Z_ELE_FAILED_EQUAL, - equal
395 * Z_ELE_FAILED_NOT_EQUAL, - not equal
396 * Z_ELE_FAILED_MANY - not used
397 *
398 * logic_criteria2
399 * Z_ELE_FAILED_LOGIC_NONE,
400 * Z_ELE_FAILED_LOGIC_AND,
401 * Z_ELE_FAILED_LOGIC_OR,
402 * Z_ELE_FAILED_LOGIC_MANY
403 *
404 * ---------------------------------------------------------- */
406 int USERD_get_uns_failed_params(
407 char *fail_var_name, /* variable name to be used in failure
408 must be scalar, per elem */
409 float *threshold_val1, /* number to compare for failure */
410 float *threshold_val2, /* number to compare for failure */
411 int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN,
412 Z_EQUAL_TO */
413 int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN,
414 Z_EQUAL_TO */
415 int *logic_criteria2
418 -------------------------
419 Order Routines are called
420 -------------------------
422 The various main operations are given basically in the order they will
423 be performed. Within each operation, the order the routines will be
424 called is given.
426 1. Setting name in the gui, and specifying one or two input fields
428 USERD_get_name_of_reader
429 USERD_get_reader_descrip (optional)
430 USERD_get_extra_gui_numbers (optional)
431 USERD_get_extra_gui_defaults (optional)
433 2. Getting the reader version (also distinguishes between API's)
435 USERD_get_reader_version
437 3. Setting filenames and getting timeset and time info
439 USERD_set_server_number
440 USERD_set_extra_gui_data (optional)
441 USERD_set_filenames
442 USERD_get_number_of_timesets
443 USERD_get_geom_timeset_number
445 for each timeset:
446 USERD_get_timeset_description
447 USERD_get_num_of_time_steps
448 USERD_get_sol_times
450 USERD_set_time_set_and_step
452 4. Gathering info for part builder
454 USERD_set_time_set_and_step
455 USERD_get_changing_geometry_status
456 USERD_get_node_label_status
457 USERD_get_element_label_status
458 USERD_get_number_of_files_in_dataset
459 USERD_get_dataset_query_file_info
460 USERD_get_descrip_lines (for geometry)
461 USERD_get_number_of_model_parts
462 USERD_get_uns_failed_model_flag
463 USERD_get_gold_part_build_info
464 USERD_get_uns_failed_etype_flags
465 USERD_get_ghosts_in_model_flag
466 USERD_get_maxsize_info
467 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
468 USERD_get_model_extents OR (for model extents)
469 USERD_get_part_coords AND/OR
470 USERD_get_block_coords_by_component
472 5. Gathering Variable info
474 USERD_get_number_of_variables
475 USERD_get_gold_variable_info
477 6. Part building (per part created)
479 both unstructured and structured:
480 --------------------------------
481 USERD_set_time_set_and_step
483 if unstructured part:
484 --------------------
485 USERD_get_part_element_ids_by_type
486 USERD_get_part_elements_by_type
488 If any nsided elements:
490 USERD_get_nsided_conn
492 If any nfaced elements:
494 USERD_get_nfaced_nodes_per_face
495 USERD_get_nfaced_conn
497 USERD_get_part_coords
498 USERD_get_part_node_ids
499 USERD_get_uns_failed_elist_flags
501 else if structured part:
502 -----------------------
503 USERD_get_block_iblanking
504 USERD_get_block_coords_by_component
505 USERD_get_block_ghost_flags (If ghost cells in part)
506 USERD_get_part_node_ids (If node ids given)
507 USERD_get_part_element_ids_by_type (If element ids given)
509 both again:
510 ----------
511 USERD_get_border_availability (If border representation
512 USERD_get_border_elements_by_type is selected)
514 USERD_stop_part_building (only once when part builder
515 dialog is closed)
517 7. Loading Variables
519 constants:
520 ---------
521 USERD_set_time_set_and_step
522 USERD_get_constant_val
524 scalars/vectors/tensors:
525 ------------------------
526 USERD_get_descrip_lines
527 USERD_set_time_set_and_step
528 USERD_get_var_by_component
530 8. Changing geometry
532 changing coords only (per part):
533 --------------------
534 USERD_set_time_set_and_step
535 USERD_get_descrip_lines
536 USERD_get_part_coords
537 USERD_get_uns_failed_model_flag
538 USERD_get_uns_failed_etype_flags
539 USERD_get_uns_failed_elist_flags
540 USERD_get_block_coords_by_component
542 changing connectivity (per part):
543 ---------------------
544 USERD_set_time_set_and_step
545 USERD_get_descrip_lines
546 USERD_get_number_of_model_parts
547 USERD_get_uns_failed_model_flag
548 USERD_get_gold_part_build_info
549 USERD_get_uns_failed_etype_flags
550 USERD_get_ghosts_in_model_flag
551 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
552 USERD_get_model_extents OR
553 USERD_get_part_coords AND/OR
554 USERD_get_block_coords_by_component
555 USERD_get_part_element_ids_by_type
556 USERD_get_part_elements_by_type
557 USERD_get_part_coords
558 USERD_get_part_node_ids
559 USERD_get_uns_failed_elist_flags
560 USERD_get_block_iblanking
561 USERD_get_block_coords_by_component
562 USERD_get_block_ghost_flags (If ghost cells in part)
563 USERD_get_part_node_ids (If node ids given)
564 USERD_get_part_element_ids_by_type (If element ids given)
566 USERD_get_border_availability (If border representation
567 USERD_get_border_elements_by_type is selected)
570 9. Node or Element queries over time
572 USERD_get_var_value_at_specific
574 10. To see if materials in the model
576 USERD_get_number_of_material_sets
577 USERD_get_matf_set_info
579 If any material sets in the model (calls these once per material set):
580 USERD_get_number_of_materials
581 USERD_get_matf_var_info
583 For each elment type of each part containing material ids, calls:
584 USERD_size_matf_data
585 USERD_load_matf_data
587 If there are any elements with mixed materials, when a domain or
588 interface is created, calls these again per part:
590 USERD_size_matf_data
591 USERD_load_matf_data
593 11. To modify the variable extraction parameters and have the variables
594 update accordingly.
596 USERD_get_var_extract_gui_numbers
597 USERD_get_var_extract_gui_defaults
598 USERD_set_var_extract_gui_data
602 -----------------------
603 Detailed Specifications
604 -----------------------
606 Include files:
607 --------------
608 The following header file is required in any file containing these library
609 routines.
611 #include "global_extern.h"
613 And it references:
615 #include "global_extern_proto.h"
619 *******************************************************************************
620 ****************************** Special Note ***********************************
621 *******************************************************************************
623 Make sure you use the proper define in the global_extern.h header file, namely:
624 #define USERD_API_204
626 Also, Make sure the api version in the USERD_get_reader_version routine is set
627 to "2.04" or larger.
629 Make sure your reader has access to the global_extern_proto.h This is a new
630 file which is accessed from the new global_extern.h
632 *******************************************************************************
633 *******************************************************************************
636 Basis of arrays:
637 ---------------
638 Unless explicitly stated otherwise, all arrays are zero based - in true C
639 fashion.
642 Global variables:
643 ----------------
644 You will generally need to have a few global variables which are shared by
645 the various library routines. The detailed specifications below have assumed
646 the following are available. (Their names describe their purpose, and they
647 will be used in helping describe the details of the routines below).
649 static int Numparts_available = 0;
650 static int Num_unstructured_parts = 0;
651 static int Num_structured_blocks = 0;
653 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
655 static int Num_timesets = 1;
656 static int Current_timeset = 1;
657 static int Geom_timeset_number = 1;
659 static int Num_time_steps[Z_MAXSETS] = 1;
660 static int Current_time_step = 0;
661 static int Num_variables = 0;
662 static int Num_dataset_files = 0;
664 static int Server_Number = 1; Which server of
665 static int Tot_Servers = 1; the total number of servers
669 _________________________________________
670 -----------------------------------------
671 Library Routines (in alphabetical order):
672 _________________________________________
673 -----------------------------------------
675 --------------------------------------------------------------------
676 USERD_bkup
678 Description:
679 -----------
680 This routine is called during the EnSight archive process. You can
681 use it to save or restore info relating to your user defined reader.
683 Specification:
684 -------------
685 int USERD_bkup(FILE *archive_file,
686 int backup_type)
688 Returns:
689 -------
690 Z_OK if successful
691 Z_ERR if not successful
693 Arguments:
694 ---------
695 (IN) archive_file = The archive file pointer
697 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
698 Z_REST_ARCHIVE for restoring archive
700 Notes:
701 -----
702 * Since EnSight's archive file is saved in binary form, you should
703 also do any writing to it or reading from it in binary.
705 * You should archive any variables, which will be needed for
706 future operations, that will not be read or computed again
707 before they will be needed. These are typically global
708 variables.
710 * Make sure that the number of bytes that you write on a save and
711 the number of bytes that you read on a restore are identical!!
713 * If any of the variables you save are allocated arrays, you must
714 do the allocations before restoring into them.
716 --------------------------------------------------------------------
717 USERD_exit_routine
719 Description:
720 -----------
721 This routine is called as EnSight is exiting. It can be used to clean
722 up anything needed - such as removing temporary files, etc. - or can simply
723 be a dummy.
725 Specification:
726 -------------
727 void USERD_exit_routine( void )
729 Arguments:
730 ---------
731 none
733 --------------------------------------------------------------------
734 USERD_get_block_coords_by_component
736 Description:
737 -----------
738 Get the coordinates of a given structured block, a component at a time.
740 Specification:
741 -------------
742 int USERD_get_block_coords_by_component(int block_number,
743 int which_component,
744 float *coord_array)
746 Returns:
747 -------
748 Z_OK if successful
749 Z_ERR if not successful
751 Arguments:
752 ---------
753 (IN) block_number = The block part number
754 (1-based index of part table, namely:
756 1 ... Numparts_available.
758 It is NOT the part_id that
759 is loaded in USERD_get_gold_part_build_info)
761 (IN) which_component = Z_COMPX if x component wanted
762 = Z_COMPY if y component wanted
763 = Z_COMPZ if z component wanted
765 (OUT) coord_array = 1D array containing x,y, or z
766 coordinate component of each node
768 (Array will have been allocated
769 i*j*k for the block long)
771 Notes:
772 -----
773 * Not called unless Num_structured_blocks is > 0
775 * Will be based on Current_time_step
779 --------------------------------------------------------------------
780 USERD_get_block_iblanking
782 Description:
783 -----------
784 Get the iblanking value at each node of a block (if the block is
785 iblanked).
787 Specification:
788 -------------
789 int USERD_get_block_iblanking(int block_number,
790 int *iblank_array)
792 Returns:
793 -------
794 Z_OK if successful
795 Z_ERR if not successful
797 Arguments:
798 ---------
799 (IN) block_number = The block part number
800 (1-based index of part table, namely:
802 1 ... Numparts_available.
804 It is NOT the part_id that
805 is loaded in USERD_get_gold_part_build_info)
807 (OUT) iblank_array = 1D array containing iblank value
808 for each node.
810 (Array will have been allocated
811 i*j*k for the block long)
813 possible values are: Z_EXT = exterior
814 Z_INT = interior
815 Z_BND = boundary
816 Z_INTBND = internal boundary
817 Z_SYM = symmetry plane
819 Notes:
820 -----
821 * Not called unless Num_structured_blocks is > 0 and you have
822 some iblanked blocks
824 * Will be based on Current_time_step
828 ----------------------------------------------------------------------
829 USERD_get_block_ghost_flags
831 Description:
832 -----------
833 Get the ghost_flags value at each element of a block containing ghost cells.
835 Specification:
836 -------------
837 int USERD_get_block_ghost_flags(int block_number,
838 int *ghost_flags)
839 Returns:
840 -------
841 Z_OK if successful
842 Z_ERR if not successful
844 Arguments:
845 ---------
846 (IN) block_number = The block number
847 (1-based index of part table, namely:
849 1 ... Numparts_available.
851 It is NOT the part_id that
852 is loaded in USERD_get_gold_part_build_info)
854 (OUT) ghost_flags = 1D array containing ghost flag value
855 for each block cell.
857 (Array will have been allocated
858 (i-1)*(j-1)*(k-1) for the block long)
860 possible values are: 0 = non-ghost cell (normal cell)
861 >0 = ghost cell
863 Notes:
864 -----
865 * This routine is new in the 2.01 API
867 * This will be based on Current_time_step
869 * Only called for structured "block" parts that have some ghost cells
870 as indicated by the USERD_get_ghost_in_block_flag. The model must
871 of course also have been indicated to have some ghost cells in the
872 USERD_get_ghost_in_model_flag routine.
874 * It is sufficient to set the value to be 1 to flag as a ghost cell,
875 but the value can be any non-zero value, so you could use it to
876 indicate which block or which server (for Server-of-server use) the
877 cell is actually in.
881 --------------------------------------------------------------------
882 USERD_get_border_availability
884 Description:
885 -----------
886 Finds out if border elements are provided by the reader for the
887 desired part, or will need to be computed internally by EnSight.
889 Specification:
890 -------------
891 int USERD_get_border_availability(int part_number,
892 int number_of_elements[Z_MAXTYPE])
894 Returns:
895 -------
896 Z_OK if border elements will be provided by the reader.
897 (number_of_elements array will be loaded and
898 USERD_get_border_elements_by_type will be called)
900 Z_ERR if border elements are not available - thus EnSight must compute.
901 (USERD_get_border_elements_by_type will not be called)
904 Arguments:
905 ---------
906 (IN) part_number = The part number
907 (1-based index of part table, namely:
909 1 ... Numparts_available.
911 It is NOT the part_id that
912 is loaded in USERD_get_gold_part_build_info)
914 (OUT) number_of_elements = 2D array containing number of
915 each type of border element in
916 the part.
917 ------------
918 Possible types are:
920 Z_POINT = point
921 Z_BAR02 = 2-noded bar
922 Z_BAR03 = 3-noded bar
923 Z_TRI03 = 3-noded triangle
924 Z_TRI06 = 6-noded triangle
925 Z_QUA04 = 4-noded quadrilateral
926 Z_QUA08 = 8-noded quadrilateral
928 Notes:
929 -----
930 * Only called if border representation is used.
932 * Will be based on Current_time_step
936 --------------------------------------------------------------------
937 USERD_get_border_elements_by_type
939 Description:
940 -----------
941 Provides border element connectivity and parent information.
943 Specification:
944 -------------
945 int USERD_get_border_elements_by_type(int part_number,
946 int element_type,
947 int **conn_array,
948 short *parent_element_type,
949 int *parent_element_num)
951 Returns:
952 -------
953 Z_OK if successful
954 Z_ERR if not successful
956 Arguments:
957 ---------
958 (IN) part_number = The part number
959 (1-based index of part table, namely:
961 1 ... Numparts_available.
963 It is NOT the part_id that
964 is loaded in USERD_get_gold_part_build_info)
966 (IN) element_type = One of the following (See global_extern.h)
967 Z_POINT node point element
968 Z_BAR02 2 node bar
969 Z_BAR03 3 node bar
970 Z_TRI03 3 node triangle
971 Z_TRI06 6 node triangle
972 Z_QUA04 4 node quad
973 Z_QUA08 8 node quad
975 (OUT) conn_array = 2D array containing connectivity
976 of each border element of the type.
978 (Array will have been allocated
979 num_of_elements of the type by
980 connectivity length of the type)
982 ex) If number_of_elements[Z_TRI03] = 25
983 number_of_elements[Z_QUA04] = 100
984 number_of_elements[Z_QUA08] = 30
985 as obtained in:
986 USERD_get_border_availability
988 Then the allocated dimensions available
989 for this routine will be:
990 conn_array[25][3] when called with Z_TRI03
992 conn_array[100][4] when called with Z_QUA04
994 conn_array[30][8] when called with Z_QUA08
996 (OUT) parent_element_type = 1D array containing element type of the
997 parent element (the one that the border
998 element is a face/edge of).
1000 (Array will have been allocated
1001 num_of_elements of the type long)
1003 (OUT) parent_element_num = 1D array containing element number of the
1004 parent element (the one that the border
1005 element is a face/edge of).
1007 (Array will have been allocated
1008 num_of_elements of the type long)
1011 Notes:
1012 -----
1013 * Not called unless USERD_get_border_availability returned Z_OK
1015 * Will be based on Current_time_step
1019 --------------------------------------------------------------------
1020 USERD_get_changing_geometry_status
1022 Description:
1023 -----------
1024 Gets the changing geometry status for the model
1026 Specification:
1027 -------------
1028 int USERD_get_changing_geometry_status( void )
1030 Returns:
1031 -------
1032 Z_STATIC if geometry does not change
1033 Z_CHANGE_COORDS if changing coordinates only
1034 Z_CHANGE_CONN if changing connectivity
1036 Arguments:
1037 ---------
1038 none
1040 Notes:
1041 -----
1042 * EnSight does not support changing number of parts. But the
1043 coords and/or the connectivity of the parts can change. Note that
1044 a part is allowed to be empty (number of nodes and elements equal
1045 to zero).
1048 --------------------------------------------------------------------
1049 USERD_get_constant_val
1051 Description:
1052 -----------
1053 Get the value of a constant at a time step
1055 Specification:
1056 -------------
1057 float USERD_get_constant_value(int which_var,
1058 int imag_data)
1060 Returns:
1061 -------
1062 Value of the requested constant variable
1064 Arguments:
1065 ---------
1066 (IN) which_var = The variable number
1068 (IN) imag_data = TRUE if want imaginary data value.
1069 FALSE if want real data value.
1071 Notes:
1072 -----
1073 * Will be based on Current_time_step
1077 --------------------------------------------------------------------
1078 USERD_get_dataset_query_file_info
1080 Description:
1081 -----------
1082 Get the information about files in the dataset. Used for the
1083 dataset query option within EnSight.
1085 Specification:
1086 -------------
1087 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
1089 Returns:
1090 -------
1091 Z_OK if successful
1092 Z_ERR if not successful
1094 Arguments:
1095 ---------
1096 (OUT) qfiles = Structure containing information about each file
1097 of the dataset. The Z_QFILES structure is defined
1098 in the global_extern.h file
1100 (The structure will have been allocated
1101 Num_dataset_files long, with 10 description
1102 lines per file).
1104 qfiles[].name = The name of the file
1105 (Z_MAXFILENP is the dimensioned length
1106 of the name)
1108 qfiles[].sizeb = The number of bytes in the file
1109 (Typically obtained with a call to the
1110 "stat" system routine) (Is a long)
1112 qfiles[].timemod = The time the file was last modified
1113 (Z_MAXTIMLEN is the dimensioned length
1114 of this string)
1115 (Typically obtained with a call to the
1116 "stat" system routine)
1118 qfiles[].num_d_lines = The number of description lines you
1119 are providing from the file. Max = 10
1121 qfiles[].f_desc[] = The description line(s) per file,
1122 qfiles[].num_d_lines of them
1123 (Z_MAXFILENP is the allocated length of
1124 each line)
1126 Notes:
1127 -----
1128 * If Num_dataset_files is 0, this routine will not be called.
1129 (See USERD_get_number_of_files_in_dataset)
1132 --------------------------------------------------------------------
1133 USERD_get_descrip_lines
1135 Description:
1136 -----------
1137 Get two description lines associated with geometry per time step,
1138 or one description line associated with a variable per time step.
1140 Specification:
1141 -------------
1142 int USERD_get_descrip_lines(int which_type,
1143 int which_var,
1144 int imag_data,
1145 char line1[Z_BUFL],
1146 char line2[Z_BUFL])
1148 Returns:
1149 -------
1150 Z_OK if successful
1151 Z_ERR if not successful
1153 Arguments:
1154 ---------
1155 (IN) which_type = Z_GEOM for geometry (2 lines)
1156 = Z_VARI for variable (1 line)
1158 (IN) which_var = If it is a variable, which one.
1159 Ignored if geometry type.
1161 (IN) imag_data = TRUE if want imaginary data file.
1162 FALSE if want real data file.
1164 (OUT) line1 = The 1st geometry description line,
1165 or the variable description line.
1167 (OUT) line2 = The 2nd geometry description line
1168 Not used if variable type.
1170 Notes:
1171 -----
1172 * Will be based on Current_time_step
1174 * These are the lines EnSight can echo to the screen in
1175 annotation mode.
1179 --------------------------------------------------------------------
1180 USERD_get_element_label_status
1182 Description:
1183 -----------
1184 Answers the question as to whether element labels will be provided.
1186 Specification:
1187 -------------
1188 int USERD_get_element_label_status( void )
1190 Returns:
1191 -------
1192 TRUE if element labels will be provided
1193 FALSE if element labels will NOT be provided
1195 Arguments:
1196 ---------
1197 none
1199 Notes:
1200 -----
1201 * element lables are needed in order to do any element querying, or
1202 element labeling on-screen within EnSight.
1204 * Prior to API 2.01:
1205 -----------------
1206 For unstructured parts, you can read them from your file if
1207 available, or can assign them, etc. They need to be unique
1208 per part, and are often unique per model.
1210 API 1.0:
1211 USERD_get_element_ids_for_part is used to obtain the ids,
1212 on a part by part basis, if TRUE status is returned here.
1214 API 2.0:
1215 USERD_get_part_element_ids_by_type is used to obtain the ids,
1216 on a per part, per type basis, if TRUE status is returned here.
1218 For structured parts, EnSight will assign ids if you return a
1219 status of TRUE here. You cannot assign them youself!!
1221 * Starting at API 2.01:
1222 --------------------
1223 For both unstructured and structured parts, you can read them
1224 from your file if available, or can assign them, etc. They need
1225 to be unique per part, and are often unique per model (especially
1226 if you are dealing with a decomposed dataset).
1228 USERD_get_part_element_ids_by_type is used to obtain the ids,
1229 on an element type by part basis, if TRUE status is returned here.
1231 * Will call USERD_get_part_element_ids_by_type for each type of
1232 of each part if this routine returns TRUE.
1233 --------------------------------------------------------------------
1234 USERD_get_geom_timeset_number -
1236 Description:
1237 -----------
1238 Gets the timeset number to be used for geometry
1240 Specification:
1241 -------------
1242 int USERD_get_geom_timeset_number( void )
1244 Returns:
1245 -------
1246 Geom_timeset_number = The timeset number that will be used for geometry.
1247 For example, if USERD_get_number_of timesets
1248 returns 2, the valid timeset numbers would be
1249 1 or 2.
1251 Arguments:
1252 ---------
1253 none
1255 Notes:
1256 -----
1257 * If your model is static, which you indicated by returning a zero
1258 in USERD_get_number_of_timesets, you can return a zero here as well.
1262 --------------------------------------------------------------------
1263 USERD_get_gold_part_build_info
1265 Description:
1266 -----------
1267 Gets the info needed for the part building process.
1269 Specification:
1270 -------------
1271 int USERD_get_gold_part_build_info(int *part_id,
1272 int *part_types,
1273 char *part_description[Z_BUFL],
1274 int *number_of_nodes,
1275 int *number_of_elements[Z_MAXTYPE],
1276 int *ijk_dimensions[9],
1277 int *iblanking_options[6])
1279 Returns:
1280 -------
1281 Z_OK if successful
1282 Z_ERR if not successful
1284 Arguments:
1285 ---------
1286 (OUT) part_id = Array containing the external part
1287 ids for each of the model parts.
1289 IMPORTANT:
1290 Parts numbers must be >= 1, because
1291 of the way they are used in the GUI
1293 *******************************************
1294 The ids provided here are the numbers by
1295 which the parts will be referred to in the
1296 GUI (if possible). They are basically
1297 labels as far as you are concerned.
1299 Note: The part numbers you pass to routines
1300 which receive a part_number or block_number
1301 or which_part as an argument are the 1-based
1302 table index of the parts!
1304 example: If Numparts_available = 3
1306 Table index part_id
1307 ----------- -------
1308 1 13
1309 2 57
1310 3 125
1312 ^ ^
1313 | |
1314 | These are placed in:
1315 | part_id[0] = 13
1316 | part_id[1] = 57
1317 | part_id[2] = 125
1318 | for GUI labeling purposes.
1319 |
1320 These implied table indices are the part_number,
1321 block_number, or which_part numbers that you would
1322 pass to routines like:
1324 USERD_get_part_coords(int part_number,...
1325 USERD_get_part_node_ids(int part_number,...
1326 USERD_get_part_elements_by_type(int part_number,...
1327 USERD_get_part_element_ids_by_type(int part_number,...
1328 USERD_get_block_coords_by_component(int block_number,...
1329 USERD_get_block_iblanking(int block_number,...
1330 USERD_get_block_ghost_flags(int block_number,...
1331 USERD_get_ghosts_in_block_flag(int block_number)
1332 USERD_get_border_availability(int part_number,...
1333 USERD_get_border_elements_by_type(int part_number,...
1334 USERD_get_var_by_component(int which_variable,
1335 int which_part,...
1336 USERD_get_var_value_at_specific(int which_var,
1337 int which_node_or_elem,
1338 int which_part,...
1339 ********************************************
1341 (Array will have been allocated
1342 Numparts_available long)
1344 (OUT) part_types = Array containing one of the
1345 following for each model part:
1347 Z_UNSTRUCTURED or
1348 Z_STRUCTURED or
1349 Z_IBLANKED
1351 (Array will have been allocated
1352 Numparts_available long)
1354 (OUT) part_description = Array containing a description
1355 for each of the model parts
1357 (Array will have been allocated
1358 Numparts_available by Z_BUFL
1359 long)
1361 (OUT) number_of_nodes = Number of unstructured nodes in the part
1363 (Array will have been allocated
1364 Numparts_available long)
1366 (OUT) number_of_elements = 2D array containing number of
1367 each type of element for each
1368 unstructured model part.
1369 ------------
1370 Possible types are:
1372 Z_POINT = point
1373 Z_BAR02 = 2-noded bar
1374 Z_BAR03 = 3-noded bar
1375 Z_TRI03 = 3-noded triangle
1376 Z_TRI06 = 6-noded triangle
1377 Z_QUA04 = 4-noded quadrilateral
1378 Z_QUA08 = 8-noded quadrilateral
1379 Z_TET04 = 4-noded tetrahedron
1380 Z_TET10 = 10-noded tetrahedron
1381 Z_PYR05 = 5-noded pyramid
1382 Z_PYR13 = 13-noded pyramid
1383 Z_PEN06 = 6-noded pentahedron
1384 Z_PEN15 = 15-noded pentahedron
1385 Z_HEX08 = 8-noded hexahedron
1386 Z_HEX20 = 20-noded hexahedron
1388 Z_G_POINT = ghost node point element
1389 Z_G_BAR02 = 2 node ghost bar
1390 Z_G_BAR03 = 3 node ghost bar
1391 Z_G_TRI03 = 3 node ghost triangle
1392 Z_G_TRI06 = 6 node ghost triangle
1393 Z_G_QUA04 = 4 node ghost quad
1394 Z_G_QUA08 = 8 node ghost quad
1395 Z_G_TET04 = 4 node ghost tetrahedron
1396 Z_G_TET10 = 10 node ghost tetrahedron
1397 Z_G_PYR05 = 5 node ghost pyramid
1398 Z_G_PYR13 = 13 node ghost pyramid
1399 Z_G_PEN06 = 6 node ghost pentahedron
1400 Z_G_PEN15 = 15 node ghost pentahedron
1401 Z_G_HEX08 = 8 node ghost hexahedron
1402 Z_G_HEX20 = 20 node ghost hexahedron
1404 (Ignored unless Z_UNSTRUCTURED type)
1406 (Array will have been allocated
1407 Numparts_available by
1408 Z_MAXTYPE long)
1410 (OUT) ijk_dimensions = 2D array containing ijk dimension info
1411 for structured blocks
1413 For Z_UNSTRUCTURED - is ignored
1415 For Z_STRUCTURED or Z_IBLANKED
1417 Prior to version 2.03:
1418 ----------------------
1419 (Array will have been allocated
1420 Numparts_available by 3 long)
1422 ijk_dimensions[][0] = I dimension
1423 ijk_dimensions[][1] = J dimension
1424 ijk_dimensions[][2] = K dimension
1427 Starting at version 2.03:
1428 ------------------------
1429 (Array will have been allocated
1430 Numparts_available by 9 long)
1432 There are two ways to do this:
1433 ------------------------------
1434 1. The simple one, without ranges.
1436 This is good for all structured models
1437 that will NOT be used in EnSight's
1438 Server of Servers
1440 Simply provide the ijk dimensions in the
1441 first three slots and place a -1 in
1442 the 4th slot. (The remaining slots will
1443 be ignored).
1445 Thus,
1446 ijk_dimensions[][0] = I dimension of block
1447 ijk_dimensions[][1] = J dimension of block
1448 ijk_dimensions[][2] = K dimension of block
1449 ijk_dimensions[][3] = -1
1451 (J planes)
1452 4 *-------*-------*
1453 | | | ijk_dimension[0][0] = 3
1454 | | | ijk_dimension[0][1] = 4
1455 | | | ijk_dimension[0][2] = 1
1456 3 *-------*-------*
1457 | | | ijk_dimension[0][4] = -1
1458 | | |
1459 | | |
1460 2 *-------*-------*
1461 | | |
1462 | | |
1463 | | |
1464 1 *-------*-------*
1465 1 2 3 (I planes)
1469 2. Using ranges.
1471 This one can be used anytime, but MUST
1472 be used if EnSight's Server of Servers
1473 is to be used!
1475 The first 3 slots contain the ijk dimension
1476 of the complete block (of which this may be
1477 a portion). The last 6 slots contain the
1478 ijk min and max ranges within the complete.
1480 Thus,
1481 ijk_dimensions[][0] = I dim of complete block
1482 ijk_dimensions[][1] = J dim of complete block
1483 ijk_dimensions[][2] = K dim of complete block
1485 ijk_dimensions[][3] = Imin of portion (1-based)
1486 ijk_dimensions[][4] = Imax of portion (1-based)
1487 ijk_dimensions[][5] = Jmin of portion (1-based)
1488 ijk_dimensions[][6] = Jmax of portion (1-based)
1489 ijk_dimensions[][7] = Kmin of portion (1-based)
1490 ijk_dimensions[][8] = Kmax of portion (1-based)
1493 example1: (Model has one part, a simple 2D block,
1494 and want whole thing)
1496 (J planes)
1497 4 *-------*-------*
1498 | | | ijk_dimension[0][0] = 3
1499 | | | ijk_dimension[0][1] = 4
1500 | | | ijk_dimension[0][2] = 1
1501 3 *-------*-------*
1502 | | | ijk_dimension[0][3] = 1
1503 | | | ijk_dimension[0][4] = 3
1504 | | | ijk_dimension[0][5] = 1
1505 2 *-------*-------* ijk_dimension[0][6] = 4
1506 | | | ijk_dimension[0][7] = 1
1507 | | | ijk_dimension[0][8] = 1
1508 | | |
1509 1 *-------*-------*
1510 1 2 3 (I planes)
1513 example2: (Want to have the block represented
1514 in two portions - 2 parts)
1516 (J planes) top portion
1517 4 *-------*-------*
1518 | | | ijk_dimension[0][0] = 3
1519 | | | ijk_dimension[0][1] = 4
1520 | | | ijk_dimension[0][2] = 1
1521 3 *-------*-------*
1522 . . . ijk_dimension[0][3] = 1
1523 . . . ijk_dimension[0][4] = 3
1524 . . . ijk_dimension[0][5] = 3
1525 2 ................. ijk_dimension[0][6] = 4
1526 . . . ijk_dimension[0][7] = 1
1527 . . . ijk_dimension[0][8] = 1
1528 . . .
1529 1 .................
1530 1 2 3 (I planes)
1533 (J planes) bottom portion
1534 4 .................
1535 . . . ijk_dimension[1][0] = 3
1536 . . . ijk_dimension[2][1] = 4
1537 . . . ijk_dimension[3][2] = 1
1538 3 *-------*-------*
1539 | | | ijk_dimension[1][3] = 1
1540 | | | ijk_dimension[1][4] = 3
1541 | | | ijk_dimension[1][5] = 1
1542 2 *-------*-------* ijk_dimension[1][6] = 3
1543 | | | ijk_dimension[1][7] = 1
1544 | | | ijk_dimension[1][8] = 1
1545 | | |
1546 1 *-------*-------*
1547 1 2 3 (I planes)
1550 And note that if you were partioning this block for
1551 EnSight's Server of Servers, you would only have one part,
1552 instead of two. Each SOS server would return its appropriate
1553 ranges in the last 6 slots. The first 3 slots would remain constant.
1556 (OUT) iblanking_options = 2D array containing iblanking
1557 options possible for each
1558 structured model part.
1559 ----------
1560 (Ignored unless Z_IBLANKED type)
1562 (Array will have been allocated
1563 Numparts_available by 6 long)
1565 iblanking_options[][Z_EXT] = TRUE if external (outside)
1566 [][Z_INT] = TRUE if internal (inside)
1567 [][Z_BND] = TRUE if boundary
1568 [][Z_INTBND] = TRUE if internal boundary
1569 [][Z_SYM] = TRUE if symmetry surface
1572 Notes:
1573 -----
1574 * If you haven't built a table of pointers to the different parts,
1575 you might want to do so here as you gather the needed info.
1577 * Will be based on Current_time_step
1580 --------------------------------------------------------------------
1581 USERD_get_gold_variable_info
1583 Description:
1584 -----------
1585 Get the variable descriptions, types and filenames
1587 Specification:
1588 -------------
1589 int USERD_get_gold_variable_info(char **var_description,
1590 char **var_filename,
1591 int *var_type,
1592 int *var_classify,
1593 int *var_complex,
1594 char **var_ifilename,
1595 float *var_freq,
1596 int *var_contran,
1597 int *var_timeset)
1599 Returns:
1600 -------
1601 Z_OK if successful
1602 Z_ERR if not successful
1604 Arguments:
1605 ---------
1606 (OUT) var_description = Variable descriptions
1608 (Array will have been allocated
1609 Num_variables by Z_BUFL long)
1611 variable description restrictions:
1612 ----------------------------------
1613 1. Only first 19 characters used in EnSight.
1614 2. Leading and trailing whitespace will be removed by EnSight.
1615 3. Illegal characters will be replaced by underscores.
1616 4. Thay may not start with a numeric digit.
1617 4. No two variables may have the same description.
1620 (OUT) var_filename = Variable real filenames
1622 (Array will have been allocated
1623 Num_variables by Z_BUFL long)
1625 (OUT) var_type = Variable type
1627 (Array will have been allocated
1628 Num_variables long)
1630 types are: Z_CONSTANT
1631 Z_SCALAR
1632 Z_VECTOR
1633 Z_TENSOR
1634 Z_TENSOR9
1636 (OUT) var_classify = Variable classification
1638 (Array will have been allocated
1639 Num_variables long)
1641 types are: Z_PER_NODE
1642 Z_PER_ELEM
1644 (OUT) var_complex = TRUE if complex, FALSE otherwise
1646 (Array will have been allocated
1647 Num_variables long)
1649 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1651 (Array will have been allocated
1652 Num_variables by Z_BUFL long)
1654 (OUT) var_freq = complex frequency (if complex)
1656 (Array will have been allocated
1657 Num_variables long)
1659 (OUT) var_contran = TRUE if constant changes per time step
1660 FALSE if constant truly same at all time steps
1662 (Array will have been allocated
1663 Num_variables long)
1665 (OUT) var_timeset = Timeset the variable will use (1 based).
1666 (For static models, set it to 1)
1668 (Array will have been allocated
1669 Num_variables long)
1671 For example: If USERD_get_number_of_timesets
1672 returns 2, the valid
1673 timeset_number's would be 1 or 2
1676 Notes:
1677 -----
1678 * The implied variable numbers apply, but be aware that the
1679 arrays are zero based.
1680 So for variable 1, will need to provide var_description[0]
1681 var_filename[0]
1682 var_type[0]
1683 var_classify[0]
1684 var_complex[0]
1685 var_ifilename[0]
1686 var_freq[0]
1687 var_contran[0]
1688 var_timeset[0]
1691 for variable 2, will need to provide var_description[1]
1692 var_filename[1]
1693 var_type[1]
1694 var_classify[1]
1695 var_complex[1]
1696 var_ifilename[1]
1697 var_freq[1]
1698 var_contran[1]
1699 var_timeset[1]
1700 etc.
1705 --------------------------------------------------------------------
1706 USERD_get_ghosts_in_block_flag
1708 Description:
1709 -----------
1710 Gets whether ghost cells present in block or not
1712 Specification:
1713 -------------
1714 int USERD_get_ghosts_in_block_flag(int block_number)
1716 Returns:
1717 -------
1718 TRUE if any ghost cells in this structured part
1719 FALSE if no ghost cells in this structured part
1721 Arguments:
1722 ---------
1723 (IN) block_number = The block part number
1724 (1-based index of part table, namely:
1726 1 ... Numparts_available.
1728 It is NOT the part_id that
1729 is loaded in USERD_get_gold_part_build_info)
1731 Notes:
1732 -----
1733 * This routine is new in the 2.01 API
1734 * This will be based on Current_time_step
1736 * Intended for structured parts only, value will be ignored for
1737 unstructured parts
1741 --------------------------------------------------------------------
1742 USERD_get_ghosts_in_model_flag
1744 Description:
1745 -----------
1746 Answers the question as to whether any ghost cells in the model.
1748 Specification:
1749 -------------
1750 int USERD_get_ghosts_in_model_flag( void )
1752 Returns:
1753 -------
1754 TRUE if any ghost cells in the model
1755 FALSE if no ghost cells in the model
1757 Arguments:
1758 ---------
1760 Notes:
1761 -----
1762 * This routine is new in the 2.01 API
1764 -------------------------------------------------------------------------
1765 USERD_get_matf_set_info
1767 Description:
1768 -----------
1769 Get the material set ids and names
1771 Specification:
1772 -------------
1773 int USERD_get_matf_set_info(int *mat_set_ids,
1774 char **mat_set_name)
1776 Returns:
1777 -------
1778 Z_OK if successful
1779 Z_ERR if not successful
1781 Arguments:
1782 ---------
1783 (OUT) mat_set_ids = 1D material set ids array
1785 (Array will have been allocated
1786 Num_material_sets long)
1788 (OUT) mat_set_name = 2D material set name array
1790 (Array will have been allocated
1791 Num_material_sets by Z_BUFL long)
1793 Notes:
1794 -----
1795 * Will not be called if Num_material_sets is zero
1796 * See USERD_get_number_of_material_sets header for explanatory example
1799 --------------------------------------------------------------------
1800 USERD_get_matf_var_info
1802 Description:
1803 -----------
1804 Gets the material ids and descriptions for the material set
1806 Specification:
1807 -------------
1808 int USERD_get_matf_var_info(int set_index,
1809 int *mat_ids,
1810 char **mat_desc)
1812 Returns:
1813 -------
1814 Z_OK if successful
1815 Z_ERR if not successful
1817 Arguments:
1818 ---------
1819 (IN) set_index = the material set index (zero based)
1821 (OUT) mat_ids[set_index] = 1D integer array containing the material
1822 ids to associated with each material
1824 (Array will have been allocated
1825 Num_materials[set_index] long)
1827 (OUT) mat_desc[set_index] = 2D char array containing the material
1828 descriptions to associated with each material
1830 (Array will have been allocated
1831 Num_materials[set_index] by Z_BUFL long)
1833 Notes:
1834 -----
1835 * See USERD_get_number_of_material_sets header for explanatory example
1836 * Will not be called if Num_material_sets is zero, or
1837 Num_materials[set_index] is zero
1842 --------------------------------------------------------------------
1843 USERD_get_maxsize_info
1845 Description:
1846 -----------
1847 Gets maximum part sizes for efficient memory allocation.
1849 Transient models (especially those that increase in size) can cause
1850 reallocations, at time step changes, to keep chewing up more and
1851 more memory. The way to avoid this is to know what the maximum
1852 size of such memory will be, and allocate for this maximum initially.
1854 Accordingly, if you choose to provide this information (it is optional),
1855 EnSight will take advantage of it.
1858 Specification:
1859 -------------
1860 int USERD_get_maxsize_info(int *max_number_of_nodes,
1861 int *max_number_of_elements[Z_MAXTYPE],
1862 int *max_ijk_dimensions[3])
1864 Returns:
1865 -------
1866 Z_OK if supplying maximum data
1867 Z_ERR if not supplying maximum data, or some error occurred
1868 while trying to obtain it.
1870 Arguments:
1871 ---------
1872 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1873 in the part (over all time).
1875 (Array will have been allocated
1876 Numparts_available long)
1878 (OUT) max_number_of_elements = 2D array containing maximum number of
1879 each type of element for each
1880 unstructured model part (over all time).
1881 ------------
1882 Possible types are:
1884 Z_POINT = point
1885 Z_BAR02 = 2-noded bar
1886 Z_BAR03 = 3-noded bar
1887 Z_TRI03 = 3-noded triangle
1888 Z_TRI06 = 6-noded triangle
1889 Z_QUA04 = 4-noded quadrilateral
1890 Z_QUA08 = 8-noded quadrilateral
1891 Z_TET04 = 4-noded tetrahedron
1892 Z_TET10 = 10-noded tetrahedron
1893 Z_PYR05 = 5-noded pyramid
1894 Z_PYR13 = 13-noded pyramid
1895 Z_PEN06 = 6-noded pentahedron
1896 Z_PEN15 = 15-noded pentahedron
1897 Z_HEX08 = 8-noded hexahedron
1898 Z_HEX20 = 20-noded hexahedron
1900 Z_G_POINT = ghost node point element
1901 Z_G_BAR02 = 2 node ghost bar
1902 Z_G_BAR03 = 3 node ghost bar
1903 Z_G_TRI03 = 3 node ghost triangle
1904 Z_G_TRI06 = 6 node ghost triangle
1905 Z_G_QUA04 = 4 node ghost quad
1906 Z_G_QUA08 = 8 node ghost quad
1907 Z_G_TET04 = 4 node ghost tetrahedron
1908 Z_G_TET10 = 10 node ghost tetrahedron
1909 Z_G_PYR05 = 5 node ghost pyramid
1910 Z_G_PYR13 = 13 node ghost pyramid
1911 Z_G_PEN06 = 6 node ghost pentahedron
1912 Z_G_PEN15 = 15 node ghost pentahedron
1913 Z_G_HEX08 = 8 node ghost hexahedron
1914 Z_G_HEX20 = 20 node ghost hexahedron
1916 (Ignored unless Z_UNSTRUCTURED type)
1918 (Array will have been allocated
1919 Numparts_available by
1920 Z_MAXTYPE long)
1922 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1923 for each structured model part (over all time).
1924 ----------
1925 (Ignored if Z_UNSTRUCTURED type)
1927 (Array will have been allocated
1928 Numparts_available by 3 long)
1930 max_ijk_dimensions[][0] = maximum I dimension
1931 max_ijk_dimensions[][1] = maximum J dimension
1932 max_ijk_dimensions[][2] = maximum K dimension
1934 Notes:
1935 -----
1936 * You need to have first called USERD_get_number_of_model_parts and
1937 USERD_get_gold_part_build_info, so Numparts_available is known and
1938 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1939 or Z_IBLANKED) of each part.
1941 * This will NOT be based on Current_time_step - it is to be the maximum
1942 values over all time!!
1944 * This information is optional. If you return Z_ERR, Ensight will still
1945 process things fine, reallocating as needed, etc. However, for
1946 large transient models you will likely use considerably more memory
1947 and take more processing time for the memory reallocations. So, if it
1948 is possible to provide this information "up front", it is recommended
1949 to do so.
1952 --------------------------------------------------------------------
1953 USERD_get_model_extents
1955 Description:
1956 -----------
1957 Gets the model bounding box extents. If this routine supplys them
1958 EnSight will not have to spend time doing so. If this routine
1959 returns Z_ERR, EnSight will have to take the time to touch all the
1960 nodes and gather the extent info.
1962 Specification:
1963 -------------
1964 int USERD_get_model_extents(float extents[6])
1966 Returns:
1967 -------
1968 Z_OK if successful
1969 Z_ERR if not successful (whereupon EnSight will determine by reading
1970 all coords of all parts)
1972 Arguments:
1973 ---------
1974 (OUT) extents[0] = min x
1975 [1] = max x
1976 [2] = min y
1977 [3] = max y
1978 [4] = min z
1979 [5] = max z
1981 Notes:
1982 -----
1983 * This will be based on Current_time_step
1986 --------------------------------------------------------------------
1987 USERD_get_name_of_reader
1989 Description:
1990 -----------
1991 Gets the name of your user defined reader. The user interface will
1992 ask for this and include it in the available reader list.
1994 Specification:
1995 -------------
1996 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1997 int *two_fields)
1999 Returns:
2000 -------
2001 Z_OK if successful
2002 Z_ERR if not successful
2004 Arguments:
2005 ---------
2006 (OUT) reader_name = the name of the your reader or data format.
2007 (max length is Z_MAX_USERD_NAME, which is 20)
2009 (OUT) two_fields = FALSE if only one data field is
2010 required.
2011 TRUE if two data fields required
2013 -1 if one field (Geom) required
2014 and one field (Param) is optional
2015 Param field can contain any text
2016 for example a file name, modifiers,
2017 etc. that can be used to modify the
2018 reader's behavior.
2021 Notes:
2022 -----
2023 * Always called. Please be sure to provide a name for your custom
2024 reader format.
2026 --------------------------------------------------------------------
2027 USERD_get_nfaced_conn
2029 Description:
2030 -----------
2031 Gets the array containing the connectivity of nsided faces of nfaced elements
2033 Specification:
2034 -------------int
2035 int USERD_get_nfaced_conn(int part_number,
2036 int *nfaced_conn_array)
2038 Returns:
2039 -------
2040 Z_OK if successful
2041 Z_ERR if not successful
2043 Arguments:
2044 ---------
2045 (IN) part_number = the part number
2047 (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced
2048 elements
2050 (int array will have been allocated long enough to
2051 hold all the nsided face connectivities. Which is
2052 the sum of all the nodes per face values in the
2053 nfaced_npf_array of USERD_get_nfaced_nodes_per_face)
2055 Notes:
2056 -----
2057 * Will not be called unless there are some nfaced elements in the part
2059 * Providing nfaced information to Ensight:
2061 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2062 polyhedral elements in the part.
2064 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2065 the number of faces per nfaced element. (as if connectivity
2066 length of an nfaced element is one)
2068 3. In this routine, provide the streamed number of nodes per face
2069 for each of the faces of the nfaced elements.
2072 Simple example: 11 10 12
2073 +--------+-----+
2074 2 nfaced elements: /| |\ /|
2075 (1 7-faced / | | \ / |
2076 1 5-sided) / | | +9 |
2077 / | | /| |
2078 /7 | 8 / | |
2079 +-----------+/ | | |
2080 | |5 | |4 | |6
2081 | +-----|--+--|--+
2082 | / | \ | /
2083 | / | \|/3
2084 | / | +
2085 | / | /
2086 |/1 |2 /
2087 +-----------+/
2089 1. In USERD_get_gold_part_build_info:
2090 number_of_elements[Z_NFACED] = 2
2091 .
2092 /|\
2093 |
2094 2. In USERD_get_part_elements_by_type:
2095 length of conn_array will be: 2 x 1
2096 for element_type of Z_NFACED:
2097 conn_array[0][0] = 7 (for the 7-faced element)
2098 conn_array[1][0] = 5 (for the 5-faced element)
2100 ==
2101 Sum 12 <---------+
2102 |
2103 3. In USERD_get_faced_nodes_per_face: |
2104 length of nfaced_npf_array will be: 12
2106 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2107 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2108 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2109 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2110 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2111 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2112 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2114 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2115 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2116 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2117 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2118 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2120 ==
2121 Sum 48 <-------------+
2122 |
2123 4. In this function: |
2124 length of the nfaced_conn_array will be: 48
2126 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2127 nsided_conn_array[1] = 8
2128 nsided_conn_array[2] = 9
2129 nsided_conn_array[3] = 10
2130 nsided_conn_array[4] = 11
2132 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2133 nsided_conn_array[6] = 5
2134 nsided_conn_array[7] = 4
2135 nsided_conn_array[8] = 3
2136 nsided_conn_array[9] = 2
2138 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2139 nsided_conn_array[11] = 2
2140 nsided_conn_array[12] = 8
2141 nsided_conn_array[13] = 7
2143 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2144 nsided_conn_array[15] = 1
2145 nsided_conn_array[16] = 7
2146 nsided_conn_array[17] = 11
2148 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2149 nsided_conn_array[19] = 5
2150 nsided_conn_array[20] = 11
2151 nsided_conn_array[21] = 10
2153 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2154 nsided_conn_array[23] = 3
2155 nsided_conn_array[24] = 9
2156 nsided_conn_array[25] = 8
2158 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2159 nsided_conn_array[27] = 4
2160 nsided_conn_array[28] = 10
2161 nsided_conn_array[29] = 9
2163 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2164 nsided_conn_array[32] = 12
2165 nsided_conn_array[32] = 10
2167 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2168 nsided_conn_array[34] = 4
2169 nsided_conn_array[35] = 6
2171 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2172 nsided_conn_array[37] = 4
2173 nsided_conn_array[38] = 10
2174 nsided_conn_array[39] = 12
2176 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2177 nsided_conn_array[41] = 6
2178 nsided_conn_array[42] = 12
2179 nsided_conn_array[43] = 9
2181 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2182 nsided_conn_array[45] = 3
2183 nsided_conn_array[46] = 9
2184 nsided_conn_array[47] = 10
2188 --------------------------------------------------------------------
2189 USERD_get_nfaced_nodes_per_face -
2191 Description:
2192 -----------
2193 Gets the array containing the number of nodes per face for each face
2194 of the nfaced elements.
2196 Specification:
2197 -------------
2198 int USERD_get_nfaced_nodes_per_face(int part_number,
2199 int *nfaced_npf_array)
2201 Returns:
2202 -------
2203 Z_OK if successful
2204 Z_ERR if not successful
2206 Arguments:
2207 ---------
2208 (IN) part_number = the part number
2210 (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of
2211 nfaced elements
2213 (int array will have been allocated long enough
2214 to hold all the nodes_per_face values. Which is
2215 the sum of all the number of faces per element
2216 values in the conn_array of
2217 USERD_get_part_elements_by_type)
2219 Notes:
2220 -----
2221 * Will not be called unless there are some nfaced elements in the
2222 the part
2224 * Providing nfaced information to Ensight:
2226 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2227 polyhedral elements in the part.
2229 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2230 the number of faces per nfaced element. (as if connectivity
2231 length of an nfaced element is one)
2233 3. In this routine, provide the streamed number of nodes per face
2234 for each of the faces of the nfaced elements.
2237 Simple example: 11 10 12
2238 +--------+-----+
2239 2 nfaced elements: /| |\ /|
2240 (1 7-faced / | | \ / |
2241 1 5-sided) / | | +9 |
2242 / | | /| |
2243 /7 | 8 / | |
2244 +-----------+/ | | |
2245 | |5 | |4 | |6
2246 | +-----|--+--|--+
2247 | / | \ | /
2248 | / | \|/3
2249 | / | +
2250 | / | /
2251 |/1 |2 /
2252 +-----------+/
2254 1. In USERD_get_gold_part_build_info:
2255 number_of_elements[Z_NFACED] = 2
2256 .
2257 /|\
2258 |
2259 2. In USERD_get_part_elements_by_type:
2260 length of conn_array will be: 2 x 1
2261 for element_type of Z_NFACED:
2262 conn_array[0][0] = 7 (for the 7-faced element)
2263 conn_array[1][0] = 5 (for the 5-faced element)
2265 ==
2266 Sum 12 <---------+
2267 |
2268 3. In this routine: |
2269 length of nfaced_npf_array will be: 12
2271 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2272 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2273 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2274 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2275 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2276 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2277 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2279 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2280 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2281 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2282 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2283 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2285 ==
2286 Sum 48 <-------------+
2287 |
2288 4. In USERD_get_nfaced_conn: |
2289 length of the nfaced_conn_array will be: 48
2291 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2292 nsided_conn_array[1] = 8
2293 nsided_conn_array[2] = 9
2294 nsided_conn_array[3] = 10
2295 nsided_conn_array[4] = 11
2297 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2298 nsided_conn_array[6] = 5
2299 nsided_conn_array[7] = 4
2300 nsided_conn_array[8] = 3
2301 nsided_conn_array[9] = 2
2303 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2304 nsided_conn_array[11] = 2
2305 nsided_conn_array[12] = 8
2306 nsided_conn_array[13] = 7
2308 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2309 nsided_conn_array[15] = 1
2310 nsided_conn_array[16] = 7
2311 nsided_conn_array[17] = 11
2313 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2314 nsided_conn_array[19] = 5
2315 nsided_conn_array[20] = 11
2316 nsided_conn_array[21] = 10
2318 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2319 nsided_conn_array[23] = 3
2320 nsided_conn_array[24] = 9
2321 nsided_conn_array[25] = 8
2323 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2324 nsided_conn_array[27] = 4
2325 nsided_conn_array[28] = 10
2326 nsided_conn_array[29] = 9
2328 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2329 nsided_conn_array[32] = 12
2330 nsided_conn_array[32] = 10
2332 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2333 nsided_conn_array[34] = 4
2334 nsided_conn_array[35] = 6
2336 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2337 nsided_conn_array[37] = 4
2338 nsided_conn_array[38] = 10
2339 nsided_conn_array[39] = 12
2341 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2342 nsided_conn_array[41] = 6
2343 nsided_conn_array[42] = 12
2344 nsided_conn_array[43] = 9
2346 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2347 nsided_conn_array[45] = 3
2348 nsided_conn_array[46] = 9
2349 nsided_conn_array[47] = 10
2354 --------------------------------------------------------------------
2355 USERD_get_node_label_status
2357 Description:
2358 -----------
2359 Answers the question as to whether node labels will be provided.
2361 Specification:
2362 -------------
2363 int USERD_get_node_label_status( void )
2365 Returns:
2366 -------
2367 TRUE if node labels will be provided
2368 FALSE if node labels will NOT be provided
2370 Arguments:
2371 ---------
2372 none
2374 Notes:
2375 -----
2376 * Node ids are needed in order to do any node querying, or node
2377 labeling on-screen within EnSight.
2379 * Prior to API 2.01:
2380 -----------------
2381 For unstructured parts, you can read them from your file if
2382 available, or can assign them, etc. They need to be unique
2383 per part, and are often unique per model. They must also be
2384 positive numbers greater than zero.
2386 USERD_get_part_node_ids is used to obtain the ids, if the
2387 status returned here is TRUE.
2389 (Unlike API 1.0, where the connectivity of elements had to be
2390 according to the node ids - API 2.0's element connectivities
2391 are not affected either way by the status here.)
2393 For structured parts, EnSight will assign ids if you return a
2394 status of TRUE here. You cannot assign them yourself!!
2396 * Starting at API 2.01:
2397 --------------------
2398 For both unstructured and structured parts, you can read them
2399 from your file if available, or can assign them, etc. They need
2400 to be unique per part, and are often unique per model. They must
2401 also be positive numbers greater than zero.
2403 USERD_get_part_node_ids is used to obtain the ids, if the
2404 status returned here is TRUE.
2406 * Will call USERD_get_part_node_ids for each part if this routine
2407 returns TRUE.
2409 --------------------------------------------------------------------
2410 USERD_get_nsided_conn -
2412 Description:
2413 -----------
2414 Gets the array containing the connectivity of nsided elements
2416 Specification:
2417 -------------
2418 int USERD_get_nsided_conn(int part_number,
2419 int *nsided_conn_array)
2421 Returns:
2422 -------
2423 Z_OK if successful
2424 Z_ERR if not successful
2426 Arguments:
2427 ---------
2428 (IN) part_number = the part number
2430 (OUT) nsided_conn_array = 1D array of nsided connectivies
2432 (int array will have been allocated long enough
2433 to hold all the nsided connectivities. Which is
2434 the sum of all the nodes_per_element values in
2435 the conn_array of USERD_get_part_elements_by_type)
2438 Notes:
2439 -----
2440 * Will not be called unless there are some nsided elements in the the part.
2442 * Providing nsided information to Ensight:
2444 1. In USERD_get_gold_part_build_info, provide the number of nsided
2445 elements in the part.
2447 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2448 the number of nodes per nsided element. (as if connectivity
2449 length of an nsided element is one)
2451 3. In this routine, provide the streamed connectivities for each of the
2452 nsided elements.
2455 Simple example: 5 6
2456 +--------+
2457 3 nsided elements: /| \
2458 (1 4-sided / | \
2459 1 3-sided / | \
2460 1 7-sided) / | \ 7
2461 /3 |4 +
2462 +-----+ |
2463 | | |
2464 | | |8
2465 | | +
2466 | | /
2467 | | /
2468 | | /
2469 |1 |2 /9
2470 +-----+--------+
2472 1. In USERD_get_gold_part_build_info:
2473 number_of_elements[Z_NSIDED] = 3
2474 .
2475 /|\
2476 |
2477 2. In USERD_get_part_elements_by_type:
2478 length of conn_array will be: 3 x 1
2480 for element_type of Z_NSIDED:
2481 conn_array[0][0] = 4 (for the 4-sided element)
2482 conn_array[1][0] = 3 (for the 3-sided element)
2483 conn_array[2][0] = 7 (for the 7-sided element)
2485 Sum ===
2486 14 <---------+
2487 |
2488 3. In this routine: |
2489 length of nsided_conn_array will be: 14
2491 nsided_conn_array[0] = 1 (connectivity of 4-sided element)
2492 nsided_conn_array[1] = 2
2493 nsided_conn_array[2] = 4
2494 nsided_conn_array[3] = 3
2496 nsided_conn_array[4] = 3 (connectivity of 3-sided element)
2497 nsided_conn_array[5] = 4
2498 nsided_conn_array[6] = 5
2500 nsided_conn_array[7] = 2 (connectivity of 7-sided element)
2501 nsided_conn_array[8] = 9
2502 nsided_conn_array[9] = 8
2503 nsided_conn_array[10] = 7
2504 nsided_conn_array[11] = 6
2505 nsided_conn_array[12] = 5
2506 nsided_conn_array[13] = 4
2511 --------------------------------------------------------------------
2512 USERD_get_num_of_time_steps
2514 Description:
2515 -----------
2516 Gets the number of time steps of data available for desired timeset.
2518 Specification:
2519 -------------
2520 int USERD_get_num_of_time_steps( int timeset_number )
2522 Returns:
2523 -------
2524 Number of time steps in timeset (>0 if okay, <=0 if problems).
2526 Arguments:
2527 ---------
2528 (IN) timeset number = the timeset number
2530 For example: If USERD_get_number_of_timesets
2531 returns 2, the valid
2532 timeset_number's would be 1 and 2
2534 Notes:
2535 -----
2536 * This should be >= 1 1 indicates a static model
2537 >1 indicates a transient model
2539 * Num_time_steps[timeset_number] would be set here
2543 --------------------------------------------------------------------
2544 USERD_get_number_of_files_in_dataset
2546 Description:
2547 -----------
2548 Get the total number of files in the dataset. Used for the
2549 dataset query option within EnSight.
2551 Specification:
2552 -------------
2553 int USERD_get_number_of_files_in_dataset( void )
2555 Returns:
2556 -------
2557 The total number of files in the dataset.
2559 Arguments:
2560 ---------
2561 none
2563 Notes:
2564 -----
2565 * You can be as complete as you want about this. If you don't
2566 care about the dataset query option, return a value of 0
2567 If you only want certain files, you can just include them. But,
2568 you will need to supply the info in USERD_get_dataset_query_file_info
2569 for each file you include here.
2571 * Num_dataset_files would be set here
2574 --------------------------------------------------------------------
2575 USERD_get_number_of_material_sets -
2577 Description:
2578 -----------
2579 Get the number of material sets in the model
2581 Specification:
2582 -------------
2583 int USERD_get_number_of_material_sets( void )
2586 Returns:
2587 -------
2588 Num_material_sets = number of material sets
2589 (Zero would indicate that you have no materials
2590 to deal with in the model)
2592 or
2594 -1 if an error condition
2596 Arguments:
2597 ---------
2598 none
2600 Notes:
2601 -----
2602 * You may want to keep this as a global for use in other routines.
2604 ###############################################################
2605 NOTE: For EnSight 7.6, only one material set is supported
2606 within EnSight.
2607 Thus the only valid returns here are:
2608 0 (no materials)
2609 1 (for the one material set allowed)
2610 or -1 (if an error)
2612 If the casefile has more than this, this reader will
2613 read them, but EnSight will issue an error message and
2614 choke on them!
2615 ###############################################################
2617 ================================================================
2618 A very simple explanatory example, to use as a reference for the
2619 materials routines:
2621 Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
2622 Most of the model is material 1, but the top left corner is material 9 -
2623 basically as shown:
2626 *--------*--------*--------*
2627 | | / | |
2628 | Mat 9 / | |
2629 | | / | |
2630 | |/ | |
2631 | e7 / e8 | e9 |
2632 | /| | |
2633 | / | | |
2634 | / | | |
2635 *----/---*--------*--------*
2636 | / | | |
2637 | / | | |
2638 | / | Mat 1 |
2639 |/ | | |
2640 | e4 | e5 | e6 |
2641 | | | |
2642 | | | |
2643 | | | |
2644 *--------*--------*--------*
2645 | | | |
2646 | | | |
2647 | | | |
2648 | | | |
2649 | e1 | e2 | e3 |
2650 | | | |
2651 | | | |
2652 | | | |
2653 *--------*--------*--------*
2656 Thus, in this routine, set:
2657 Num_material_sets = 1
2659 In USERD_get_matf_set_info, set:
2660 mat_set_ids[0] = 1
2661 mat_set_name[0] = "Material Set 1" (or whatever name desired)
2663 In USERD_get_number_of_materials, input would be set_index = 0, and
2664 would need to set:
2665 Num_materials[0] = 2
2667 For simplicity, the ids and descriptions that would be returned in
2668 USERD_get_matf_var_info could be:
2669 mat_ids[0] = 1
2670 mat_ids[1] = 9
2671 mat_desc[0] = "mat 1" (or whatever desired)
2672 mat_desc[2] = "mat 9"
2674 The per element material ids list would need to be:
2676 material ids:
2677 -------------
2678 ids_list[0] = 1 (material id 1, for elem e1)
2679 ids_list[1] = 1 ( " e2)
2680 ids_list[2] = 1 ( " e3)
2681 ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
2682 ids_list[5] = 1 (material id 1, for elem e5)
2683 ids_list[5] = 1 ( " e6)
2684 ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
2685 ids_list[5] = -9 ( " e8)
2686 ids_list[5] = 1 (material id 1, for elem e9)
2688 Finally we need the mixed material ids list and the mixed materials values list,
2689 which would need to be:
2691 mixed-material ids:
2692 -------------------
2693 ==> 1 ids_list[0] = 2 (the -1 in the material variable points here,
2694 2 indicates that two materials are present)
2695 2 ids_list[1] = 1 (1st material is 1)
2696 3 ids_list[2] = 9 (2nd material is 9)
2697 4 ids_list[3] = -1 (negative of index into mixed-material val_list)
2698 ==> 5 ids_list[4] = 2 (the -5 in the material variable points here,
2699 2 indicates that two materials are present)
2700 6 ids_list[5] = 1 (1st material is 1)
2701 7 ids_list[6] = 9 (2nd material is 9)
2702 8 ids_list[7] = -3 (negative of index into mixed-material val_list)
2703 ==> 9 ids_list[8] = 2 etc.
2704 10 ids_list[9] = 1
2705 11 ids_list[10] = 9
2706 12 ids_list[11] = -5
2708 mixed-material values:
2709 ----------------------
2710 ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here,
2711 and this is the value for material 1)
2712 2 val_list[1] = 0.125 (the value for material 9)
2713 ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
2714 4 val_list[3] = 0.875
2715 ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
2716 6 val_list[5] = 0.125
2718 So, USERD_size_matf_data would need to return
2719 matf_size = 8, when called with set_id = 1
2720 part_id = 1
2721 wtyp = Z_QUA04
2722 mat_type = Z_MAT_INDEX
2724 matf_size = 12, when called with set_id = 1
2725 part_id = 1
2726 mat_type = Z_MIX_INDEX
2728 = 6, when called with set_id = 1
2729 part_id = 1
2730 mat_type = Z_MIX_VALUE
2732 And, USERD_load_matf_data would need to return:
2733 the int array ids_list as shown above when called with:
2734 set_id = 1
2735 part_id = 1
2736 wtyp = Z_QUA04
2737 mat_type = Z_MAT_INDEX (indicating id list).
2739 the int array ids_list as shown above when called with:
2740 set_id = 1
2741 part_id = 1
2742 mat_type = Z_MIX_INDEX (indicating id list).
2744 the float array val_list as shown above when called with:
2745 set_id = 1
2746 part_id = 1
2747 mat_type = Z_MIX_VALUE (indicating val list).
2750 -------------------------------------------------------------------------
2751 USERD_get_number_of_materials
2753 Description:
2754 -----------
2755 Gets the number of materials in the material set
2757 Specification:
2758 -------------
2759 int USERD_get_number_of_materials( int set_index )
2761 Returns:
2762 -------
2763 Num_materials[set_index] = Number of materials in the set
2764 0 indicates no materials information present
2765 -1 indicates an error
2766 Arguments:
2767 ---------
2768 (IN) set_index = the material set index (zero based)
2770 Notes:
2771 -----
2772 * See USERD_get_number_of_material_sets header for explanatory example
2773 * Will not be called if Num_material_sets is zero
2774 * You may want to keep this as a global for use in other routines.
2778 --------------------------------------------------------------------
2779 USERD_get_number_of_model_parts
2781 Description:
2782 -----------
2783 Gets the total number of unstructured and structured parts
2784 in the model, for which you can supply information.
2786 Specification:
2787 -------------
2788 int USERD_get_number_of_model_parts( void )
2790 Returns:
2791 -------
2792 Number of parts (>0 if okay, <=0 if problems).
2794 Arguments:
2795 ---------
2796 none
2798 Notes:
2799 -----
2800 * If going to have to read down through the parts in order to
2801 know how many, you may want to build a table of pointers to
2802 the various parts, so you can easily get to particular parts in
2803 later processes. If you can simply read the number of parts
2804 at the head of the file, then you would probably not build the
2805 table at this time.
2807 * This routine would set Numparts_available, which is equal to
2808 Num_unstructured_parts + Num_structured_blocks.
2812 --------------------------------------------------------------------
2813 USERD_get_number_of_timesets
2815 Description:
2816 -----------
2817 Gets the number of timesets used in the model.
2819 Specification:
2820 -------------
2821 int USERD_get_number_of_timesets( void )
2823 Returns:
2824 -------
2825 Number of timesets in the model
2827 Arguments:
2828 ---------
2829 none
2831 Notes:
2832 -----
2833 * Num_timesets would be set here
2835 * If you have a static model, both geometry and variables, you should
2836 return a value of zero.
2838 * If you have a transient model, then you should return one or more.
2840 For example:
2842 Geometry Variables No. of timesets
2843 --------- ------------------------------ ---------------
2844 static static 0
2845 static transient, all using same timeset 1
2847 transient transient, all using same timeset as geom 1
2849 static transient, using 3 different timesets 3
2851 transient transient, using 3 different timesets and
2852 none of them the same as the
2853 geometry timeset 4
2854 etc.
2856 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
2857 the timeset number to use
2858 for geometry in:
2859 USERD_get_geom_timeset_number
2861 Variables can use the same timeset as the geometry, or can use
2862 other timesets. More than one variable can use the same timeset.
2864 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
2865 variable 1 provided at these same five steps
2866 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
2868 This routine should return a value of 2, because only
2869 two different timesets are needed. Timeset 1 would be for the
2870 geometry and variable 1 (they both use it). Timeset 2 would
2871 be for variable 2, which needs its own in this case.
2877 --------------------------------------------------------------------
2878 USERD_get_number_of_variables
2880 Description:
2881 -----------
2882 Get the number of variables for which you will be providing info.
2884 Specification:
2885 -------------
2886 int USERD_get_number_of_variables( void )
2888 Returns:
2889 -------
2890 Number of variables (includes constant, scalar, vector and tensor types)
2891 (>=0 if okay, <0 if problem)
2893 Arguments:
2894 ---------
2895 none
2897 Notes:
2898 -----
2899 *****************************************************************
2900 * Variable numbers, by which references will be made, are implied
2901 here. If you say there are 3 variables, the variable numbers
2902 will be 1, 2, and 3.
2903 *****************************************************************
2905 * Num_variables would be set here
2909 --------------------------------------------------------------------
2910 USERD_get_part_coords
2912 Description:
2913 -----------
2914 Gets the coordinates for an unstructured part.
2916 Specification:
2917 -------------
2918 int USERD_get_part_coords(int part_number, float **coord_array)
2920 Returns:
2921 -------
2922 Z_OK if successful
2923 Z_ERR if not successful
2925 Arguments:
2926 ---------
2927 (IN) part_number = The part number
2928 (1-based index of part table, namely:
2930 1 ... Numparts_available.
2932 It is NOT the part_id that
2933 is loaded in USERD_get_gold_part_build_info)
2935 (OUT) coord_array = 2D float array which contains,
2936 x,y,z coordinates of each node
2937 in the part.
2939 (IMPORTANT: The second dimension of this aray is 1-based!!!)
2941 (Array will have been allocated
2942 3 by (number_of_nodes + 1) for the part
2943 long - see USERD_get_gold_part_build_info)
2946 ex) If number_of_nodes = 100
2947 as obtained in:
2948 USERD_get_gold_part_build_info
2950 Then the allocated dimensions of the
2951 pointer sent to this routine will be:
2952 coord_array[3][101]
2954 Ignore the coord_array[0][0]
2955 coord_array[1][0]
2956 coord_array[2][0] locations and start
2957 the node coordinates at:
2958 coord_array[0][1]
2959 coord_array[1][1]
2960 coord_array[2][1]
2962 coord_array[0][2]
2963 coord_array[1][2]
2964 coord_array[2][2]
2966 etc.
2968 Notes:
2969 -----
2970 * Not called unless Num_unstructured_parts is > 0
2972 * Will be based on Current_time_step
2975 --------------------------------------------------------------------
2976 USERD_get_part_element_ids_by_type
2978 Description:
2979 -----------
2980 Gets the ids for the elements of a particular type for an unstructured
2981 or structured part.
2983 Specification:
2984 -------------
2985 int USERD_get_part_element_ids_by_type(int part_number,
2986 int element_type,
2987 int *elemid_array)
2989 Returns:
2990 -------
2991 Z_OK if successful
2992 Z_ERR if not successful
2994 Arguments:
2995 ---------
2996 (IN) part_number = The part number
2997 (1-based index of part table, namely:
2999 1 ... Numparts_available.
3001 It is NOT the part_id that
3002 is loaded in USERD_get_gold_part_build_info)
3004 (IN) element_type = One of the following (See global_extern.h)
3005 Z_POINT node point element
3006 Z_BAR02 2 node bar
3007 Z_BAR03 3 node bar
3008 Z_TRI03 3 node triangle
3009 Z_TRI06 6 node triangle
3010 Z_QUA04 4 node quad
3011 Z_QUA08 8 node quad
3012 Z_TET04 4 node tetrahedron
3013 Z_TET10 10 node tetrahedron
3014 Z_PYR05 5 node pyramid
3015 Z_PYR13 13 node pyramid
3016 Z_PEN06 6 node pentahedron
3017 Z_PEN15 15 node pentahedron
3018 Z_HEX08 8 node hexahedron
3019 Z_HEX20 20 node hexahedron
3021 Z_G_POINT ghost node point element
3022 Z_G_BAR02 2 node ghost bar
3023 Z_G_BAR03 3 node ghost bar
3024 Z_G_TRI03 3 node ghost triangle
3025 Z_G_TRI06 6 node ghost triangle
3026 Z_G_QUA04 4 node ghost quad
3027 Z_G_QUA08 8 node ghost quad
3028 Z_G_TET04 4 node ghost tetrahedron
3029 Z_G_TET10 10 node ghost tetrahedron
3030 Z_G_PYR05 5 node ghost pyramid
3031 Z_G_PYR13 13 node ghost pyramid
3032 Z_G_PEN06 6 node ghost pentahedron
3033 Z_G_PEN15 15 node ghost pentahedron
3034 Z_G_HEX08 8 node ghost hexahedron
3035 Z_G_HEX20 20 node ghost hexahedron
3037 (OUT) elemid_array = 1D array containing id of each
3038 element of the type.
3040 (Array will have been allocated
3041 number_of_elements of the type long)
3043 ex) If number_of_elements[Z_TRI03] = 25
3044 number_of_elements[Z_QUA04] = 100
3045 number_of_elements[Z_HEX08] = 30
3046 as obtained in:
3047 USERD_get_gold_part_build_info
3049 Then the allocated dimensions available
3050 for this routine will be:
3051 conn_array[25] when called with Z_TRI03
3053 conn_array[100] when called with Z_QUA04
3055 conn_array[30] when called with Z_HEX08
3057 Notes:
3058 -----
3059 * Not called unless element label status is set to TRUE in
3060 USERD_get_element_label_status
3062 * Will be based on Current_time_step
3066 --------------------------------------------------------------------
3067 USERD_get_part_elements_by_type
3069 Description:
3070 -----------
3071 Gets the connectivities for the elements of a particular type in an
3072 unstructured part
3074 Specification:
3075 -------------
3076 int USERD_get_part_elements_by_type(int part_number,
3077 int element_type,
3078 int **conn_array)
3080 Returns:
3081 -------
3082 Z_OK if successful
3083 Z_ERR if not successful
3085 Arguments:
3086 ---------
3087 (IN) part_number = The part number
3088 (1-based index of part table, namely:
3090 1 ... Numparts_available.
3092 It is NOT the part_id that
3093 is loaded in USERD_get_gold_part_build_info)
3095 (IN) element_type = One of the following (See global_extern.h)
3096 Z_POINT node point element
3097 Z_BAR02 2 node bar
3098 Z_BAR03 3 node bar
3099 Z_TRI03 3 node triangle
3100 Z_TRI06 6 node triangle
3101 Z_QUA04 4 node quad
3102 Z_QUA08 8 node quad
3103 Z_TET04 4 node tetrahedron
3104 Z_TET10 10 node tetrahedron
3105 Z_PYR05 5 node pyramid
3106 Z_PYR13 13 node pyramid
3107 Z_PEN06 6 node pentahedron
3108 Z_PEN15 15 node pentahedron
3109 Z_HEX08 8 node hexahedron
3110 Z_HEX20 20 node hexahedron
3112 Z_G_POINT ghost node point element
3113 Z_G_BAR02 2 node ghost bar
3114 Z_G_BAR03 3 node ghost bar
3115 Z_G_TRI03 3 node ghost triangle
3116 Z_G_TRI06 6 node ghost triangle
3117 Z_G_QUA04 4 node ghost quad
3118 Z_G_QUA08 8 node ghost quad
3119 Z_G_TET04 4 node ghost tetrahedron
3120 Z_G_TET10 10 node ghost tetrahedron
3121 Z_G_PYR05 5 node ghost pyramid
3122 Z_G_PYR13 13 node ghost pyramid
3123 Z_G_PEN06 6 node ghost pentahedron
3124 Z_G_PEN15 15 node ghost pentahedron
3125 Z_G_HEX08 8 node ghost hexahedron
3126 Z_G_HEX20 20 node ghost hexahedron
3129 (OUT) conn_array = 2D array containing connectivity
3130 of each element of the type.
3132 (Array will have been allocated
3133 num_of_elements of the type by
3134 connectivity length of the type)
3136 ex) If number_of_elements[Z_TRI03] = 25
3137 number_of_elements[Z_QUA04] = 100
3138 number_of_elements[Z_HEX08] = 30
3139 as obtained in:
3140 USERD_get_gold_part_build_info
3142 Then the allocated dimensions available
3143 for this routine will be:
3144 conn_array[25][3] when called with Z_TRI03
3146 conn_array[100][4] when called with Z_QUA04
3148 conn_array[30][8] when called with Z_HEX08
3150 Notes:
3151 -----
3152 * Not called unless Num_unstructured_parts is > 0
3154 * Will be based on Current_time_step
3157 --------------------------------------------------------------------
3158 USERD_get_part_node_ids
3160 Description:
3161 -----------
3162 Gets the node ids of an unstructured or structured part.
3164 Specification:
3165 -------------
3166 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
3168 Returns:
3169 -------
3170 Z_OK if successful
3171 Z_ERR if not successful
3173 Arguments:
3174 ---------
3175 (IN) part_number = The part number
3176 (1-based index of part table, namely:
3178 1 ... Numparts_available.
3180 It is NOT the part_id that
3181 is loaded in USERD_get_gold_part_build_info)
3183 (OUT) nodeid_array = 1D array containing node ids of
3184 each node in the part.
3186 (IMPORTANT: This array is 1-based!!!)
3188 (Array will have been allocated
3189 (number_of_nodes + 1) for the part long
3190 see USERD_get_gold_part_build_info)
3192 ex) If number_of_nodes = 100
3193 as obtained in:
3194 USERD_get_gold_part_build_info
3196 Then the allocated dimensions of the
3197 pointer sent to this routine will be:
3198 nodeid_array[101]
3200 Ignore the nodeid_array[0] location and start
3201 the node ids at:
3202 nodeid_array[1]
3204 nodeid_array[2]
3206 etc.
3208 Notes:
3209 -----
3210 * Not called unless node label status is TRUE, as returned from
3211 USERD_get_node_label_status
3213 * Will be based on Current_time_step
3215 * The ids are purely labels, used when displaying or querying node ids.
3216 However, any node id < 0 will never be displayed
3219 --------------------------------------------------------------------
3220 USERD_get_reader_descrip
3222 Description:
3223 -----------
3224 Gets the description of the reader, so gui can give more info
3226 Specification:
3227 -------------
3228 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
3230 Returns:
3231 -------
3232 Z_OK if successful
3233 Z_ERR if not successful
3235 Arguments:
3236 ---------
3237 (OUT) descrip = the description of the reader (max length is MAXFILENP,
3238 which is 255)
3240 Notes:
3241 -----
3242 * OPTIONAL ROUTINE! You can have it or not.
3246 --------------------------------------------------------------------
3247 USERD_get_reader_version
3249 Description:
3250 -----------
3251 Gets the version number of the user defined reader
3253 Specification:
3254 -------------
3255 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
3257 Returns:
3258 -------
3259 Z_OK if successful
3260 Z_ERR if not successful (and will assume is version 1.0)
3262 Arguments:
3263 ---------
3264 (OUT) version_number = the version number of the reader
3265 (max length is Z_MAX_USERD_NAME, which
3266 is 20)
3268 Notes:
3269 -----
3270 * This needs to be "2.000" or greater. Otherwise EnSight will assume
3271 this reader is API 1.0
3273 * should set it to "2.010" for this version of the API
3278 --------------------------------------------------------------------
3279 USERD_get_sol_times
3281 Description:
3282 -----------
3283 Get the solution times associated with each time step for
3284 desired timeset.
3286 Specification:
3287 -------------
3288 int USERD_get_sol_times(int timeset_number,
3289 float *solution_times)
3291 Returns:
3292 -------
3293 Z_OK if successful
3294 Z_ERR if not successful
3296 Arguments:
3297 ---------
3298 (IN) timeset_number = the timeset number
3300 For example: If USERD_get_number_of_timesets
3301 returns 2, the valid
3302 timeset_number's would be 1 and 2
3304 (OUT) solution_times = 1D array of solution times per time step
3306 (Array will have been allocated
3307 Num_time_steps[timeset_number] long)
3309 Notes:
3310 -----
3311 * The solution times must be non-negative and increasing.
3315 --------------------------------------------------------------------
3316 USERD_get_timeset_description -
3318 Description:
3319 -----------
3320 Get the description to associate with the desired timeset.
3322 Specification:
3323 -------------
3324 int USERD_get_timeset_description(int timeset_number,
3325 char timeset_description[Z_BUFL])
3327 Returns:
3328 -------
3329 Z_OK if successful
3330 Z_ERR if not successful
3332 Arguments:
3333 ---------
3334 (IN) timeset_number = the timeset number
3336 For example: If USERD_get_number_of_timesets
3337 returns 2, the valid
3338 timeset_number's would be 1 and 2
3340 (OUT) timeset_description = timeset description string
3343 Notes:
3344 -----
3345 * A string of NULLs is valid for timeset_description
3350 --------------------------------------------------------------------
3351 USERD_get_var_by_component
3353 Description:
3354 -----------
3355 Gets the values of a variable component. Both unstructured and structured
3356 parts use this routine.
3358 if Z_PER_NODE:
3359 Get the component value at each node for a given variable in the part.
3361 or if Z_PER_ELEM:
3362 Get the component value at each element of a specific part and type
3363 for a given variable.
3365 Specification:
3366 -------------
3367 int USERD_get_var_by_component(int which_variable,
3368 int which_part,
3369 int var_type,
3370 int which_type,
3371 int imag_data,
3372 int component,
3373 float *var_array)
3375 Returns:
3376 -------
3377 Z_OK if successful
3378 Z_ERR if not successful
3380 or: Z_UNDEF, in which case you need not load any values into var_array
3383 Arguments:
3384 ---------
3385 (IN) which_variable = The variable number
3387 (IN) which_part Since EnSight Version 7.4
3388 -------------------------
3389 = The part number
3391 (1-based index of part table, namely:
3393 1 ... Numparts_available.
3395 It is NOT the part_id that
3396 is loaded in USERD_get_gold_part_build_info)
3398 Prior to EnSight Version 7.4
3399 ----------------------------
3400 = The part id This is the part_id label loaded
3401 in USERD_get_gold_part_build_info.
3402 It is NOT the part table index.
3404 (IN) var_type = Z_SCALAR
3405 Z_VECTOR
3406 Z_TENSOR (symmetric tensor)
3407 Z_TENSOR9 (asymmetric tensor)
3409 (IN) which_type
3411 if Z_PER_NODE: Not used
3413 if Z_PER_ELEM: = The element type
3414 Z_POINT node point element
3415 Z_BAR02 2 node bar
3416 Z_BAR03 3 node bar
3417 Z_TRI03 3 node triangle
3418 Z_TRI06 6 node triangle
3419 Z_QUA04 4 node quad
3420 Z_QUA08 8 node quad
3421 Z_TET04 4 node tetrahedron
3422 Z_TET10 10 node tetrahedron
3423 Z_PYR05 5 node pyramid
3424 Z_PYR13 13 node pyramid
3425 Z_PEN06 6 node pentahedron
3426 Z_PEN15 15 node pentahedron
3427 Z_HEX08 8 node hexahedron
3428 Z_HEX20 20 node hexahedron
3430 Z_G_POINT ghost node point element
3431 Z_G_BAR02 2 node ghost bar
3432 Z_G_BAR03 3 node ghost bar
3433 Z_G_TRI03 3 node ghost triangle
3434 Z_G_TRI06 6 node ghost triangle
3435 Z_G_QUA04 4 node ghost quad
3436 Z_G_QUA08 8 node ghost quad
3437 Z_G_TET04 4 node ghost tetrahedron
3438 Z_G_TET10 10 node ghost tetrahedron
3439 Z_G_PYR05 5 node ghost pyramid
3440 Z_G_PYR13 13 node ghost pyramid
3441 Z_G_PEN06 6 node ghost pentahedron
3442 Z_G_PEN15 15 node ghost pentahedron
3443 Z_G_HEX08 8 node ghost hexahedron
3444 Z_G_HEX20 20 node ghost hexahedron
3446 (IN) imag_data = TRUE if imag component
3447 FALSE if real component
3449 (IN) component = The component: (0 if Z_SCALAR)
3450 (0 - 2 if Z_VECTOR)
3451 (0 - 5 if Z_TENSOR)
3452 (0 - 8 if Z_TENSOR9)
3454 * 6 Symmetric Indicies, 0:5 *
3455 * ---------------------------- *
3456 * | 11 12 13 | | 0 3 4 | *
3457 * | | | | *
3458 * T = | 22 23 | = | 1 5 | *
3459 * | | | | *
3460 * | 33 | | 2 | *
3463 * 9 General Indicies, 0:8 *
3464 * ---------------------------- *
3465 * | 11 12 13 | | 0 3 4 | *
3466 * | | | | *
3467 * T = | 21 22 23 | = | 6 1 5 | *
3468 * | | | | *
3469 * | 31 32 33 | | 7 8 2 | *
3471 (OUT) var_array
3473 -----------------------------------------------------------------------
3474 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
3475 -----------------------------------------------------------------------
3477 if Z_PER_NODE: = 1D array containing variable component value
3478 for each node.
3480 (Array will have been allocated
3481 (number_of_nodes + 1) long)
3483 Info stored in this fashion:
3484 var_array[0] = not used
3485 var_array[1] = var component for node 1 of part
3486 var_array[2] = var_component for node 2 of part
3487 var_array[3] = var_component for node 3 of part
3488 etc.
3490 if Z_PER_ELEM: = 1D array containing variable component
3491 value for each element of a particular
3492 part and type.
3494 (Array will have been allocated
3495 (number_of_elements[which_part][which_type] + 1)
3496 long. See USERD_get_gold_part_build_info)
3498 Info stored in this fashion:
3499 var_array[1] = var component for elem 1 (of part and type)
3500 var_array[2] = var component for elem 2 (of part and type)
3501 var_array[3] = var component for elem 3 (of part and type)
3502 etc.
3504 Notes:
3505 -----
3506 * Not called unless Num_variables is > 0
3508 * The per_node or per_elem classification must be obtainable from the
3509 variable number (a var_classify array needs to be retained)
3511 * Will be based on Current_time_step
3513 * If the variable is not defined for this part, simply return with a
3514 value of Z_UNDEF. EnSight will treat the variable as undefined for
3515 this part.
3518 --------------------------------------------------------------------
3519 USERD_get_var_value_at_specific
3521 Description:
3522 -----------
3523 if Z_PER_NODE:
3524 Get the value of a particular variable at a particular node in a
3525 particular part at a particular time.
3527 or if Z_PER_ELEM:
3528 Get the value of a particular variable at a particular element of
3529 a particular type in a particular part at a particular time.
3532 Specification:
3533 -------------
3534 int USERD_get_var_value_at_specific(int which_var,
3535 int which_node_or_elem,
3536 int which_part,
3537 int which_elem_type,
3538 int time_step,
3539 float values[3],
3540 int imag_data)
3542 Returns:
3543 -------
3544 Z_OK if successful
3545 Z_ERR if not successful
3547 Arguments:
3548 ---------
3549 (IN) which_var = The variable number
3551 (IN) which_node_or_elem
3553 If Z_PER_NODE:
3554 = The node number. This is not the id, but is
3555 the index of the global node
3556 list (1 based), or the block's
3557 node list (1 based).
3559 Thus, coord_array[1]
3560 coord_array[2]
3561 coord_array[3]
3562 . |
3563 . |which_node_or_elem index
3564 . ----
3567 If Z_PER_ELEM:
3568 = The element number. This is not the id, but is
3569 the element number index
3570 of the number_of_element array
3571 (see USERD_get_gold_part_build_info),
3572 or the block's element list (1 based).
3574 Thus, for which_part:
3575 conn_array[which_elem_type][0]
3576 conn_array[which_elem_type][1]
3577 conn_array[which_elem_type][2]
3578 . |
3579 . which_node_or_elem index
3580 . ----
3583 (IN) which_part Since EnSight Version 7.4
3584 -------------------------
3585 = The part number
3587 (1-based index of part table, namely:
3589 1 ... Numparts_available.
3591 It is NOT the part_id that
3592 is loaded in USERD_get_gold_part_build_info)
3594 Prior to EnSight Version 7.4
3595 ----------------------------
3596 = The part id This is the part_id label loaded
3597 in USERD_get_gold_part_build_info.
3598 It is NOT the part table index.
3601 (IN) which_elem_type
3603 If Z_PER_NODE, or block part:
3604 = Not used
3606 If Z_PER_ELEM:
3607 = The element type. This is the element type index
3608 of the number_of_element array
3609 (see USERD_get_gold_part_build_info)
3611 (IN) time_step = The time step
3613 (IN) imag_data = TRUE if want imaginary value.
3614 FALSE if want real value.
3616 (OUT) values = scalar or vector component value(s)
3617 values[0] = scalar or vector[0]
3618 values[1] = vector[1]
3619 values[2] = vector[2]
3622 Notes:
3623 -----
3624 * This routine is used in node querys over time (or element querys over
3625 time for Z_PER_ELEM variables). If these operations are not critical
3626 to you, this can be a dummy routine.
3628 * The per_node or per_elem classification must be obtainable from the
3629 variable number (a var_classify array needs to be retained)
3631 * The time step given is for the proper variable timeset.
3634 ----------------------------------------------------------------------
3635 USERD_load_matf_data
3637 Description:
3638 -----------
3639 Get the material id list, mixed-material id list, or
3640 mixed-material values list for the given material set and part (and
3641 element type if material id list)
3643 Specification:
3644 -------------
3645 int USERD_load_matf_data( int set_index,
3646 int part_id,
3647 int wtyp,
3648 int mat_type,
3649 int *ids_list,
3650 float *val_list)
3653 Returns:
3654 -------
3655 Z_OK if successful
3656 Z_ERR if not successful
3658 Arguments:
3659 ---------
3660 (IN) set_index = the material set index (zero based)
3662 (IN) part_id = the part number desired
3664 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3666 Z_POINT node point element
3667 Z_BAR02 2 node bar
3668 Z_BAR03 3 node bar
3669 Z_TRI03 3 node triangle
3670 Z_TRI06 6 node triangle
3671 Z_QUA04 4 node quad
3672 Z_QUA08 8 node quad
3673 Z_TET04 4 node tetrahedron
3674 Z_TET10 10 node tetrahedron
3675 Z_PYR05 5 node pyramid
3676 Z_PYR13 13 node pyramid
3677 Z_PEN06 6 node pentahedron
3678 Z_PEN15 15 node pentahedron
3679 Z_HEX08 8 node hexahedron
3680 Z_HEX20 20 node hexahedron
3681 Z_NSIDED nsided polygon
3682 Z_NFACED nfaced polyhedron
3684 Z_G_POINT ghost node point element
3685 Z_G_BAR02 2 node ghost bar
3686 Z_G_BAR03 3 node ghost bar
3687 Z_G_TRI03 3 node ghost triangle
3688 Z_G_TRI06 6 node ghost triangle
3689 Z_G_QUA04 4 node ghost quad
3690 Z_G_QUA08 8 node ghost quad
3691 Z_G_TET04 4 node ghost tetrahedron
3692 Z_G_TET10 10 node ghost tetrahedron
3693 Z_G_PYR05 5 node ghost pyramid
3694 Z_G_PYR13 13 node ghost pyramid
3695 Z_G_PEN06 6 node ghost pentahedron
3696 Z_G_PEN15 15 node ghost pentahedron
3697 Z_G_HEX08 8 node ghost hexahedron
3698 Z_G_HEX20 20 node ghost hexahedron
3699 Z_G_NSIDED ghost nsided polygon
3700 Z_G_NFACED ghost nfaced polyhedron
3702 (IN) mat_type = Z_MAT_INDEX for material ids list
3703 Z_MIX_INDEX for mixed-material ids list
3704 Z_MIX_VALUE for mixed-material values list
3706 (OUT) ids_list = If mat_type is Z_MAT_INDEX:
3707 ---------------------------
3708 1D material id list
3709 (Int array will have been allocated
3710 the appropriate size, as returned in
3711 USERD_size_matf_data for mat_type Z_MAT_INDEX)
3713 If mat_type is Z_MIX_INDEX:
3714 ---------------------------
3715 1D mixed-material id list
3716 (Int array will have been allocated
3717 the appropriate size, as returned in
3718 USERD_size_matf_data for mat_type Z_MIX_INDEX)
3720 (OUT) val_list = 1D mixed-materials values list
3721 (only used if mat_type is Z_MIX_VALUE)
3723 (Float array will have been allocated
3724 the appropriate size, as returned in
3725 USERD_size_matf_data for mat_type Z_MIX_VALUE)
3727 Notes:
3728 -----
3729 * See USERD_get_number_of_material_sets header for explanatory example
3730 * Will not be called if Num_material_sets is zero,
3731 or Num_materials[set_index] is zero,
3732 or the appropriate size from USERD_size_matf_data is zero
3736 --------------------------------------------------------------------
3737 USERD_set_filenames
3739 Description:
3740 -----------
3741 Receives the geometry and result filenames entered in the data
3742 dialog. The user written code will have to store and use these
3743 as needed. The user written code must manage its own files!!
3745 Specification:
3746 -------------
3747 int USERD_set_filenames(char filename_1[],
3748 char filename_2[],
3749 char the_path[],
3750 int swapbytes)
3752 Returns:
3753 -------
3754 Z_OK if successful
3755 Z_ERR if not successful
3757 Arguments:
3758 ---------
3759 (IN) filename_1 = the filename entered into the geometry
3760 field of the data dialog.
3762 (IN) param_2 = The usage of this string depends on
3763 'two_fields' in USERD_get_name_of_reader.
3765 If two_fields is FALSE then it's empty.
3767 If two_fields is TRUE, this is the
3768 manditory results file entered
3769 into the result field of the data dialog.
3771 If two_fields is -1, then this contains
3772 optional text (filenames, modifiers, etc.)
3773 that can be parsed and used to modify
3774 reader
3776 (IN) the_path = the path info from the data dialog.
3777 Note: filename_1 and filename_2 have already
3778 had the path prepended to them. This
3779 is provided in case it is needed for
3780 filenames contained in one of the files
3782 (IN) swapbytes = TRUE if should swap bytes when reading data.
3783 = FALSE normally.
3785 Notes:
3786 -----
3787 * Since you must manage everything from the input that is entered in
3788 these data dialog fields, this is an important routine!
3790 * It may be that you will need to have an executive type file that contains
3791 info and other filenames within it, like EnSight6's case file.
3794 --------------------------------------------------------------------
3795 USERD_set_server_number
3797 Description:
3798 -----------
3799 Receives the server number of how many total servers.
3801 Specification:
3802 -------------
3803 int USERD_set_server_number(int cur_serv,
3804 int tot_servs)
3806 Returns:
3807 -------
3808 nothing
3810 Arguments:
3811 ---------
3812 (IN) cur_serv = the current server.
3814 (IN) tot_servs = the total number of servers.
3816 Notes:
3817 -----
3818 * Only useful if your user defined reader is being used with EnSight's
3819 Server-of-Server capability. And even then, it may or may not be
3820 something that you can take advantage of. If your data is already
3821 partitioned in some manner, such that you can access the proper
3822 portions using this information.
3824 For all non-SOS uses, this will simply be 1 of 1
3828 --------------------------------------------------------------------
3829 USERD_set_time_set_and_step
3831 Description:
3832 -----------
3833 Set the current time step in the desired timeset. All functions that
3834 need time, and that do not explicitly pass it in, will use the timeset
3835 and step set by this routine, if needed.
3837 Specification:
3838 -------------
3839 void USERD_set_time_set_and_step(int timeset_number,
3840 int time_step)
3842 Returns:
3843 -------
3844 nothing
3846 Arguments:
3847 ---------
3848 (IN) timeset_number = the timeset number (1 based).
3850 For example: If USERD_get_number_of_timesets
3851 returns 2, the valid timeset_number's
3852 would be 1 and 2.
3854 (IN) time_step = The current time step to set
3856 Notes:
3857 -----
3858 * Current_time_step and Current_timeset would be set here
3861 --------------------------------------------------------------------
3862 USERD_size_matf_data
3864 Description:
3865 -----------
3866 Get the length of the material id list, mixed-material id list, or
3867 mixed-material values list for the given material set and part (and
3868 element type if material id list)
3870 Specification:
3871 -------------
3872 int USERD_size_matf_data( int set_index,
3873 int part_id,
3874 int wtyp,
3875 int mat_type,
3876 int *matf_size)
3879 Returns:
3880 -------
3881 Z_OK if successful
3882 Z_ERR if not successful
3884 Arguments:
3885 ---------
3886 (IN) set_index = the material set index (zero based)
3888 (IN) part_id = the part number desired
3890 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3892 Z_POINT node point element
3893 Z_BAR02 2 node bar
3894 Z_BAR03 3 node bar
3895 Z_TRI03 3 node triangle
3896 Z_TRI06 6 node triangle
3897 Z_QUA04 4 node quad
3898 Z_QUA08 8 node quad
3899 Z_TET04 4 node tetrahedron
3900 Z_TET10 10 node tetrahedron
3901 Z_PYR05 5 node pyramid
3902 Z_PYR13 13 node pyramid
3903 Z_PEN06 6 node pentahedron
3904 Z_PEN15 15 node pentahedron
3905 Z_HEX08 8 node hexahedron
3906 Z_HEX20 20 node hexahedron
3907 Z_NSIDED nsided polygon
3908 Z_NFACED nfaced polyhedron
3910 Z_G_POINT ghost node point element
3911 Z_G_BAR02 2 node ghost bar
3912 Z_G_BAR03 3 node ghost bar
3913 Z_G_TRI03 3 node ghost triangle
3914 Z_G_TRI06 6 node ghost triangle
3915 Z_G_QUA04 4 node ghost quad
3916 Z_G_QUA08 8 node ghost quad
3917 Z_G_TET04 4 node ghost tetrahedron
3918 Z_G_TET10 10 node ghost tetrahedron
3919 Z_G_PYR05 5 node ghost pyramid
3920 Z_G_PYR13 13 node ghost pyramid
3921 Z_G_PEN06 6 node ghost pentahedron
3922 Z_G_PEN15 15 node ghost pentahedron
3923 Z_G_HEX08 8 node ghost hexahedron
3924 Z_G_HEX20 20 node ghost hexahedron
3925 Z_G_NSIDED ghost nsided polygon
3926 Z_G_NFACED ghost nfaced polyhedron
3928 (IN) mat_type = Z_MAT_INDEX for material ids list
3929 Z_MIX_INDEX for mixed-material ids list
3930 Z_MIX_VALUE for mixed-material values list
3932 (OUT) matf_size = the length of the material id list, or
3933 mixed-material id list, or
3934 mixed-material values list
3935 for the given material set and part number
3936 (and element type if Z_MAT_INDEX)
3938 Notes:
3939 -----
3940 * See USERD_get_number_of_material_sets header for explanatory example
3941 * Will not be called if Num_material_sets is zero, or
3942 Num_materials[set_index] is zero
3947 --------------------------------------------------------------------
3948 USERD_stop_part_building
3950 Description:
3951 -----------
3952 This routine called when the part building dialog is closed. It is
3953 provided in case you desire to release memory, etc. that was only needed
3954 during the part building process.
3956 Specification:
3957 -------------
3958 void USERD_stop_part_building( void )
3960 Returns:
3961 -------
3962 nothing
3964 Arguments:
3965 ---------
3966 none
3968 Notes:
3969 -----
3971 --------------------------------------------------------------------
3972 USERD_rigidbody_existence
3974 Description:
3975 -----------
3976 Gets the existence of rigid body values or not in the model
3978 Specification:
3979 -------------
3980 int USERD_rigidbody_existence( void )
3982 Returns:
3983 -------
3984 Z_OK if rigid body values exist for the model
3985 Z_UNDEF if no rigid body values exist
3986 Z_ERR if an error
3988 Arguments:
3989 ---------
3990 none
3992 Notes:
3993 -----
3994 * This will be based on Current_time_step
3997 --------------------------------------------------------------------
3998 USERD_rigidbody_values
4000 Description:
4001 -----------
4002 Gets the rigid body values for each part
4004 Specification:
4005 -------------
4006 int USERD_rigidbody_values(int part_number,
4007 float values[7])
4009 Returns:
4010 -------
4011 Z_OK if rigid body values exist for the model
4012 Z_UNDEF if no rigid body values exist
4013 Z_ERR if an error
4015 Arguments:
4016 ---------
4017 (IN) part_number = The part number
4019 (1-based index of part table, namely:
4021 1 ... Numparts_available.
4023 It is NOT the part_id that
4024 is loaded in USERD_get_gold_part_build_info)
4026 (OUT) values values[0] = IX (x location)
4027 values[1] = IY (y location)
4028 values[2] = IZ (z location)
4029 values[3] = E0 (e0 euler value)
4030 values[4] = E1 (e1 euler value)
4031 values[5] = E2 (e2 euler value)
4032 values[6] = E3 (e3 euler value)
4035 Notes:
4036 -----
4037 * This will be based on Current_time_step
4038 * It will not be called unless USERD_rigidbody_existence indicates
4039 that there are some values in the model by returning Z_OK.
4042 --------------------------------------------------------------------
4043 USERD_set_right_side
4045 Description:
4046 -----------
4047 Informs the reader that the time currently set is the right side of a time
4048 span used for variable interpolation between time steps
4050 Specification:
4051 -------------
4052 void USERD_set_right_side( void )
4054 Returns:
4055 -------
4057 Arguments:
4058 ---------
4059 none
4061 Notes:
4062 -----
4063 * Applies to Current_time_step
4069 ------------------------------------------------------------------
4070 ENHANCED GUI ROUTINES
4072 --------------------------------------------------------------------
4073 USERD_get_extra_gui_numbers
4075 Description:
4076 -----------
4077 The Enhanced GUI routines are added to allow
4078 the user to customize a portion of the Data
4079 Reader dialog to pass in options to their
4080 user defined reader.
4082 Specification:
4083 -------------
4084 void USERD__get_extra_gui_numbers(int *num_Toggles,
4085 int *num_pulldowns,
4086 int *num_fields)
4088 Returns:
4089 -------
4091 Arguments:
4092 ---------
4093 (OUT) num_Toggles = number of toggles that will be provided
4095 num_pulldowns = number of pulldowns that will be provided
4097 num_fields = number of fields that will be provided
4099 Notes:
4100 -----
4101 There are three routines that work together:
4102 USERD_get_extra_gui_numbers
4103 USERD_get_extra_gui_defaults
4104 USERD_set_extra_gui_data
4106 The existence of these routine indicates that
4107 you wish to add customize entries to the
4108 Data Reader dialog.
4110 If you don't want the extra GUI features,
4111 simply delete these routines, or change their
4112 names to something such as
4113 USERD_DISABLED_get_extra_gui_defaults
4115 The presence of these routines
4116 will ensure that EnSight will call them and
4117 use their data to modify the extraction parameters set
4118 with some or all of the following:
4119 toggles, pulldown menu and fields.
4121 The user can then interact with the enhanced
4122 GUI and then send their choices to
4123 USERD_set_extra_gui_data
4125 Therefore if USERD_get_extra_gui_numbers
4126 exists then the other two must exist.
4128 If none exist, then the GUI will be unchanged.
4130 Toggle data will return an integer
4131 TRUE if checked
4132 FALSE if unchecked
4134 Pulldown menu will return an integer representing
4135 the menu item selected
4137 Field will return a string Z_LEN_GUI_FIELD_STR long.
4139 If all the enhanced GUI features are enabled it
4140 might look something like this
4142 ===================================================
4143 [] Title 1 [X] Title 3
4144 [X]Title 2 [X] Title 4
4146 Pulldown Menu ->
4147 Menu Choice 1
4148 Menu Choice 2
4149 Menu Choice 3
4151 Data Field Title 1 ____________________________
4153 Data Field Title 2 ____________________________
4154 =====================================================
4156 This routine defines the numbers of toggles, pulldowns & fields
4158 The following are defined in the global_extern.h
4159 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4160 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4161 Z_LEN_GUI_FIELD_STR max length of field string
4162 Z_LEN_GUI_TITLE_STR max length of title string
4164 The library is loaded, this routine is
4165 called, then the library is unloaded.
4167 Do not define globals in this routine
4168 as when the library is unloaded, you'll
4169 lose them.
4172 --------------------------------------------------------------------
4173 USERD_get_extra_gui_defaults
4175 Description:
4176 -----------
4177 This routine defines the Titles, status,
4178 List choices, strings, etc that are fed
4179 up to the GUI.
4181 Specification:
4182 -------------
4183 int USERD_get_extra_gui_defaults(char **toggle_Title,
4184 int *toggle_default_status,
4185 char **pulldown_Title,
4186 int *pulldown_number_in_list,
4187 int *pulldown_default_selection,
4188 char ***pulldown_item_strings,
4189 char **field_Title,
4190 char **field_user_string)
4192 Returns:
4193 -------
4194 Z_OK if successful
4195 Z_ERR if not successful
4197 Arguments:
4198 ---------
4199 (OUT) toggle_Title = title for each toggle
4200 array dimension is [num_toggles] by
4201 [Z_LEN_GUI_TITLE_STR] long
4203 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4204 array dimension is [num_toggles] long
4206 pulldown_Title = title for each pulldown
4207 array dimension is [num_pulldowns] by
4208 [Z_LEN_GUI_TITLE_STR] long
4210 pulldown_number_in_list = number of items in each pulldown
4211 array dimension is [num_pulldowns] long
4213 pulldown_default_selection = pulldown item selection for each pulldown
4214 array dimension is [num_pulldowns] long
4216 pulldown_item_strings = pulldown item strings
4217 array is [num_pulldowns] by
4218 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4219 [Z_LEN_GUI_PULL_STR] long
4221 field_Title = title for each field
4222 array dimension is [num_fields] by
4223 [Z_LEN_GUI_TITLE_STR] long
4225 field_user_string = content of the field
4226 array dimension is [num_fields] by
4227 [Z_LEN_GUI_TITLE_STR] long
4231 Notes:
4232 -----
4233 * The library is loaded, this routine is called, then the library is unloaded.
4235 * Do not define globals in this routine as when the library is unloaded, you'll
4236 lose them.
4240 --------------------------------------------------------------------
4241 USERD_set_extra_gui_data
4243 Description:
4244 -----------
4245 This routine sets the new values for the toggles, pulldowns, and fields.
4247 Specification:
4248 -------------
4249 void USERD_set_extra_gui_data(
4250 int *toggle, /* [num_toggle] */
4251 int *pulldown, /* [num_pulldown] */
4252 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4254 Returns:
4255 -------
4257 Arguments:
4258 ---------
4259 (IN) toggle = setting for each toggle. TRUE or FALSE
4260 array dimension is [num_toggles] long
4262 pulldown = item chosen in each pulldown. (0 based)
4263 array dimension is [num_pulldowns] long
4265 field_text = content of the field
4266 array dimension is [num_fields] by
4267 [Z_LEN_GUI_TITLE_STR] long
4270 Notes:
4271 -----
4272 * This routine is called when the library is permanently
4273 loaded to the EnSight session, so define your globals
4274 in this and later routines.
4276 * It's up to you to change your reader behavior according to
4277 user entries!
4281 --------------------------------------------------------------------
4282 USERD_get_var_extract_gui_numbers
4284 Description:
4285 -----------
4286 The Var_Extract_GUI routines are added to allow
4287 the user to customize a extraction parameters
4288 for variables "after" the file has been read.
4289 These things can be modified and the variables will
4290 be update/refreshed according to the new parameters set
4292 Specification:
4293 -------------
4294 void USERD_get_var_extract_gui_numbers(int *num_Toggles,
4295 int *num_pulldowns,
4296 int *num_fields)
4299 Returns:
4300 -------
4302 Arguments:
4303 ---------
4304 (OUT) num_Toggles = number of toggles that will be provided
4306 num_pulldowns = number of pulldowns that will be provided
4308 num_fields = number of fields that will be provided
4310 Notes:
4311 -----
4312 There are three routines that work together:
4313 USERD_get_var_extract_gui_numbers
4314 USERD_get_var_extract_gui_defaults (this one)
4315 USERD_set_var_extract_gui_data
4317 The existence of these routine indicates that
4318 you wish to have the Var Extract Parameters dialog.
4320 If you don't want the extra GUI features,
4321 simply delete these routines, or change their
4322 names to something such as
4323 USERD_DISABLED_get_var_extract_gui_defaults
4325 The presence of these routines
4326 will ensure that EnSight will call them and
4327 use their data to modify the extraction parameters set
4328 with some or all of the following:
4329 toggles, pulldown menu and fields.
4331 The user can then interact with the enhanced
4332 GUI and then send their choices to
4333 USERD_set_extra_gui_data
4335 Therefore if USERD_get_var_extract_gui_numbers
4336 exists then the other two must exist.
4338 If none exist, then the GUI will be unchanged.
4340 Toggle data will return an integer
4341 TRUE if checked
4342 FALSE if unchecked
4344 Pulldown menu will return an integer representing
4345 the menu item selected
4347 Field will return a string Z_LEN_GUI_FIELD_STR long.
4349 If all the enhanced GUI features are enabled it
4350 might look something like this
4352 ===================================================
4353 [] Title 1 [X] Title 3
4354 [X]Title 2 [X] Title 4
4356 Pulldown Menu ->
4357 Menu Choice 1
4358 Menu Choice 2
4359 Menu Choice 3
4361 Data Field Title 1 ____________________________
4363 Data Field Title 2 ____________________________
4364 =====================================================
4366 This routine defines the numbers of toggles, pulldowns & fields
4368 The following are defined in the global_extern.h
4369 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4370 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4371 Z_LEN_GUI_FIELD_STR max length of field string
4372 Z_LEN_GUI_TITLE_STR max length of title string
4374 The library is loaded, this routine is
4375 called, then the library is unloaded.
4377 Do not define globals in this routine
4378 as when the library is unloaded, you'll
4379 lose them.
4382 --------------------------------------------------------------------
4383 USERD_get_var_extract_gui_defaults
4385 Description:
4386 -----------
4387 This routine defines the Titles, status,
4388 List choices, strings, etc that are fed
4389 up to the GUI.
4391 Specification:
4392 -------------
4393 int USERD_get_var_extract_gui_defaults(char **toggle_Title,
4394 int *toggle_default_status,
4395 char **pulldown_Title,
4396 int *pulldown_number_in_list,
4397 int *pulldown_default_selection,
4398 char ***pulldown_item_strings,
4399 char **field_Title,
4400 char **field_user_string)
4402 Returns:
4403 -------
4404 Z_OK if successful
4405 Z_ERR if not successful
4407 Arguments:
4408 ---------
4409 (OUT) toggle_Title = title for each toggle
4410 array dimension is [num_toggles] by
4411 [Z_LEN_GUI_TITLE_STR] long
4413 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4414 array dimension is [num_toggles] long
4416 pulldown_Title = title for each pulldown
4417 array dimension is [num_pulldowns] by
4418 [Z_LEN_GUI_TITLE_STR] long
4420 pulldown_number_in_list = number of items in each pulldown
4421 array dimension is [num_pulldowns] long
4423 pulldown_default_selection = pulldown item selection for each pulldown
4424 array dimension is [num_pulldowns] long
4426 pulldown_item_strings = pulldown item strings
4427 array is [num_pulldowns] by
4428 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4429 [Z_LEN_GUI_PULL_STR] long
4431 field_Title = title for each field
4432 array dimension is [num_fields] by
4433 [Z_LEN_GUI_TITLE_STR] long
4435 field_user_string = content of the field
4436 array dimension is [num_fields] by
4437 [Z_LEN_GUI_TITLE_STR] long
4441 Notes:
4442 -----
4443 * The library is loaded, this routine is called, then the library is unloaded.
4445 * Do not define globals in this routine as when the library is unloaded, you'll
4446 lose them.
4450 --------------------------------------------------------------------
4451 USERD_set_var_extract_gui_data
4453 Description:
4454 -----------
4455 This routine sets the new values for the toggles, pulldowns, and fields.
4457 Specification:
4458 -------------
4459 void USERD_set_var_extract_gui_data(
4460 int *toggle, /* [num_toggle] */
4461 int *pulldown, /* [num_pulldown] */
4462 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4464 Returns:
4465 -------
4467 Arguments:
4468 ---------
4469 (IN) toggle = setting for each toggle. TRUE or FALSE
4470 array dimension is [num_toggles] long
4472 pulldown = item chosen in each pulldown. (0 based)
4473 array dimension is [num_pulldowns] long
4475 field_text = content of the field
4476 array dimension is [num_fields] by
4477 [Z_LEN_GUI_TITLE_STR] long
4480 Notes:
4481 -----
4482 * This routine is called when the library is permanently
4483 loaded to the EnSight session, so define your globals
4484 in this and later routines.
4486 * It's up to you to change your reader behavior according to
4487 user entries!
4493 -----------------------------------------------------------------------------------
4494 /* ----------------------------------------------------------
4495 * New in EnSight 8 is the capability to remove (fail) elements
4496 * based on variable threshold values. Basically the variable
4497 * name, a couple of thresholds, a couple of values and a logic
4498 * criteria are read in from this routine. Every element that
4499 * satisfies the failure criteria is removed and not used in
4500 * EnSight calculations.
4501 *
4502 * Example Failure criteria
4503 * Let fail_var_name = "fail_flag"
4504 * threshold_val1 = 0
4505 * threshold_operator1 = Z_EQUAL_TO
4506 * logic_criteria2 not used
4507 * threshold_val2 not used
4508 * threshold_operator2 not used
4509 * For each value of "fail_flag" at each element,
4510 * if fail flag == threshold_val1 (0.0) then element fails
4511 * Return (Z_ERR) if this is not used.
4512 * Return (Z_OK) if failed element feature should be used
4513 *
4514 * threshold_operator1 & 2 can be one of the following
4515 * Z_ELE_FAILED_NONE, - disables checking
4516 * Z_ELE_FAILED_GREATER, - greater than
4517 * Z_ELE_FAILED_LESS, - less than
4518 * Z_ELE_FAILED_EQUAL, - equal
4519 * Z_ELE_FAILED_NOT_EQUAL, - not equal
4520 * Z_ELE_FAILED_MANY - not used
4521 *
4522 * logic_criteria2
4523 * Z_ELE_FAILED_LOGIC_NONE,
4524 * Z_ELE_FAILED_LOGIC_AND,
4525 * Z_ELE_FAILED_LOGIC_OR,
4526 * Z_ELE_FAILED_LOGIC_MANY
4527 *
4528 * ---------------------------------------------------------- */
4529 int USERD_get_uns_failed_params(
4530 char *fail_var_name, /* variable name to be used in failure
4531 must be scalar, per elem */
4532 float *threshold_val1, /* number to compare for failure */
4533 float *threshold_val2, /* number to compare for failure */
4534 int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN,
4535 Z_EQUAL_TO */
4536 int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN,
4537 Z_EQUAL_TO */
4538 int *logic_criteria2
4543 ---- end of document ----