[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.08
| blob | 29e185d4d0cc03fefd8d608d98618fbbaa8a253b |
1 README_USERD_2.08
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.08)
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.08 invloves a slight change to API 2.05 and later:
17 Namely, rotational (yaw,pitch,roll) values were added to the values
18 argument of USERD_rigidbody_values routine.
20 ***>> API 2.07 additional capabilities (beyond API 2.06):
21 Optional routine to allow userd defined readers to indicate their auto
22 distribute preference when used with SOS. This is used to set the auto
23 distribute flag default in the client. If the function does not exist,
24 then it defaults to 'use auto distribute'. If the function does exist and
25 indicates 'no auto distribute', then it's up to the UDR to decompose a
26 distributed data set.
27 USERD_prefer_auto_distribute
28 Optional routine to allow userd defined readers to indicate their
29 preference for the 'Set file...' button labels in the client's File->Open
30 dialog. If the function does not exist or it returns a null string for
31 an argument, then the default values are used.
32 USERD_set_filename_button_labels
34 ***>> API 2.06 additional capabilities (beyond API 2.05):
35 Routines to allow userd defined readers for structured data
36 to deal with min, max, and stride within the reader itself
37 instead of within EnSight.
38 USERD_get_structured_reader_cinching
39 USERD_set_block_range_and_stride
42 ***>> API 2.05 additional capabilities (beyond API 2.04):
43 Routines to handle material species.
44 USERD_get_number_of_species
45 USERD_get_matsp_info
47 Routines to handle variable extraction parameters after a read, and then
48 update the variables accordingly. Similar to the extra GUI capabilities
49 (which are processed before a read). (Can actually be added to pre-2.05 readers)
50 USERD_get_var_extract_gui_numbers
51 USERD_get_var_extract_gui_defaults
52 USERD_set_var_extract_gui_data
54 Routines to obtain rigid body values from a reader.
55 (Routines were added - EnSight is now using for Nastran and STL readers
56 with Dynasty rigid body motion data file)
57 USERD_rigidbody_existence
58 USERD_rigidbody_values
60 Routine that lets reader know when EnSight is getting the right side of a time
61 interval for variable interpolation between steps. Not generally needed for
62 most readers - however, may be needed for those that implement rigid body, and
63 wish to cache left and right timespan information for interpolation within the
64 reader itself. (Can actually be added to pre-2.05 readers)
65 USERD_set_right_side
68 ***>> API 2.04 additional capabilities (beyond API 2.03):
69 Routines to handle failed elements. Basically
70 a.One routine to return a flag indicating the existence of
71 failed elements in at least one part in at least one
72 timestep in the model.
73 b.A second routine to return a matrix of flags indexed by part and
74 element type indicating which parts and element types have failed
75 elements at the current time step.
76 c.Finally a third routine to return an array of flags for a given
77 part and element type that is number of elements of that type long
78 indicating which elements have failed, and which have not failed.
81 ***>> API 2.03 additional capabilities (beyond API 2.01):
82 1. Routines to handle materials
83 2. Routines to handle nsided and nfaced elements
84 3. Modified routine to handle structured ranges
87 ****************************************************************************
88 Note: Only the the Ensight Gold example reader, has been moved to
89 this 2.06 API level. And it is purely for an example - it does not
90 actually provide a benefit.
91 ****************************************************************************
94 The process for producing a user defined reader is:
95 ---------------------------------------------------
96 1. Write code for all pertinent routines in the library (Unless someone else
97 has done this for you).
99 This is of course where the work is done by the user. The word
100 "pertinent" is used because depending on the nature of the data, some
101 of the routines in the library may be dummy routines.
103 The source code for a dummy_gold library and for various other
104 working or sample libraries is copied from the installation CD during
105 installation. These will be located in directories under:
107 $CEI_HOME/ensight76/user_defined_src/readers
109 examples:
110 --------
111 Basic dummy_gold routines provide skeleton for a new reader
112 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
114 Sample library which reads unstructured binary EnSight Gold data
115 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
117 You may find it useful to place your library source in this area as
118 well, but are not limited to this location.
120 * ===> The descriptions of each library routine and the order that the
121 routines are called, which is provided in this file, along with
122 the example libraries, should make it possible for you to produce
123 code for your own data reader.
126 2. Produce the dynamic shared library.
128 This is a compiling and loading process which varies according to
129 the type of machine you are on. In the user-defined-reader source
130 tree we have tried to isolate the machine dependent parts of the
131 build process using a set of files in the 'config' directory. In this
132 directory there is a configuration file for each platform on which
133 EnSight is supported. Before you can compile the installed readers
134 you should run the script called 'init' in the config directory.
136 i.e. (for UNIX)
137 cd config
138 ./init sgi_6.5_n64
139 cd ..
140 make
142 If you are compiling for Windows NT, there are two options. If you
143 have the Cygwin GNU utilities installed, you can use GNU make as for
144 Unix. Otherwise, there is a script called makeall.cmd which will
145 build all of the readers using nmake. The Makefiles in each reader
146 directory will work using either make or nmake.
148 i.e. (WIN32 Cygwin) (using nmake)
149 cd config cd config
150 sh init win32 cp win32 config
151 cd .. cd ..
152 mkdir lib
153 make makeall.cmd
155 If you have platform-specific portions of code in your reader, the
156 build system defines a set of flags which can be used within
157 #ifdef ... #endif regions in your source, as shown in the table
158 below.
160 Because the readers are now dynamically opened by EnSight, you may
161 have to include dependent libraries on your link-line to avoid having
162 unresolved symbols. If you are having problems with a reader, start
163 ensight as "ensight7 -readerdbg" and you will get feedback on any
164 problems encountered in loading a reader. If there are unresolved
165 symbols, you need to find the library which contains the missing
166 symbols and link it into your reader by adding it to the example
167 link commands below.
169 If you choose to use a different build environment for your reader,
170 you should take care to use compatible compilation flags to ensure
171 compatibilty with the EnSight executables, most notably on the SGI
172 and HP-UX 11.0 platforms, which should use the following flags:
174 sgi_6.2_o32: -mips2
175 sgi_6.2_n64: -mips4 -64
176 sgi_6.5_n32: -mips3
177 sgi_6.5_n64: -mips4 -64
178 hp_11.0_32: +DA2.0
179 hp_11.0_64: +DA2.0W
181 ______________________________________________________________________
182 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
183 | TYPE |------------------------------------------------------------|
184 | | LD COMMAND USED IN MAKEFILE |
185 ======================================================================
186 ______________________________________________________________________
187 | sgi | -DSGI | libuserd-X.so |
188 | |------------------------------------------------------------|
189 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
190 ----------------------------------------------------------------------
191 ______________________________________________________________________
192 | hp | -DHP | libuserd-X.sl |
193 | |------------------------------------------------------------|
194 | | ld -b -o libuserd-X.sl libuserd-X.o |
195 ----------------------------------------------------------------------
196 ______________________________________________________________________
197 | sun | -DSUN | libuserd-X.so |
198 | |------------------------------------------------------------|
199 | | ld -G -o libuserd-X.so libuserd-X.o |
200 ----------------------------------------------------------------------
201 ______________________________________________________________________
202 | dec | -DDEC | libuserd-X.so |
203 | |------------------------------------------------------------|
204 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
205 ----------------------------------------------------------------------
206 ______________________________________________________________________
207 | linux | -DLINUX | libuserd-X.so |
208 | |------------------------------------------------------------|
209 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
210 ----------------------------------------------------------------------
211 ______________________________________________________________________
212 | alpha | -DALINUX | libuserd-X.so |
213 | linux |------------------------------------------------------------|
214 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
215 ----------------------------------------------------------------------
216 ______________________________________________________________________
217 | ibm | -DIBM | libuserd-X.so |
218 | |------------------------------------------------------------|
219 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
220 ----------------------------------------------------------------------
222 Once you have created your library, you should place it in a directory
223 of your choice or in the standard reader location:
225 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
227 For example, if you created a reader for "mydata", you should create
228 the reader libuserd-mydata.so and place the file in your own reader
229 directory (see section 3 below) or in the standard location:
231 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
234 3. By default EnSight will load all readers found in the directory:
236 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
238 Files with names "libuserd-X.so" (where X is a name unique to the reader)
239 are assumed to be user-defined readers.
241 There are two methods which can be used to supplement the default
242 behavior.
244 (1) A feature which is useful for site-level or user-level configuration
245 is the optional environment variable $ENSIGHT7_READER. This
246 variable directs EnSight to load all readers in the specified reader
247 directory (you should probably specify a full path) before loading
248 the built-in readers. If the same reader exists in both directories
249 (as determined by the name returned by USERD_get_name_of_reader(),
250 NOT by the filename), the locally configured reader will take
251 precedence.
253 (2) A useful feature for end-users is the use of the libuserd-devel
254 reader. EnSight will search for a reader named libuserd-devel.so
255 (.sl for HP or .dll for NT). This reader can exist anywhere in the
256 library path (see below) of the user. This is useful for an
257 individual actively developing a reader because the existence of a
258 libuserd-devel library will take precedence over any other library
259 which returns the same name from USERD_get_name_of_reader().
261 As an example, a site may install commonly used readers in a common
262 location, and users can set the ENSIGHT7_READER variable to access them:
264 setenv ENSIGHT7_READER /usr/local/lib/e7readers
266 A user working on a new reader may compile the reader and place it in
267 a directory specified by the library path:
269 cp libuserd-myreader.so ~/lib/libuserd-devel.so
270 setenv <librarypath> ~/lib:$<librarypath>
272 The user is responsible for correctly configuring the library path
273 variable in order to make use of the libuserd-devel feature. The
274 library environment variables used are:
276 Machine type Environment variable to set
277 ------------ ---------------------------
278 sgi LD_LIBRARY_PATH
279 dec LD_LIBRARY_PATH
280 sun LD_LIBRARY_PATH
281 linux LD_LIBRARY_PATH
282 alpha linux LD_LIBRARY_PATH
283 hp SHLIB_PATH
284 ibm LIBPATH
286 As always, EnSight support is available if you need it.
288 -------------------------------
289 Quick Index of Library Routines
290 -------------------------------
292 Generally Needed for UNSTRUCTURED data
293 --------------------------------------
294 USERD_get_part_coords part's node coordinates
295 USERD_get_part_node_ids part's node ids
296 USERD_get_part_elements_by_type part's element connectivites
297 USERD_get_part_element_ids_by_type part's element ids
300 Generally Needed for BLOCK data
301 --------------------------------------
302 USERD_get_block_coords_by_component block coordinates
303 USERD_get_block_iblanking block iblanking values
304 USERD_get_ghosts_in_block_flag block ghost cell existence?
305 USERD_get_block_ghost_flags block ghost cell flags
307 These routines, which formerly were only for unstructured data, will now
308 also be called for structured data if you specify that ids will be given
309 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
310 ------------------------------------------------------------------------------
311 USERD_get_part_node_ids part's node ids
312 USERD_get_part_element_ids_by_type part's element ids
315 Generally needed for either or both kinds of data
316 -------------------------------------------------
317 USERD_get_name_of_reader name of reader for GUI
318 USERD_get_reader_release release string of reader
319 USERD_get_reader_version provide reader version number
320 USERD_get_reader_descrip provide GUI more description (optional)
322 USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields
323 USERD_get_extra_gui_defaults Gets the default values for the GUI members
324 USERD_set_extra_gui_data Returns the answers provided by the user
326 USERD_set_filenames filenames entered in GUI
327 USERD_set_server_number server which of how many
329 USERD_get_number_of_timesets number of timesets
330 USERD_get_timeset_description description of timeset
331 USERD_get_geom_timeset_number timeset # to use for geom
333 USERD_get_num_of_time_steps number of time steps
334 USERD_get_sol_times solution time values
335 USERD_set_time_set_and_step current timeset and time step
337 USERD_get_changing_geometry_status changing geometry?
338 USERD_get_node_label_status node labels?
339 USERD_get_element_label_status element labels?
340 USERD_get_model_extents provide model bounding extents
341 USERD_get_number_of_files_in_dataset number of files in model
342 USERD_get_dataset_query_file_info info about each model file
343 USERD_get_descrip_lines file associated description lines
344 USERD_get_number_of_model_parts number of model parts
345 USERD_get_gold_part_build_info Gets the info needed for part building process
346 USERD_get_part_build_info part/block type/descrip etc.
347 USERD_get_maxsize_info part/block allocation maximums
348 USERD_get_ghosts_in_model_flag model contains ghost cells?
349 USERD_get_nsided_conn Gets the element connectivities for nsided
350 elements. (utilizes the number of nodes
351 per element obtained in
352 USERD_get_part_elements_by_type)
353 USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced
354 elements (utilizes the number of faces
355 per element obtained in
356 USERD_get_part_elements_by_type)
357 USERD_get_nfaced_conn Gets the element connectivities for nfaced
358 elements (utilizes the number of nodes
359 per face obtained in
360 USERD_get_nfaced_nodes_per_face)
363 USERD_get_border_availability part border provided?
364 USERD_get_border_elements_by_type part border conn and parent info
366 USERD_get_number_of_variables number of variables
367 USERD_get_gold_variable_info variable type/descrip etc.
368 USERD_get_var_by_component part or block variable values
369 USERD_get_constant_val constant variable's value
370 USERD_get_var_value_at_specific node's or element's variable value over time
371 USERD_stop_part_building cleanup after part build routine
373 USERD_get_number_of_material_sets Gets the number of material sets
374 USERD_get_matf_set_info Gets the material set indices and names
375 USERD_get_number_of_materials Gets the number of materials
376 USERD_get_matf_var_info Gets the material indices and descriptions
377 USERD_size_matf_data Gets the length of either the
378 material ids list,
379 mixed-material ids list, or
380 mixed-material values list
381 USERD_load_matf_data Gets the material ids list,
382 mixed-material ids list, or
383 mixed-material values list
385 USERD_bkup archive routine
387 USERD_exit_routine cleanup upon exit routine
389 USERD_get_uns_failed_params Gets thresholds/criteria for failure
391 USERD_rigidbody_existence Returns whether rigid body transformation
392 data exists for the model.
393 USERD_rigidbody_values Returns the euler and location values for a
394 given part
396 USERD_set_right_side Simply informs the reader when the time set
397 is for the right side of a time span during
398 variable interpolation between time steps.
400 USERD_get_structured_reader_cinching Tells if the reader will do structured
401 cinching
402 USERD_set_block_range_and_stride Sets the min, max, and stride of a block
403 if doing structured cinching
406 -------------------------
407 Order Routines are called
408 -------------------------
410 The various main operations are given basically in the order they will
411 be performed. Within each operation, the order the routines will be
412 called is given.
414 1. Setting name in the gui, and specifying one or two input fields
416 USERD_get_name_of_reader
417 USERD_get_reader_descrip (optional)
418 USERD_get_extra_gui_numbers (optional)
419 USERD_get_extra_gui_defaults (optional)
421 2. Getting the reader version (also distinguishes between API's)
423 USERD_get_reader_version
425 3. Setting filenames and getting timeset and time info
427 <USERD_set_extra_gui_data> (optional if reader has
428 USERD_get_extra_gui_defaults routine)
429 USERD_get_structured_reader_cinching
430 USERD_set_server_number
431 USERD_set_extra_gui_data (optional)
432 USERD_set_filenames
433 USERD_get_number_of_timesets
434 USERD_get_geom_timeset_number
436 for each timeset:
437 USERD_get_timeset_description
438 USERD_get_num_of_time_steps
439 USERD_get_sol_times
441 USERD_set_time_set_and_step
443 4. Gathering info for part builder
445 USERD_set_time_set_and_step
446 USERD_get_changing_geometry_status
447 USERD_get_node_label_status
448 USERD_get_element_label_status
449 USERD_get_number_of_files_in_dataset
450 USERD_get_dataset_query_file_info
451 USERD_get_descrip_lines (for geometry)
452 USERD_get_number_of_model_parts
453 USERD_get_gold_part_build_info
454 USERD_get_ghosts_in_model_flag
455 USERD_get_maxsize_info
456 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
457 USERD_get_model_extents OR (for model extents)
458 USERD_get_part_coords AND/OR
459 <USERD_set_block_range_and_stride> (if doing structured reader cinching
460 USERD_get_block_coords_by_component
462 5. Gathering Variable info
464 USERD_get_number_of_variables
465 USERD_get_gold_variable_info
467 6. Part building (per part created)
469 both unstructured and structured:
470 --------------------------------
471 USERD_set_time_set_and_step
473 if unstructured part:
474 --------------------
475 USERD_get_part_element_ids_by_type
476 USERD_get_part_elements_by_type
478 If any nsided elements:
480 USERD_get_nsided_conn
482 If any nfaced elements:
484 USERD_get_nfaced_nodes_per_face
485 USERD_get_nfaced_conn
487 USERD_get_part_coords
488 USERD_get_part_node_ids
490 else if structured part:
491 -----------------------
492 USERD_get_block_iblanking
493 <USERD_set_block_range_and_stride> (if doing structured reader cinching
494 USERD_get_block_coords_by_component
495 USERD_get_block_ghost_flags (If ghost cells in part)
496 USERD_get_part_node_ids (If node ids given)
497 USERD_get_part_element_ids_by_type (If element ids given)
499 both again:
500 ----------
501 USERD_get_border_availability (If border representation
502 USERD_get_border_elements_by_type is selected)
504 USERD_stop_part_building (only once when part builder
505 dialog is closed)
507 7. Loading Variables
509 constants:
510 ---------
511 USERD_set_time_set_and_step
512 USERD_get_constant_val
514 scalars/vectors/tensors:
515 ------------------------
516 USERD_get_descrip_lines
517 USERD_set_time_set_and_step
518 <USERD_set_block_range_and_stride> (if doing structured reader cinching
519 USERD_get_var_by_component
521 8. Changing geometry
523 changing coords only (per part):
524 --------------------
525 USERD_set_time_set_and_step
526 USERD_get_descrip_lines
527 USERD_get_part_coords
528 <USERD_set_block_range_and_stride> (if doing structured reader cinching
529 USERD_get_block_coords_by_component
531 changing connectivity (per part):
532 ---------------------
533 USERD_set_time_set_and_step
534 USERD_get_descrip_lines
535 USERD_get_number_of_model_parts
536 USERD_get_gold_part_build_info
537 USERD_get_ghosts_in_model_flag
538 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
539 USERD_get_model_extents OR
540 USERD_get_part_coords AND/OR
541 <USERD_set_block_range_and_stride> (if doing structured reader cinching
542 USERD_get_block_coords_by_component
543 USERD_get_part_element_ids_by_type
544 USERD_get_part_elements_by_type
545 USERD_get_part_coords
546 USERD_get_part_node_ids
547 USERD_get_block_iblanking
548 <USERD_set_block_range_and_stride> (if doing structured reader cinching
549 USERD_get_block_coords_by_component
550 USERD_get_block_ghost_flags (If ghost cells in part)
551 USERD_get_part_node_ids (If node ids given)
552 USERD_get_part_element_ids_by_type (If element ids given)
554 USERD_get_border_availability (If border representation
555 USERD_get_border_elements_by_type is selected)
558 9. Node or Element queries over time
560 USERD_get_var_value_at_specific
562 10. To see if materials in the model
564 USERD_get_number_of_material_sets
565 USERD_get_matf_set_info
567 If any material sets in the model (calls these once per material set):
568 USERD_get_number_of_materials
569 USERD_get_matf_var_info
571 For each elment type of each part containing material ids, calls:
572 USERD_size_matf_data
573 USERD_load_matf_data
575 If there are any elements with mixed materials, when a domain or
576 interface is created, calls these again per part:
578 USERD_size_matf_data
579 USERD_load_matf_data
581 11. To modify the variable extraction parameters and have the variables
582 update accordingly.
584 USERD_get_var_extract_gui_numbers
585 USERD_get_var_extract_gui_defaults
586 USERD_set_var_extract_gui_data
590 -----------------------
591 Detailed Specifications
592 -----------------------
594 Include files:
595 --------------
596 The following header file is required in any file containing these library
597 routines.
599 #include "global_extern.h"
601 And it references:
603 #include "global_extern_proto.h"
607 *******************************************************************************
608 ****************************** Special Note ***********************************
609 *******************************************************************************
611 Make sure you use the proper define in the global_extern.h header file, namely:
612 #define USERD_API_204
614 Also, Make sure the api version in the USERD_get_reader_version routine is set
615 to "2.04" or larger.
617 Make sure your reader has access to the global_extern_proto.h This is a new
618 file which is accessed from the new global_extern.h
620 *******************************************************************************
621 *******************************************************************************
624 Basis of arrays:
625 ---------------
626 Unless explicitly stated otherwise, all arrays are zero based - in true C
627 fashion.
630 Global variables:
631 ----------------
632 You will generally need to have a few global variables which are shared by
633 the various library routines. The detailed specifications below have assumed
634 the following are available. (Their names describe their purpose, and they
635 will be used in helping describe the details of the routines below).
637 static int Numparts_available = 0;
638 static int Num_unstructured_parts = 0;
639 static int Num_structured_blocks = 0;
641 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
643 static int Num_timesets = 1;
644 static int Current_timeset = 1;
645 static int Geom_timeset_number = 1;
647 static int Num_time_steps[Z_MAXSETS] = 1;
648 static int Current_time_step = 0;
649 static int Num_variables = 0;
650 static int Num_dataset_files = 0;
652 static int Server_Number = 1; Which server of
653 static int Tot_Servers = 1; the total number of servers
657 _________________________________________
658 -----------------------------------------
659 Library Routines (in alphabetical order):
660 _________________________________________
661 -----------------------------------------
663 --------------------------------------------------------------------
664 USERD_bkup
666 Description:
667 -----------
668 This routine is called during the EnSight archive process. You can
669 use it to save or restore info relating to your user defined reader.
671 Specification:
672 -------------
673 int USERD_bkup(FILE *archive_file,
674 int backup_type)
676 Returns:
677 -------
678 Z_OK if successful
679 Z_ERR if not successful
681 Arguments:
682 ---------
683 (IN) archive_file = The archive file pointer
685 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
686 Z_REST_ARCHIVE for restoring archive
688 Notes:
689 -----
690 * Since EnSight's archive file is saved in binary form, you should
691 also do any writing to it or reading from it in binary.
693 * You should archive any variables, which will be needed for
694 future operations, that will not be read or computed again
695 before they will be needed. These are typically global
696 variables.
698 * Make sure that the number of bytes that you write on a save and
699 the number of bytes that you read on a restore are identical!!
701 * If any of the variables you save are allocated arrays, you must
702 do the allocations before restoring into them.
704 --------------------------------------------------------------------
705 USERD_exit_routine
707 Description:
708 -----------
709 This routine is called as EnSight is exiting. It can be used to clean
710 up anything needed - such as removing temporary files, etc. - or can simply
711 be a dummy.
713 Specification:
714 -------------
715 void USERD_exit_routine( void )
717 Arguments:
718 ---------
719 none
721 --------------------------------------------------------------------
722 USERD_get_block_coords_by_component
724 Description:
725 -----------
726 Get the coordinates of a given structured block, a component at a time.
728 Specification:
729 -------------
730 int USERD_get_block_coords_by_component(int block_number,
731 int which_component,
732 float *coord_array)
734 Returns:
735 -------
736 Z_OK if successful
737 Z_ERR if not successful
739 Arguments:
740 ---------
741 (IN) block_number = The block part number
742 (1-based index of part table, namely:
744 1 ... Numparts_available.
746 It is NOT the part_id that
747 is loaded in USERD_get_gold_part_build_info)
749 (IN) which_component = Z_COMPX if x component wanted
750 = Z_COMPY if y component wanted
751 = Z_COMPZ if z component wanted
753 (OUT) coord_array = 1D array containing x,y, or z
754 coordinate component of each node
756 (Array will have been allocated
757 i*j*k for the block long)
759 Notes:
760 -----
761 * Not called unless Num_structured_blocks is > 0
763 * Will be based on Current_time_step
767 --------------------------------------------------------------------
768 USERD_get_block_iblanking
770 Description:
771 -----------
772 Get the iblanking value at each node of a block (if the block is
773 iblanked).
775 Specification:
776 -------------
777 int USERD_get_block_iblanking(int block_number,
778 int *iblank_array)
780 Returns:
781 -------
782 Z_OK if successful
783 Z_ERR if not successful
785 Arguments:
786 ---------
787 (IN) block_number = The block part number
788 (1-based index of part table, namely:
790 1 ... Numparts_available.
792 It is NOT the part_id that
793 is loaded in USERD_get_gold_part_build_info)
795 (OUT) iblank_array = 1D array containing iblank value
796 for each node.
798 (Array will have been allocated
799 i*j*k for the block long)
801 possible values are: Z_EXT = exterior
802 Z_INT = interior
803 Z_BND = boundary
804 Z_INTBND = internal boundary
805 Z_SYM = symmetry plane
807 Notes:
808 -----
809 * Not called unless Num_structured_blocks is > 0 and you have
810 some iblanked blocks
812 * Will be based on Current_time_step
816 ----------------------------------------------------------------------
817 USERD_get_block_ghost_flags
819 Description:
820 -----------
821 Get the ghost_flags value at each element of a block containing ghost cells.
823 Specification:
824 -------------
825 int USERD_get_block_ghost_flags(int block_number,
826 int *ghost_flags)
827 Returns:
828 -------
829 Z_OK if successful
830 Z_ERR if not successful
832 Arguments:
833 ---------
834 (IN) block_number = The block number
835 (1-based index of part table, namely:
837 1 ... Numparts_available.
839 It is NOT the part_id that
840 is loaded in USERD_get_gold_part_build_info)
842 (OUT) ghost_flags = 1D array containing ghost flag value
843 for each block cell.
845 (Array will have been allocated
846 (i-1)*(j-1)*(k-1) for the block long)
848 possible values are: 0 = non-ghost cell (normal cell)
849 >0 = ghost cell
851 Notes:
852 -----
853 * This routine is new in the 2.01 API
855 * This will be based on Current_time_step
857 * Only called for structured "block" parts that have some ghost cells
858 as indicated by the USERD_get_ghost_in_block_flag. The model must
859 of course also have been indicated to have some ghost cells in the
860 USERD_get_ghost_in_model_flag routine.
862 * It is sufficient to set the value to be 1 to flag as a ghost cell,
863 but the value can be any non-zero value, so you could use it to
864 indicate which block or which server (for Server-of-server use) the
865 cell is actually in.
869 --------------------------------------------------------------------
870 USERD_get_border_availability
872 Description:
873 -----------
874 Finds out if border elements are provided by the reader for the
875 desired part, or will need to be computed internally by EnSight.
877 Specification:
878 -------------
879 int USERD_get_border_availability(int part_number,
880 int number_of_elements[Z_MAXTYPE])
882 Returns:
883 -------
884 Z_OK if border elements will be provided by the reader.
885 (number_of_elements array will be loaded and
886 USERD_get_border_elements_by_type will be called)
888 Z_ERR if border elements are not available - thus EnSight must compute.
889 (USERD_get_border_elements_by_type will not be called)
892 Arguments:
893 ---------
894 (IN) part_number = The part number
895 (1-based index of part table, namely:
897 1 ... Numparts_available.
899 It is NOT the part_id that
900 is loaded in USERD_get_gold_part_build_info)
902 (OUT) number_of_elements = 2D array containing number of
903 each type of border element in
904 the part.
905 ------------
906 Possible types are:
908 Z_POINT = point
909 Z_BAR02 = 2-noded bar
910 Z_BAR03 = 3-noded bar
911 Z_TRI03 = 3-noded triangle
912 Z_TRI06 = 6-noded triangle
913 Z_QUA04 = 4-noded quadrilateral
914 Z_QUA08 = 8-noded quadrilateral
916 Notes:
917 -----
918 * Only called if border representation is used.
920 * Will be based on Current_time_step
924 --------------------------------------------------------------------
925 USERD_get_border_elements_by_type
927 Description:
928 -----------
929 Provides border element connectivity and parent information.
931 Specification:
932 -------------
933 int USERD_get_border_elements_by_type(int part_number,
934 int element_type,
935 int **conn_array,
936 short *parent_element_type,
937 int *parent_element_num)
939 Returns:
940 -------
941 Z_OK if successful
942 Z_ERR if not successful
944 Arguments:
945 ---------
946 (IN) part_number = The part number
947 (1-based index of part table, namely:
949 1 ... Numparts_available.
951 It is NOT the part_id that
952 is loaded in USERD_get_gold_part_build_info)
954 (IN) element_type = One of the following (See global_extern.h)
955 Z_POINT node point element
956 Z_BAR02 2 node bar
957 Z_BAR03 3 node bar
958 Z_TRI03 3 node triangle
959 Z_TRI06 6 node triangle
960 Z_QUA04 4 node quad
961 Z_QUA08 8 node quad
963 (OUT) conn_array = 2D array containing connectivity
964 of each border element of the type.
966 (Array will have been allocated
967 num_of_elements of the type by
968 connectivity length of the type)
970 ex) If number_of_elements[Z_TRI03] = 25
971 number_of_elements[Z_QUA04] = 100
972 number_of_elements[Z_QUA08] = 30
973 as obtained in:
974 USERD_get_border_availability
976 Then the allocated dimensions available
977 for this routine will be:
978 conn_array[25][3] when called with Z_TRI03
980 conn_array[100][4] when called with Z_QUA04
982 conn_array[30][8] when called with Z_QUA08
984 (OUT) parent_element_type = 1D array containing element type of the
985 parent element (the one that the border
986 element is a face/edge of).
988 (Array will have been allocated
989 num_of_elements of the type long)
991 (OUT) parent_element_num = 1D array containing element number of the
992 parent element (the one that the border
993 element is a face/edge of).
995 (Array will have been allocated
996 num_of_elements of the type long)
999 Notes:
1000 -----
1001 * Not called unless USERD_get_border_availability returned Z_OK
1003 * Will be based on Current_time_step
1007 --------------------------------------------------------------------
1008 USERD_get_changing_geometry_status
1010 Description:
1011 -----------
1012 Gets the changing geometry status for the model
1014 Specification:
1015 -------------
1016 int USERD_get_changing_geometry_status( void )
1018 Returns:
1019 -------
1020 Z_STATIC if geometry does not change
1021 Z_CHANGE_COORDS if changing coordinates only
1022 Z_CHANGE_CONN if changing connectivity
1024 Arguments:
1025 ---------
1026 none
1028 Notes:
1029 -----
1030 * EnSight does not support changing number of parts. But the
1031 coords and/or the connectivity of the parts can change. Note that
1032 a part is allowed to be empty (number of nodes and elements equal
1033 to zero).
1036 --------------------------------------------------------------------
1037 USERD_get_constant_val
1039 Description:
1040 -----------
1041 Get the value of a constant at a time step
1043 Specification:
1044 -------------
1045 float USERD_get_constant_value(int which_var,
1046 int imag_data)
1048 Returns:
1049 -------
1050 Value of the requested constant variable
1052 Arguments:
1053 ---------
1054 (IN) which_var = The variable number
1056 (IN) imag_data = TRUE if want imaginary data value.
1057 FALSE if want real data value.
1059 Notes:
1060 -----
1061 * Will be based on Current_time_step
1065 --------------------------------------------------------------------
1066 USERD_get_dataset_query_file_info
1068 Description:
1069 -----------
1070 Get the information about files in the dataset. Used for the
1071 dataset query option within EnSight.
1073 Specification:
1074 -------------
1075 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
1077 Returns:
1078 -------
1079 Z_OK if successful
1080 Z_ERR if not successful
1082 Arguments:
1083 ---------
1084 (OUT) qfiles = Structure containing information about each file
1085 of the dataset. The Z_QFILES structure is defined
1086 in the global_extern.h file
1088 (The structure will have been allocated
1089 Num_dataset_files long, with 10 description
1090 lines per file).
1092 qfiles[].name = The name of the file
1093 (Z_MAXFILENP is the dimensioned length
1094 of the name)
1096 qfiles[].sizeb = The number of bytes in the file
1097 (Typically obtained with a call to the
1098 "stat" system routine) (Is a long)
1100 qfiles[].timemod = The time the file was last modified
1101 (Z_MAXTIMLEN is the dimensioned length
1102 of this string)
1103 (Typically obtained with a call to the
1104 "stat" system routine)
1106 qfiles[].num_d_lines = The number of description lines you
1107 are providing from the file. Max = 10
1109 qfiles[].f_desc[] = The description line(s) per file,
1110 qfiles[].num_d_lines of them
1111 (Z_MAXFILENP is the allocated length of
1112 each line)
1114 Notes:
1115 -----
1116 * If Num_dataset_files is 0, this routine will not be called.
1117 (See USERD_get_number_of_files_in_dataset)
1120 --------------------------------------------------------------------
1121 USERD_get_descrip_lines
1123 Description:
1124 -----------
1125 Get two description lines associated with geometry per time step,
1126 or one description line associated with a variable per time step.
1128 Specification:
1129 -------------
1130 int USERD_get_descrip_lines(int which_type,
1131 int which_var,
1132 int imag_data,
1133 char line1[Z_BUFL],
1134 char line2[Z_BUFL])
1136 Returns:
1137 -------
1138 Z_OK if successful
1139 Z_ERR if not successful
1141 Arguments:
1142 ---------
1143 (IN) which_type = Z_GEOM for geometry (2 lines)
1144 = Z_VARI for variable (1 line)
1146 (IN) which_var = If it is a variable, which one.
1147 Ignored if geometry type.
1149 (IN) imag_data = TRUE if want imaginary data file.
1150 FALSE if want real data file.
1152 (OUT) line1 = The 1st geometry description line,
1153 or the variable description line.
1155 (OUT) line2 = The 2nd geometry description line
1156 Not used if variable type.
1158 Notes:
1159 -----
1160 * Will be based on Current_time_step
1162 * These are the lines EnSight can echo to the screen in
1163 annotation mode.
1167 --------------------------------------------------------------------
1168 USERD_get_element_label_status
1170 Description:
1171 -----------
1172 Answers the question as to whether element labels will be provided.
1174 Specification:
1175 -------------
1176 int USERD_get_element_label_status( void )
1178 Returns:
1179 -------
1180 TRUE if element labels will be provided
1181 FALSE if element labels will NOT be provided
1183 Arguments:
1184 ---------
1185 none
1187 Notes:
1188 -----
1189 * element lables are needed in order to do any element querying, or
1190 element labeling on-screen within EnSight.
1192 * Prior to API 2.01:
1193 -----------------
1194 For unstructured parts, you can read them from your file if
1195 available, or can assign them, etc. They need to be unique
1196 per part, and are often unique per model.
1198 API 1.0:
1199 USERD_get_element_ids_for_part is used to obtain the ids,
1200 on a part by part basis, if TRUE status is returned here.
1202 API 2.0:
1203 USERD_get_part_element_ids_by_type is used to obtain the ids,
1204 on a per part, per type basis, if TRUE status is returned here.
1206 For structured parts, EnSight will assign ids if you return a
1207 status of TRUE here. You cannot assign them youself!!
1209 * Starting at API 2.01:
1210 --------------------
1211 For both unstructured and structured parts, you can read them
1212 from your file if available, or can assign them, etc. They need
1213 to be unique per part, and are often unique per model (especially
1214 if you are dealing with a decomposed dataset).
1216 USERD_get_part_element_ids_by_type is used to obtain the ids,
1217 on an element type by part basis, if TRUE status is returned here.
1219 * Will call USERD_get_part_element_ids_by_type for each type of
1220 of each part if this routine returns TRUE.
1221 --------------------------------------------------------------------
1222 USERD_get_geom_timeset_number -
1224 Description:
1225 -----------
1226 Gets the timeset number to be used for geometry
1228 Specification:
1229 -------------
1230 int USERD_get_geom_timeset_number( void )
1232 Returns:
1233 -------
1234 Geom_timeset_number = The timeset number that will be used for geometry.
1235 For example, if USERD_get_number_of timesets
1236 returns 2, the valid timeset numbers would be
1237 1 or 2.
1239 Arguments:
1240 ---------
1241 none
1243 Notes:
1244 -----
1245 * If your model is static, which you indicated by returning a zero
1246 in USERD_get_number_of_timesets, you can return a zero here as well.
1250 --------------------------------------------------------------------
1251 USERD_get_gold_part_build_info
1253 Description:
1254 -----------
1255 Gets the info needed for the part building process.
1257 Specification:
1258 -------------
1259 int USERD_get_gold_part_build_info(int *part_id,
1260 int *part_types,
1261 char *part_description[Z_BUFL],
1262 int *number_of_nodes,
1263 int *number_of_elements[Z_MAXTYPE],
1264 int *ijk_dimensions[9],
1265 int *iblanking_options[6])
1267 Returns:
1268 -------
1269 Z_OK if successful
1270 Z_ERR if not successful
1272 Arguments:
1273 ---------
1274 (OUT) part_id = Array containing the external part
1275 ids for each of the model parts.
1277 IMPORTANT:
1278 Parts numbers must be >= 1, because
1279 of the way they are used in the GUI
1281 *******************************************
1282 The ids provided here are the numbers by
1283 which the parts will be referred to in the
1284 GUI (if possible). They are basically
1285 labels as far as you are concerned.
1287 Note: The part numbers you pass to routines
1288 which receive a part_number or block_number
1289 or which_part as an argument are the 1-based
1290 table index of the parts!
1292 example: If Numparts_available = 3
1294 Table index part_id
1295 ----------- -------
1296 1 13
1297 2 57
1298 3 125
1300 ^ ^
1301 | |
1302 | These are placed in:
1303 | part_id[0] = 13
1304 | part_id[1] = 57
1305 | part_id[2] = 125
1306 | for GUI labeling purposes.
1307 |
1308 These implied table indices are the part_number,
1309 block_number, or which_part numbers that you would
1310 pass to routines like:
1312 USERD_get_part_coords(int part_number,...
1313 USERD_get_part_node_ids(int part_number,...
1314 USERD_get_part_elements_by_type(int part_number,...
1315 USERD_get_part_element_ids_by_type(int part_number,...
1316 USERD_get_block_coords_by_component(int block_number,...
1317 USERD_get_block_iblanking(int block_number,...
1318 USERD_get_block_ghost_flags(int block_number,...
1319 USERD_get_ghosts_in_block_flag(int block_number)
1320 USERD_get_border_availability(int part_number,...
1321 USERD_get_border_elements_by_type(int part_number,...
1322 USERD_get_var_by_component(int which_variable,
1323 int which_part,...
1324 USERD_get_var_value_at_specific(int which_var,
1325 int which_node_or_elem,
1326 int which_part,...
1327 ********************************************
1329 (Array will have been allocated
1330 Numparts_available long)
1332 (OUT) part_types = Array containing one of the
1333 following for each model part:
1335 Z_UNSTRUCTURED or
1336 Z_STRUCTURED or
1337 Z_IBLANKED
1339 (Array will have been allocated
1340 Numparts_available long)
1342 (OUT) part_description = Array containing a description
1343 for each of the model parts
1345 (Array will have been allocated
1346 Numparts_available by Z_BUFL
1347 long)
1349 (OUT) number_of_nodes = Number of unstructured nodes in the part
1351 (Array will have been allocated
1352 Numparts_available long)
1354 (OUT) number_of_elements = 2D array containing number of
1355 each type of element for each
1356 unstructured model part.
1357 ------------
1358 Possible types are:
1360 Z_POINT = point
1361 Z_BAR02 = 2-noded bar
1362 Z_BAR03 = 3-noded bar
1363 Z_TRI03 = 3-noded triangle
1364 Z_TRI06 = 6-noded triangle
1365 Z_QUA04 = 4-noded quadrilateral
1366 Z_QUA08 = 8-noded quadrilateral
1367 Z_TET04 = 4-noded tetrahedron
1368 Z_TET10 = 10-noded tetrahedron
1369 Z_PYR05 = 5-noded pyramid
1370 Z_PYR13 = 13-noded pyramid
1371 Z_PEN06 = 6-noded pentahedron
1372 Z_PEN15 = 15-noded pentahedron
1373 Z_HEX08 = 8-noded hexahedron
1374 Z_HEX20 = 20-noded hexahedron
1376 Z_G_POINT = ghost node point element
1377 Z_G_BAR02 = 2 node ghost bar
1378 Z_G_BAR03 = 3 node ghost bar
1379 Z_G_TRI03 = 3 node ghost triangle
1380 Z_G_TRI06 = 6 node ghost triangle
1381 Z_G_QUA04 = 4 node ghost quad
1382 Z_G_QUA08 = 8 node ghost quad
1383 Z_G_TET04 = 4 node ghost tetrahedron
1384 Z_G_TET10 = 10 node ghost tetrahedron
1385 Z_G_PYR05 = 5 node ghost pyramid
1386 Z_G_PYR13 = 13 node ghost pyramid
1387 Z_G_PEN06 = 6 node ghost pentahedron
1388 Z_G_PEN15 = 15 node ghost pentahedron
1389 Z_G_HEX08 = 8 node ghost hexahedron
1390 Z_G_HEX20 = 20 node ghost hexahedron
1392 (Ignored unless Z_UNSTRUCTURED type)
1394 (Array will have been allocated
1395 Numparts_available by
1396 Z_MAXTYPE long)
1398 (OUT) ijk_dimensions = 2D array containing ijk dimension info
1399 for structured blocks
1401 For Z_UNSTRUCTURED - is ignored
1403 For Z_STRUCTURED or Z_IBLANKED
1405 Prior to version 2.03:
1406 ----------------------
1407 (Array will have been allocated
1408 Numparts_available by 3 long)
1410 ijk_dimensions[][0] = I dimension
1411 ijk_dimensions[][1] = J dimension
1412 ijk_dimensions[][2] = K dimension
1415 Starting at version 2.03:
1416 ------------------------
1417 (Array will have been allocated
1418 Numparts_available by 9 long)
1420 There are two ways to do this:
1421 ------------------------------
1422 1. The simple one, without ranges.
1424 This is good for all structured models
1425 that will NOT be used in EnSight's
1426 Server of Servers
1428 Simply provide the ijk dimensions in the
1429 first three slots and place a -1 in
1430 the 4th slot. (The remaining slots will
1431 be ignored).
1433 Thus,
1434 ijk_dimensions[][0] = I dimension of block
1435 ijk_dimensions[][1] = J dimension of block
1436 ijk_dimensions[][2] = K dimension of block
1437 ijk_dimensions[][3] = -1
1439 (J planes)
1440 4 *-------*-------*
1441 | | | ijk_dimension[0][0] = 3
1442 | | | ijk_dimension[0][1] = 4
1443 | | | ijk_dimension[0][2] = 1
1444 3 *-------*-------*
1445 | | | ijk_dimension[0][4] = -1
1446 | | |
1447 | | |
1448 2 *-------*-------*
1449 | | |
1450 | | |
1451 | | |
1452 1 *-------*-------*
1453 1 2 3 (I planes)
1457 2. Using ranges.
1459 This one can be used anytime, but MUST
1460 be used if EnSight's Server of Servers
1461 is to be used!
1463 The first 3 slots contain the ijk dimension
1464 of the complete block (of which this may be
1465 a portion). The last 6 slots contain the
1466 ijk min and max ranges within the complete.
1468 Thus,
1469 ijk_dimensions[][0] = I dim of complete block
1470 ijk_dimensions[][1] = J dim of complete block
1471 ijk_dimensions[][2] = K dim of complete block
1473 ijk_dimensions[][3] = Imin of portion (1-based)
1474 ijk_dimensions[][4] = Imax of portion (1-based)
1475 ijk_dimensions[][5] = Jmin of portion (1-based)
1476 ijk_dimensions[][6] = Jmax of portion (1-based)
1477 ijk_dimensions[][7] = Kmin of portion (1-based)
1478 ijk_dimensions[][8] = Kmax of portion (1-based)
1481 example1: (Model has one part, a simple 2D block,
1482 and want whole thing)
1484 (J planes)
1485 4 *-------*-------*
1486 | | | ijk_dimension[0][0] = 3
1487 | | | ijk_dimension[0][1] = 4
1488 | | | ijk_dimension[0][2] = 1
1489 3 *-------*-------*
1490 | | | ijk_dimension[0][3] = 1
1491 | | | ijk_dimension[0][4] = 3
1492 | | | ijk_dimension[0][5] = 1
1493 2 *-------*-------* ijk_dimension[0][6] = 4
1494 | | | ijk_dimension[0][7] = 1
1495 | | | ijk_dimension[0][8] = 1
1496 | | |
1497 1 *-------*-------*
1498 1 2 3 (I planes)
1501 example2: (Want to have the block represented
1502 in two portions - 2 parts)
1504 (J planes) top portion
1505 4 *-------*-------*
1506 | | | ijk_dimension[0][0] = 3
1507 | | | ijk_dimension[0][1] = 4
1508 | | | ijk_dimension[0][2] = 1
1509 3 *-------*-------*
1510 . . . ijk_dimension[0][3] = 1
1511 . . . ijk_dimension[0][4] = 3
1512 . . . ijk_dimension[0][5] = 3
1513 2 ................. ijk_dimension[0][6] = 4
1514 . . . ijk_dimension[0][7] = 1
1515 . . . ijk_dimension[0][8] = 1
1516 . . .
1517 1 .................
1518 1 2 3 (I planes)
1521 (J planes) bottom portion
1522 4 .................
1523 . . . ijk_dimension[1][0] = 3
1524 . . . ijk_dimension[2][1] = 4
1525 . . . ijk_dimension[3][2] = 1
1526 3 *-------*-------*
1527 | | | ijk_dimension[1][3] = 1
1528 | | | ijk_dimension[1][4] = 3
1529 | | | ijk_dimension[1][5] = 1
1530 2 *-------*-------* ijk_dimension[1][6] = 3
1531 | | | ijk_dimension[1][7] = 1
1532 | | | ijk_dimension[1][8] = 1
1533 | | |
1534 1 *-------*-------*
1535 1 2 3 (I planes)
1538 And note that if you were partioning this block for
1539 EnSight's Server of Servers, you would only have one part,
1540 instead of two. Each SOS server would return its appropriate
1541 ranges in the last 6 slots. The first 3 slots would remain constant.
1544 (OUT) iblanking_options = 2D array containing iblanking
1545 options possible for each
1546 structured model part.
1547 ----------
1548 (Ignored unless Z_IBLANKED type)
1550 (Array will have been allocated
1551 Numparts_available by 6 long)
1553 iblanking_options[][Z_EXT] = TRUE if external (outside)
1554 [][Z_INT] = TRUE if internal (inside)
1555 [][Z_BND] = TRUE if boundary
1556 [][Z_INTBND] = TRUE if internal boundary
1557 [][Z_SYM] = TRUE if symmetry surface
1560 Notes:
1561 -----
1562 * If you haven't built a table of pointers to the different parts,
1563 you might want to do so here as you gather the needed info.
1565 * Will be based on Current_time_step
1568 --------------------------------------------------------------------
1569 USERD_get_gold_variable_info
1571 Description:
1572 -----------
1573 Get the variable descriptions, types and filenames
1575 Specification:
1576 -------------
1577 int USERD_get_gold_variable_info(char **var_description,
1578 char **var_filename,
1579 int *var_type,
1580 int *var_classify,
1581 int *var_complex,
1582 char **var_ifilename,
1583 float *var_freq,
1584 int *var_contran,
1585 int *var_timeset)
1587 Returns:
1588 -------
1589 Z_OK if successful
1590 Z_ERR if not successful
1592 Arguments:
1593 ---------
1594 (OUT) var_description = Variable descriptions
1596 (Array will have been allocated
1597 Num_variables by Z_BUFL long)
1599 variable description restrictions:
1600 ----------------------------------
1601 1. Only first 19 characters used in EnSight.
1602 2. Leading and trailing whitespace will be removed by EnSight.
1603 3. Illegal characters will be replaced by underscores.
1604 4. Thay may not start with a numeric digit.
1605 4. No two variables may have the same description.
1608 (OUT) var_filename = Variable real filenames
1610 (Array will have been allocated
1611 Num_variables by Z_BUFL long)
1613 (OUT) var_type = Variable type
1615 (Array will have been allocated
1616 Num_variables long)
1618 types are: Z_CONSTANT
1619 Z_SCALAR
1620 Z_VECTOR
1621 Z_TENSOR
1622 Z_TENSOR9
1624 (OUT) var_classify = Variable classification
1626 (Array will have been allocated
1627 Num_variables long)
1629 types are: Z_PER_NODE
1630 Z_PER_ELEM
1632 (OUT) var_complex = TRUE if complex, FALSE otherwise
1634 (Array will have been allocated
1635 Num_variables long)
1637 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1639 (Array will have been allocated
1640 Num_variables by Z_BUFL long)
1642 (OUT) var_freq = complex frequency (if complex)
1644 (Array will have been allocated
1645 Num_variables long)
1647 (OUT) var_contran = TRUE if constant changes per time step
1648 FALSE if constant truly same at all time steps
1650 (Array will have been allocated
1651 Num_variables long)
1653 (OUT) var_timeset = Timeset the variable will use (1 based).
1654 (For static models, set it to 1)
1656 (Array will have been allocated
1657 Num_variables long)
1659 For example: If USERD_get_number_of_timesets
1660 returns 2, the valid
1661 timeset_number's would be 1 or 2
1664 Notes:
1665 -----
1666 * The implied variable numbers apply, but be aware that the
1667 arrays are zero based.
1668 So for variable 1, will need to provide var_description[0]
1669 var_filename[0]
1670 var_type[0]
1671 var_classify[0]
1672 var_complex[0]
1673 var_ifilename[0]
1674 var_freq[0]
1675 var_contran[0]
1676 var_timeset[0]
1679 for variable 2, will need to provide var_description[1]
1680 var_filename[1]
1681 var_type[1]
1682 var_classify[1]
1683 var_complex[1]
1684 var_ifilename[1]
1685 var_freq[1]
1686 var_contran[1]
1687 var_timeset[1]
1688 etc.
1693 --------------------------------------------------------------------
1694 USERD_get_ghosts_in_block_flag
1696 Description:
1697 -----------
1698 Gets whether ghost cells present in block or not
1700 Specification:
1701 -------------
1702 int USERD_get_ghosts_in_block_flag(int block_number)
1704 Returns:
1705 -------
1706 TRUE if any ghost cells in this structured part
1707 FALSE if no ghost cells in this structured part
1709 Arguments:
1710 ---------
1711 (IN) block_number = The block part number
1712 (1-based index of part table, namely:
1714 1 ... Numparts_available.
1716 It is NOT the part_id that
1717 is loaded in USERD_get_gold_part_build_info)
1719 Notes:
1720 -----
1721 * This routine is new in the 2.01 API
1722 * This will be based on Current_time_step
1724 * Intended for structured parts only, value will be ignored for
1725 unstructured parts
1729 --------------------------------------------------------------------
1730 USERD_get_ghosts_in_model_flag
1732 Description:
1733 -----------
1734 Answers the question as to whether any ghost cells in the model.
1736 Specification:
1737 -------------
1738 int USERD_get_ghosts_in_model_flag( void )
1740 Returns:
1741 -------
1742 TRUE if any ghost cells in the model
1743 FALSE if no ghost cells in the model
1745 Arguments:
1746 ---------
1748 Notes:
1749 -----
1750 * This routine is new in the 2.01 API
1752 -------------------------------------------------------------------------
1753 USERD_get_matf_set_info
1755 Description:
1756 -----------
1757 Get the material set ids and names
1759 Specification:
1760 -------------
1761 int USERD_get_matf_set_info(int *mat_set_ids,
1762 char **mat_set_name)
1764 Returns:
1765 -------
1766 Z_OK if successful
1767 Z_ERR if not successful
1769 Arguments:
1770 ---------
1771 (OUT) mat_set_ids = 1D material set ids array
1773 (Array will have been allocated
1774 Num_material_sets long)
1776 (OUT) mat_set_name = 2D material set name array
1778 (Array will have been allocated
1779 Num_material_sets by Z_BUFL long)
1781 Notes:
1782 -----
1783 * Will not be called if Num_material_sets is zero
1784 * See USERD_get_number_of_material_sets header for explanatory example
1787 --------------------------------------------------------------------
1788 USERD_get_matf_var_info
1790 Description:
1791 -----------
1792 Gets the material ids and descriptions for the material set
1794 Specification:
1795 -------------
1796 int USERD_get_matf_var_info(int set_index,
1797 int *mat_ids,
1798 char **mat_desc)
1800 Returns:
1801 -------
1802 Z_OK if successful
1803 Z_ERR if not successful
1805 Arguments:
1806 ---------
1807 (IN) set_index = the material set index (zero based)
1809 (OUT) mat_ids[set_index] = 1D integer array containing the material
1810 ids to associated with each material
1812 (Array will have been allocated
1813 Num_materials[set_index] long)
1815 (OUT) mat_desc[set_index] = 2D char array containing the material
1816 descriptions to associated with each material
1818 (Array will have been allocated
1819 Num_materials[set_index] by Z_BUFL long)
1821 Notes:
1822 -----
1823 * See USERD_get_number_of_material_sets header for explanatory example
1824 * Will not be called if Num_material_sets is zero, or
1825 Num_materials[set_index] is zero
1830 --------------------------------------------------------------------
1831 USERD_get_maxsize_info
1833 Description:
1834 -----------
1835 Gets maximum part sizes for efficient memory allocation.
1837 Transient models (especially those that increase in size) can cause
1838 reallocations, at time step changes, to keep chewing up more and
1839 more memory. The way to avoid this is to know what the maximum
1840 size of such memory will be, and allocate for this maximum initially.
1842 Accordingly, if you choose to provide this information (it is optional),
1843 EnSight will take advantage of it.
1846 Specification:
1847 -------------
1848 int USERD_get_maxsize_info(int *max_number_of_nodes,
1849 int *max_number_of_elements[Z_MAXTYPE],
1850 int *max_ijk_dimensions[3])
1852 Returns:
1853 -------
1854 Z_OK if supplying maximum data
1855 Z_ERR if not supplying maximum data, or some error occurred
1856 while trying to obtain it.
1858 Arguments:
1859 ---------
1860 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1861 in the part (over all time).
1863 (Array will have been allocated
1864 Numparts_available long)
1866 (OUT) max_number_of_elements = 2D array containing maximum number of
1867 each type of element for each
1868 unstructured model part (over all time).
1869 ------------
1870 Possible types are:
1872 Z_POINT = point
1873 Z_BAR02 = 2-noded bar
1874 Z_BAR03 = 3-noded bar
1875 Z_TRI03 = 3-noded triangle
1876 Z_TRI06 = 6-noded triangle
1877 Z_QUA04 = 4-noded quadrilateral
1878 Z_QUA08 = 8-noded quadrilateral
1879 Z_TET04 = 4-noded tetrahedron
1880 Z_TET10 = 10-noded tetrahedron
1881 Z_PYR05 = 5-noded pyramid
1882 Z_PYR13 = 13-noded pyramid
1883 Z_PEN06 = 6-noded pentahedron
1884 Z_PEN15 = 15-noded pentahedron
1885 Z_HEX08 = 8-noded hexahedron
1886 Z_HEX20 = 20-noded hexahedron
1888 Z_G_POINT = ghost node point element
1889 Z_G_BAR02 = 2 node ghost bar
1890 Z_G_BAR03 = 3 node ghost bar
1891 Z_G_TRI03 = 3 node ghost triangle
1892 Z_G_TRI06 = 6 node ghost triangle
1893 Z_G_QUA04 = 4 node ghost quad
1894 Z_G_QUA08 = 8 node ghost quad
1895 Z_G_TET04 = 4 node ghost tetrahedron
1896 Z_G_TET10 = 10 node ghost tetrahedron
1897 Z_G_PYR05 = 5 node ghost pyramid
1898 Z_G_PYR13 = 13 node ghost pyramid
1899 Z_G_PEN06 = 6 node ghost pentahedron
1900 Z_G_PEN15 = 15 node ghost pentahedron
1901 Z_G_HEX08 = 8 node ghost hexahedron
1902 Z_G_HEX20 = 20 node ghost hexahedron
1904 (Ignored unless Z_UNSTRUCTURED type)
1906 (Array will have been allocated
1907 Numparts_available by
1908 Z_MAXTYPE long)
1910 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1911 for each structured model part (over all time).
1912 ----------
1913 (Ignored if Z_UNSTRUCTURED type)
1915 (Array will have been allocated
1916 Numparts_available by 3 long)
1918 max_ijk_dimensions[][0] = maximum I dimension
1919 max_ijk_dimensions[][1] = maximum J dimension
1920 max_ijk_dimensions[][2] = maximum K dimension
1922 Notes:
1923 -----
1924 * You need to have first called USERD_get_number_of_model_parts and
1925 USERD_get_gold_part_build_info, so Numparts_available is known and
1926 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1927 or Z_IBLANKED) of each part.
1929 * This will NOT be based on Current_time_step - it is to be the maximum
1930 values over all time!!
1932 * This information is optional. If you return Z_ERR, Ensight will still
1933 process things fine, reallocating as needed, etc. However, for
1934 large transient models you will likely use considerably more memory
1935 and take more processing time for the memory reallocations. So, if it
1936 is possible to provide this information "up front", it is recommended
1937 to do so.
1940 --------------------------------------------------------------------
1941 USERD_get_model_extents
1943 Description:
1944 -----------
1945 Gets the model bounding box extents. If this routine supplys them
1946 EnSight will not have to spend time doing so. If this routine
1947 returns Z_ERR, EnSight will have to take the time to touch all the
1948 nodes and gather the extent info.
1950 Specification:
1951 -------------
1952 int USERD_get_model_extents(float extents[6])
1954 Returns:
1955 -------
1956 Z_OK if successful
1957 Z_ERR if not successful (whereupon EnSight will determine by reading
1958 all coords of all parts)
1960 Arguments:
1961 ---------
1962 (OUT) extents[0] = min x
1963 [1] = max x
1964 [2] = min y
1965 [3] = max y
1966 [4] = min z
1967 [5] = max z
1969 Notes:
1970 -----
1971 * This will be based on Current_time_step
1974 --------------------------------------------------------------------
1975 USERD_get_name_of_reader
1977 Description:
1978 -----------
1979 Gets the name of your user defined reader. The user interface will
1980 ask for this and include it in the available reader list.
1982 Specification:
1983 -------------
1984 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1985 int *two_fields)
1987 Returns:
1988 -------
1989 Z_OK if successful
1990 Z_ERR if not successful
1992 Arguments:
1993 ---------
1994 (OUT) reader_name = the name of the your reader or data format.
1995 (max length is Z_MAX_USERD_NAME, which is 20)
1997 (OUT) two_fields = FALSE if only one data field is
1998 required.
1999 TRUE if two data fields required
2001 -1 if one field (Geom) required
2002 and one field (Param) is optional
2003 Param field can contain any text
2004 for example a file name, modifiers,
2005 etc. that can be used to modify the
2006 reader's behavior.
2009 Notes:
2010 -----
2011 * Always called. Please be sure to provide a name for your custom
2012 reader format.
2014 --------------------------------------------------------------------
2015 USERD_get_nfaced_conn
2017 Description:
2018 -----------
2019 Gets the array containing the connectivity of nsided faces of nfaced elements
2021 Specification:
2022 -------------int
2023 int USERD_get_nfaced_conn(int part_number,
2024 int *nfaced_conn_array)
2026 Returns:
2027 -------
2028 Z_OK if successful
2029 Z_ERR if not successful
2031 Arguments:
2032 ---------
2033 (IN) part_number = the part number
2035 (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced
2036 elements
2038 (int array will have been allocated long enough to
2039 hold all the nsided face connectivities. Which is
2040 the sum of all the nodes per face values in the
2041 nfaced_npf_array of USERD_get_nfaced_nodes_per_face)
2043 Notes:
2044 -----
2045 * Will not be called unless there are some nfaced elements in the part
2047 * Providing nfaced information to Ensight:
2049 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2050 polyhedral elements in the part.
2052 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2053 the number of faces per nfaced element. (as if connectivity
2054 length of an nfaced element is one)
2056 3. In this routine, provide the streamed number of nodes per face
2057 for each of the faces of the nfaced elements.
2060 Simple example: 11 10 12
2061 +--------+-----+
2062 2 nfaced elements: /| |\ /|
2063 (1 7-faced / | | \ / |
2064 1 5-sided) / | | +9 |
2065 / | | /| |
2066 /7 | 8 / | |
2067 +-----------+/ | | |
2068 | |5 | |4 | |6
2069 | +-----|--+--|--+
2070 | / | \ | /
2071 | / | \|/3
2072 | / | +
2073 | / | /
2074 |/1 |2 /
2075 +-----------+/
2077 1. In USERD_get_gold_part_build_info:
2078 number_of_elements[Z_NFACED] = 2
2079 .
2080 /|\
2081 |
2082 2. In USERD_get_part_elements_by_type:
2083 length of conn_array will be: 2 x 1
2084 for element_type of Z_NFACED:
2085 conn_array[0][0] = 7 (for the 7-faced element)
2086 conn_array[1][0] = 5 (for the 5-faced element)
2088 ==
2089 Sum 12 <---------+
2090 |
2091 3. In USERD_get_faced_nodes_per_face: |
2092 length of nfaced_npf_array will be: 12
2094 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2095 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2096 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2097 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2098 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2099 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2100 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2102 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2103 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2104 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2105 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2106 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2108 ==
2109 Sum 48 <-------------+
2110 |
2111 4. In this function: |
2112 length of the nfaced_conn_array will be: 48
2114 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2115 nsided_conn_array[1] = 8
2116 nsided_conn_array[2] = 9
2117 nsided_conn_array[3] = 10
2118 nsided_conn_array[4] = 11
2120 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2121 nsided_conn_array[6] = 5
2122 nsided_conn_array[7] = 4
2123 nsided_conn_array[8] = 3
2124 nsided_conn_array[9] = 2
2126 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2127 nsided_conn_array[11] = 2
2128 nsided_conn_array[12] = 8
2129 nsided_conn_array[13] = 7
2131 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2132 nsided_conn_array[15] = 1
2133 nsided_conn_array[16] = 7
2134 nsided_conn_array[17] = 11
2136 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2137 nsided_conn_array[19] = 5
2138 nsided_conn_array[20] = 11
2139 nsided_conn_array[21] = 10
2141 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2142 nsided_conn_array[23] = 3
2143 nsided_conn_array[24] = 9
2144 nsided_conn_array[25] = 8
2146 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2147 nsided_conn_array[27] = 4
2148 nsided_conn_array[28] = 10
2149 nsided_conn_array[29] = 9
2151 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2152 nsided_conn_array[32] = 12
2153 nsided_conn_array[32] = 10
2155 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2156 nsided_conn_array[34] = 4
2157 nsided_conn_array[35] = 6
2159 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2160 nsided_conn_array[37] = 4
2161 nsided_conn_array[38] = 10
2162 nsided_conn_array[39] = 12
2164 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2165 nsided_conn_array[41] = 6
2166 nsided_conn_array[42] = 12
2167 nsided_conn_array[43] = 9
2169 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2170 nsided_conn_array[45] = 3
2171 nsided_conn_array[46] = 9
2172 nsided_conn_array[47] = 10
2176 --------------------------------------------------------------------
2177 USERD_get_nfaced_nodes_per_face -
2179 Description:
2180 -----------
2181 Gets the array containing the number of nodes per face for each face
2182 of the nfaced elements.
2184 Specification:
2185 -------------
2186 int USERD_get_nfaced_nodes_per_face(int part_number,
2187 int *nfaced_npf_array)
2189 Returns:
2190 -------
2191 Z_OK if successful
2192 Z_ERR if not successful
2194 Arguments:
2195 ---------
2196 (IN) part_number = the part number
2198 (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of
2199 nfaced elements
2201 (int array will have been allocated long enough
2202 to hold all the nodes_per_face values. Which is
2203 the sum of all the number of faces per element
2204 values in the conn_array of
2205 USERD_get_part_elements_by_type)
2207 Notes:
2208 -----
2209 * Will not be called unless there are some nfaced elements in the
2210 the part
2212 * Providing nfaced information to Ensight:
2214 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2215 polyhedral elements in the part.
2217 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2218 the number of faces per nfaced element. (as if connectivity
2219 length of an nfaced element is one)
2221 3. In this routine, provide the streamed number of nodes per face
2222 for each of the faces of the nfaced elements.
2225 Simple example: 11 10 12
2226 +--------+-----+
2227 2 nfaced elements: /| |\ /|
2228 (1 7-faced / | | \ / |
2229 1 5-sided) / | | +9 |
2230 / | | /| |
2231 /7 | 8 / | |
2232 +-----------+/ | | |
2233 | |5 | |4 | |6
2234 | +-----|--+--|--+
2235 | / | \ | /
2236 | / | \|/3
2237 | / | +
2238 | / | /
2239 |/1 |2 /
2240 +-----------+/
2242 1. In USERD_get_gold_part_build_info:
2243 number_of_elements[Z_NFACED] = 2
2244 .
2245 /|\
2246 |
2247 2. In USERD_get_part_elements_by_type:
2248 length of conn_array will be: 2 x 1
2249 for element_type of Z_NFACED:
2250 conn_array[0][0] = 7 (for the 7-faced element)
2251 conn_array[1][0] = 5 (for the 5-faced element)
2253 ==
2254 Sum 12 <---------+
2255 |
2256 3. In this routine: |
2257 length of nfaced_npf_array will be: 12
2259 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2260 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2261 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2262 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2263 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2264 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2265 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2267 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2268 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2269 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2270 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2271 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2273 ==
2274 Sum 48 <-------------+
2275 |
2276 4. In USERD_get_nfaced_conn: |
2277 length of the nfaced_conn_array will be: 48
2279 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2280 nsided_conn_array[1] = 8
2281 nsided_conn_array[2] = 9
2282 nsided_conn_array[3] = 10
2283 nsided_conn_array[4] = 11
2285 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2286 nsided_conn_array[6] = 5
2287 nsided_conn_array[7] = 4
2288 nsided_conn_array[8] = 3
2289 nsided_conn_array[9] = 2
2291 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2292 nsided_conn_array[11] = 2
2293 nsided_conn_array[12] = 8
2294 nsided_conn_array[13] = 7
2296 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2297 nsided_conn_array[15] = 1
2298 nsided_conn_array[16] = 7
2299 nsided_conn_array[17] = 11
2301 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2302 nsided_conn_array[19] = 5
2303 nsided_conn_array[20] = 11
2304 nsided_conn_array[21] = 10
2306 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2307 nsided_conn_array[23] = 3
2308 nsided_conn_array[24] = 9
2309 nsided_conn_array[25] = 8
2311 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2312 nsided_conn_array[27] = 4
2313 nsided_conn_array[28] = 10
2314 nsided_conn_array[29] = 9
2316 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2317 nsided_conn_array[32] = 12
2318 nsided_conn_array[32] = 10
2320 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2321 nsided_conn_array[34] = 4
2322 nsided_conn_array[35] = 6
2324 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2325 nsided_conn_array[37] = 4
2326 nsided_conn_array[38] = 10
2327 nsided_conn_array[39] = 12
2329 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2330 nsided_conn_array[41] = 6
2331 nsided_conn_array[42] = 12
2332 nsided_conn_array[43] = 9
2334 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2335 nsided_conn_array[45] = 3
2336 nsided_conn_array[46] = 9
2337 nsided_conn_array[47] = 10
2342 --------------------------------------------------------------------
2343 USERD_get_node_label_status
2345 Description:
2346 -----------
2347 Answers the question as to whether node labels will be provided.
2349 Specification:
2350 -------------
2351 int USERD_get_node_label_status( void )
2353 Returns:
2354 -------
2355 TRUE if node labels will be provided
2356 FALSE if node labels will NOT be provided
2358 Arguments:
2359 ---------
2360 none
2362 Notes:
2363 -----
2364 * Node ids are needed in order to do any node querying, or node
2365 labeling on-screen within EnSight.
2367 * Prior to API 2.01:
2368 -----------------
2369 For unstructured parts, you can read them from your file if
2370 available, or can assign them, etc. They need to be unique
2371 per part, and are often unique per model. They must also be
2372 positive numbers greater than zero.
2374 USERD_get_part_node_ids is used to obtain the ids, if the
2375 status returned here is TRUE.
2377 (Unlike API 1.0, where the connectivity of elements had to be
2378 according to the node ids - API 2.0's element connectivities
2379 are not affected either way by the status here.)
2381 For structured parts, EnSight will assign ids if you return a
2382 status of TRUE here. You cannot assign them yourself!!
2384 * Starting at API 2.01:
2385 --------------------
2386 For both unstructured and structured parts, you can read them
2387 from your file if available, or can assign them, etc. They need
2388 to be unique per part, and are often unique per model. They must
2389 also be positive numbers greater than zero.
2391 USERD_get_part_node_ids is used to obtain the ids, if the
2392 status returned here is TRUE.
2394 * Will call USERD_get_part_node_ids for each part if this routine
2395 returns TRUE.
2397 --------------------------------------------------------------------
2398 USERD_get_nsided_conn -
2400 Description:
2401 -----------
2402 Gets the array containing the connectivity of nsided elements
2404 Specification:
2405 -------------
2406 int USERD_get_nsided_conn(int part_number,
2407 int *nsided_conn_array)
2409 Returns:
2410 -------
2411 Z_OK if successful
2412 Z_ERR if not successful
2414 Arguments:
2415 ---------
2416 (IN) part_number = the part number
2418 (OUT) nsided_conn_array = 1D array of nsided connectivies
2420 (int array will have been allocated long enough
2421 to hold all the nsided connectivities. Which is
2422 the sum of all the nodes_per_element values in
2423 the conn_array of USERD_get_part_elements_by_type)
2426 Notes:
2427 -----
2428 * Will not be called unless there are some nsided elements in the the part.
2430 * Providing nsided information to Ensight:
2432 1. In USERD_get_gold_part_build_info, provide the number of nsided
2433 elements in the part.
2435 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2436 the number of nodes per nsided element. (as if connectivity
2437 length of an nsided element is one)
2439 3. In this routine, provide the streamed connectivities for each of the
2440 nsided elements.
2443 Simple example: 5 6
2444 +--------+
2445 3 nsided elements: /| \
2446 (1 4-sided / | \
2447 1 3-sided / | \
2448 1 7-sided) / | \ 7
2449 /3 |4 +
2450 +-----+ |
2451 | | |
2452 | | |8
2453 | | +
2454 | | /
2455 | | /
2456 | | /
2457 |1 |2 /9
2458 +-----+--------+
2460 1. In USERD_get_gold_part_build_info:
2461 number_of_elements[Z_NSIDED] = 3
2462 .
2463 /|\
2464 |
2465 2. In USERD_get_part_elements_by_type:
2466 length of conn_array will be: 3 x 1
2468 for element_type of Z_NSIDED:
2469 conn_array[0][0] = 4 (for the 4-sided element)
2470 conn_array[1][0] = 3 (for the 3-sided element)
2471 conn_array[2][0] = 7 (for the 7-sided element)
2473 Sum ===
2474 14 <---------+
2475 |
2476 3. In this routine: |
2477 length of nsided_conn_array will be: 14
2479 nsided_conn_array[0] = 1 (connectivity of 4-sided element)
2480 nsided_conn_array[1] = 2
2481 nsided_conn_array[2] = 4
2482 nsided_conn_array[3] = 3
2484 nsided_conn_array[4] = 3 (connectivity of 3-sided element)
2485 nsided_conn_array[5] = 4
2486 nsided_conn_array[6] = 5
2488 nsided_conn_array[7] = 2 (connectivity of 7-sided element)
2489 nsided_conn_array[8] = 9
2490 nsided_conn_array[9] = 8
2491 nsided_conn_array[10] = 7
2492 nsided_conn_array[11] = 6
2493 nsided_conn_array[12] = 5
2494 nsided_conn_array[13] = 4
2499 --------------------------------------------------------------------
2500 USERD_get_num_of_time_steps
2502 Description:
2503 -----------
2504 Gets the number of time steps of data available for desired timeset.
2506 Specification:
2507 -------------
2508 int USERD_get_num_of_time_steps( int timeset_number )
2510 Returns:
2511 -------
2512 Number of time steps in timeset (>0 if okay, <=0 if problems).
2514 Arguments:
2515 ---------
2516 (IN) timeset number = the timeset number
2518 For example: If USERD_get_number_of_timesets
2519 returns 2, the valid
2520 timeset_number's would be 1 and 2
2522 Notes:
2523 -----
2524 * This should be >= 1 1 indicates a static model
2525 >1 indicates a transient model
2527 * Num_time_steps[timeset_number] would be set here
2531 --------------------------------------------------------------------
2532 USERD_get_number_of_files_in_dataset
2534 Description:
2535 -----------
2536 Get the total number of files in the dataset. Used for the
2537 dataset query option within EnSight.
2539 Specification:
2540 -------------
2541 int USERD_get_number_of_files_in_dataset( void )
2543 Returns:
2544 -------
2545 The total number of files in the dataset.
2547 Arguments:
2548 ---------
2549 none
2551 Notes:
2552 -----
2553 * You can be as complete as you want about this. If you don't
2554 care about the dataset query option, return a value of 0
2555 If you only want certain files, you can just include them. But,
2556 you will need to supply the info in USERD_get_dataset_query_file_info
2557 for each file you include here.
2559 * Num_dataset_files would be set here
2562 --------------------------------------------------------------------
2563 USERD_get_number_of_material_sets -
2565 Description:
2566 -----------
2567 Get the number of material sets in the model
2569 Specification:
2570 -------------
2571 int USERD_get_number_of_material_sets( void )
2574 Returns:
2575 -------
2576 Num_material_sets = number of material sets
2577 (Zero would indicate that you have no materials
2578 to deal with in the model)
2580 or
2582 -1 if an error condition
2584 Arguments:
2585 ---------
2586 none
2588 Notes:
2589 -----
2590 * You may want to keep this as a global for use in other routines.
2592 ###############################################################
2593 NOTE: For EnSight 7.6, only one material set is supported
2594 within EnSight.
2595 Thus the only valid returns here are:
2596 0 (no materials)
2597 1 (for the one material set allowed)
2598 or -1 (if an error)
2600 If the casefile has more than this, this reader will
2601 read them, but EnSight will issue an error message and
2602 choke on them!
2603 ###############################################################
2605 ================================================================
2606 A very simple explanatory example, to use as a reference for the
2607 materials routines:
2609 Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
2610 Most of the model is material 1, but the top left corner is material 9 -
2611 basically as shown:
2614 *--------*--------*--------*
2615 | | / | |
2616 | Mat 9 / | |
2617 | | / | |
2618 | |/ | |
2619 | e7 / e8 | e9 |
2620 | /| | |
2621 | / | | |
2622 | / | | |
2623 *----/---*--------*--------*
2624 | / | | |
2625 | / | | |
2626 | / | Mat 1 |
2627 |/ | | |
2628 | e4 | e5 | e6 |
2629 | | | |
2630 | | | |
2631 | | | |
2632 *--------*--------*--------*
2633 | | | |
2634 | | | |
2635 | | | |
2636 | | | |
2637 | e1 | e2 | e3 |
2638 | | | |
2639 | | | |
2640 | | | |
2641 *--------*--------*--------*
2644 Thus, in this routine, set:
2645 Num_material_sets = 1
2647 In USERD_get_matf_set_info, set:
2648 mat_set_ids[0] = 1
2649 mat_set_name[0] = "Material Set 1" (or whatever name desired)
2651 In USERD_get_number_of_materials, input would be set_index = 0, and
2652 would need to set:
2653 Num_materials[0] = 2
2655 For simplicity, the ids and descriptions that would be returned in
2656 USERD_get_matf_var_info could be:
2657 mat_ids[0] = 1
2658 mat_ids[1] = 9
2659 mat_desc[0] = "mat 1" (or whatever desired)
2660 mat_desc[2] = "mat 9"
2662 The per element material ids list would need to be:
2664 material ids:
2665 -------------
2666 ids_list[0] = 1 (material id 1, for elem e1)
2667 ids_list[1] = 1 ( " e2)
2668 ids_list[2] = 1 ( " e3)
2669 ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
2670 ids_list[5] = 1 (material id 1, for elem e5)
2671 ids_list[5] = 1 ( " e6)
2672 ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
2673 ids_list[5] = -9 ( " e8)
2674 ids_list[5] = 1 (material id 1, for elem e9)
2676 Finally we need the mixed material ids list and the mixed materials values list,
2677 which would need to be:
2679 mixed-material ids:
2680 -------------------
2681 ==> 1 ids_list[0] = 2 (the -1 in the material variable points here,
2682 2 indicates that two materials are present)
2683 2 ids_list[1] = 1 (1st material is 1)
2684 3 ids_list[2] = 9 (2nd material is 9)
2685 4 ids_list[3] = -1 (negative of index into mixed-material val_list)
2686 ==> 5 ids_list[4] = 2 (the -5 in the material variable points here,
2687 2 indicates that two materials are present)
2688 6 ids_list[5] = 1 (1st material is 1)
2689 7 ids_list[6] = 9 (2nd material is 9)
2690 8 ids_list[7] = -3 (negative of index into mixed-material val_list)
2691 ==> 9 ids_list[8] = 2 etc.
2692 10 ids_list[9] = 1
2693 11 ids_list[10] = 9
2694 12 ids_list[11] = -5
2696 mixed-material values:
2697 ----------------------
2698 ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here,
2699 and this is the value for material 1)
2700 2 val_list[1] = 0.125 (the value for material 9)
2701 ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
2702 4 val_list[3] = 0.875
2703 ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
2704 6 val_list[5] = 0.125
2706 So, USERD_size_matf_data would need to return
2707 matf_size = 8, when called with set_id = 1
2708 part_id = 1
2709 wtyp = Z_QUA04
2710 mat_type = Z_MAT_INDEX
2712 matf_size = 12, when called with set_id = 1
2713 part_id = 1
2714 mat_type = Z_MIX_INDEX
2716 = 6, when called with set_id = 1
2717 part_id = 1
2718 mat_type = Z_MIX_VALUE
2720 And, USERD_load_matf_data would need to return:
2721 the int array ids_list as shown above when called with:
2722 set_id = 1
2723 part_id = 1
2724 wtyp = Z_QUA04
2725 mat_type = Z_MAT_INDEX (indicating id list).
2727 the int array ids_list as shown above when called with:
2728 set_id = 1
2729 part_id = 1
2730 mat_type = Z_MIX_INDEX (indicating id list).
2732 the float array val_list as shown above when called with:
2733 set_id = 1
2734 part_id = 1
2735 mat_type = Z_MIX_VALUE (indicating val list).
2738 -------------------------------------------------------------------------
2739 USERD_get_number_of_materials
2741 Description:
2742 -----------
2743 Gets the number of materials in the material set
2745 Specification:
2746 -------------
2747 int USERD_get_number_of_materials( int set_index )
2749 Returns:
2750 -------
2751 Num_materials[set_index] = Number of materials in the set
2752 0 indicates no materials information present
2753 -1 indicates an error
2754 Arguments:
2755 ---------
2756 (IN) set_index = the material set index (zero based)
2758 Notes:
2759 -----
2760 * See USERD_get_number_of_material_sets header for explanatory example
2761 * Will not be called if Num_material_sets is zero
2762 * You may want to keep this as a global for use in other routines.
2766 --------------------------------------------------------------------
2767 USERD_get_number_of_model_parts
2769 Description:
2770 -----------
2771 Gets the total number of unstructured and structured parts
2772 in the model, for which you can supply information.
2774 Specification:
2775 -------------
2776 int USERD_get_number_of_model_parts( void )
2778 Returns:
2779 -------
2780 Number of parts (>0 if okay, <=0 if problems).
2782 Arguments:
2783 ---------
2784 none
2786 Notes:
2787 -----
2788 * If going to have to read down through the parts in order to
2789 know how many, you may want to build a table of pointers to
2790 the various parts, so you can easily get to particular parts in
2791 later processes. If you can simply read the number of parts
2792 at the head of the file, then you would probably not build the
2793 table at this time.
2795 * This routine would set Numparts_available, which is equal to
2796 Num_unstructured_parts + Num_structured_blocks.
2800 --------------------------------------------------------------------
2801 USERD_get_number_of_timesets
2803 Description:
2804 -----------
2805 Gets the number of timesets used in the model.
2807 Specification:
2808 -------------
2809 int USERD_get_number_of_timesets( void )
2811 Returns:
2812 -------
2813 Number of timesets in the model
2815 Arguments:
2816 ---------
2817 none
2819 Notes:
2820 -----
2821 * Num_timesets would be set here
2823 * If you have a static model, both geometry and variables, you should
2824 return a value of zero.
2826 * If you have a transient model, then you should return one or more.
2828 For example:
2830 Geometry Variables No. of timesets
2831 --------- ------------------------------ ---------------
2832 static static 0
2833 static transient, all using same timeset 1
2835 transient transient, all using same timeset as geom 1
2837 static transient, using 3 different timesets 3
2839 transient transient, using 3 different timesets and
2840 none of them the same as the
2841 geometry timeset 4
2842 etc.
2844 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
2845 the timeset number to use
2846 for geometry in:
2847 USERD_get_geom_timeset_number
2849 Variables can use the same timeset as the geometry, or can use
2850 other timesets. More than one variable can use the same timeset.
2852 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
2853 variable 1 provided at these same five steps
2854 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
2856 This routine should return a value of 2, because only
2857 two different timesets are needed. Timeset 1 would be for the
2858 geometry and variable 1 (they both use it). Timeset 2 would
2859 be for variable 2, which needs its own in this case.
2865 --------------------------------------------------------------------
2866 USERD_get_number_of_variables
2868 Description:
2869 -----------
2870 Get the number of variables for which you will be providing info.
2872 Specification:
2873 -------------
2874 int USERD_get_number_of_variables( void )
2876 Returns:
2877 -------
2878 Number of variables (includes constant, scalar, vector and tensor types)
2879 (>=0 if okay, <0 if problem)
2881 Arguments:
2882 ---------
2883 none
2885 Notes:
2886 -----
2887 *****************************************************************
2888 * Variable numbers, by which references will be made, are implied
2889 here. If you say there are 3 variables, the variable numbers
2890 will be 1, 2, and 3.
2891 *****************************************************************
2893 * Num_variables would be set here
2897 --------------------------------------------------------------------
2898 USERD_get_part_coords
2900 Description:
2901 -----------
2902 Gets the coordinates for an unstructured part.
2904 Specification:
2905 -------------
2906 int USERD_get_part_coords(int part_number, float **coord_array)
2908 Returns:
2909 -------
2910 Z_OK if successful
2911 Z_ERR if not successful
2913 Arguments:
2914 ---------
2915 (IN) part_number = The part number
2916 (1-based index of part table, namely:
2918 1 ... Numparts_available.
2920 It is NOT the part_id that
2921 is loaded in USERD_get_gold_part_build_info)
2923 (OUT) coord_array = 2D float array which contains,
2924 x,y,z coordinates of each node
2925 in the part.
2927 (IMPORTANT: The second dimension of this aray is 1-based!!!)
2929 (Array will have been allocated
2930 3 by (number_of_nodes + 1) for the part
2931 long - see USERD_get_gold_part_build_info)
2934 ex) If number_of_nodes = 100
2935 as obtained in:
2936 USERD_get_gold_part_build_info
2938 Then the allocated dimensions of the
2939 pointer sent to this routine will be:
2940 coord_array[3][101]
2942 Ignore the coord_array[0][0]
2943 coord_array[1][0]
2944 coord_array[2][0] locations and start
2945 the node coordinates at:
2946 coord_array[0][1]
2947 coord_array[1][1]
2948 coord_array[2][1]
2950 coord_array[0][2]
2951 coord_array[1][2]
2952 coord_array[2][2]
2954 etc.
2956 Notes:
2957 -----
2958 * Not called unless Num_unstructured_parts is > 0
2960 * Will be based on Current_time_step
2963 --------------------------------------------------------------------
2964 USERD_get_part_element_ids_by_type
2966 Description:
2967 -----------
2968 Gets the ids for the elements of a particular type for an unstructured
2969 or structured part.
2971 Specification:
2972 -------------
2973 int USERD_get_part_element_ids_by_type(int part_number,
2974 int element_type,
2975 int *elemid_array)
2977 Returns:
2978 -------
2979 Z_OK if successful
2980 Z_ERR if not successful
2982 Arguments:
2983 ---------
2984 (IN) part_number = The part number
2985 (1-based index of part table, namely:
2987 1 ... Numparts_available.
2989 It is NOT the part_id that
2990 is loaded in USERD_get_gold_part_build_info)
2992 (IN) element_type = One of the following (See global_extern.h)
2993 Z_POINT node point element
2994 Z_BAR02 2 node bar
2995 Z_BAR03 3 node bar
2996 Z_TRI03 3 node triangle
2997 Z_TRI06 6 node triangle
2998 Z_QUA04 4 node quad
2999 Z_QUA08 8 node quad
3000 Z_TET04 4 node tetrahedron
3001 Z_TET10 10 node tetrahedron
3002 Z_PYR05 5 node pyramid
3003 Z_PYR13 13 node pyramid
3004 Z_PEN06 6 node pentahedron
3005 Z_PEN15 15 node pentahedron
3006 Z_HEX08 8 node hexahedron
3007 Z_HEX20 20 node hexahedron
3009 Z_G_POINT ghost node point element
3010 Z_G_BAR02 2 node ghost bar
3011 Z_G_BAR03 3 node ghost bar
3012 Z_G_TRI03 3 node ghost triangle
3013 Z_G_TRI06 6 node ghost triangle
3014 Z_G_QUA04 4 node ghost quad
3015 Z_G_QUA08 8 node ghost quad
3016 Z_G_TET04 4 node ghost tetrahedron
3017 Z_G_TET10 10 node ghost tetrahedron
3018 Z_G_PYR05 5 node ghost pyramid
3019 Z_G_PYR13 13 node ghost pyramid
3020 Z_G_PEN06 6 node ghost pentahedron
3021 Z_G_PEN15 15 node ghost pentahedron
3022 Z_G_HEX08 8 node ghost hexahedron
3023 Z_G_HEX20 20 node ghost hexahedron
3025 (OUT) elemid_array = 1D array containing id of each
3026 element of the type.
3028 (Array will have been allocated
3029 number_of_elements of the type long)
3031 ex) If number_of_elements[Z_TRI03] = 25
3032 number_of_elements[Z_QUA04] = 100
3033 number_of_elements[Z_HEX08] = 30
3034 as obtained in:
3035 USERD_get_gold_part_build_info
3037 Then the allocated dimensions available
3038 for this routine will be:
3039 conn_array[25] when called with Z_TRI03
3041 conn_array[100] when called with Z_QUA04
3043 conn_array[30] when called with Z_HEX08
3045 Notes:
3046 -----
3047 * Not called unless element label status is set to TRUE in
3048 USERD_get_element_label_status
3050 * Will be based on Current_time_step
3054 --------------------------------------------------------------------
3055 USERD_get_part_elements_by_type
3057 Description:
3058 -----------
3059 Gets the connectivities for the elements of a particular type in an
3060 unstructured part
3062 Specification:
3063 -------------
3064 int USERD_get_part_elements_by_type(int part_number,
3065 int element_type,
3066 int **conn_array)
3068 Returns:
3069 -------
3070 Z_OK if successful
3071 Z_ERR if not successful
3073 Arguments:
3074 ---------
3075 (IN) part_number = The part number
3076 (1-based index of part table, namely:
3078 1 ... Numparts_available.
3080 It is NOT the part_id that
3081 is loaded in USERD_get_gold_part_build_info)
3083 (IN) element_type = One of the following (See global_extern.h)
3084 Z_POINT node point element
3085 Z_BAR02 2 node bar
3086 Z_BAR03 3 node bar
3087 Z_TRI03 3 node triangle
3088 Z_TRI06 6 node triangle
3089 Z_QUA04 4 node quad
3090 Z_QUA08 8 node quad
3091 Z_TET04 4 node tetrahedron
3092 Z_TET10 10 node tetrahedron
3093 Z_PYR05 5 node pyramid
3094 Z_PYR13 13 node pyramid
3095 Z_PEN06 6 node pentahedron
3096 Z_PEN15 15 node pentahedron
3097 Z_HEX08 8 node hexahedron
3098 Z_HEX20 20 node hexahedron
3100 Z_G_POINT ghost node point element
3101 Z_G_BAR02 2 node ghost bar
3102 Z_G_BAR03 3 node ghost bar
3103 Z_G_TRI03 3 node ghost triangle
3104 Z_G_TRI06 6 node ghost triangle
3105 Z_G_QUA04 4 node ghost quad
3106 Z_G_QUA08 8 node ghost quad
3107 Z_G_TET04 4 node ghost tetrahedron
3108 Z_G_TET10 10 node ghost tetrahedron
3109 Z_G_PYR05 5 node ghost pyramid
3110 Z_G_PYR13 13 node ghost pyramid
3111 Z_G_PEN06 6 node ghost pentahedron
3112 Z_G_PEN15 15 node ghost pentahedron
3113 Z_G_HEX08 8 node ghost hexahedron
3114 Z_G_HEX20 20 node ghost hexahedron
3117 (OUT) conn_array = 2D array containing connectivity
3118 of each element of the type.
3120 (Array will have been allocated
3121 num_of_elements of the type by
3122 connectivity length of the type)
3124 ex) If number_of_elements[Z_TRI03] = 25
3125 number_of_elements[Z_QUA04] = 100
3126 number_of_elements[Z_HEX08] = 30
3127 as obtained in:
3128 USERD_get_gold_part_build_info
3130 Then the allocated dimensions available
3131 for this routine will be:
3132 conn_array[25][3] when called with Z_TRI03
3134 conn_array[100][4] when called with Z_QUA04
3136 conn_array[30][8] when called with Z_HEX08
3138 Notes:
3139 -----
3140 * Not called unless Num_unstructured_parts is > 0
3142 * Will be based on Current_time_step
3145 --------------------------------------------------------------------
3146 USERD_get_part_node_ids
3148 Description:
3149 -----------
3150 Gets the node ids of an unstructured or structured part.
3152 Specification:
3153 -------------
3154 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
3156 Returns:
3157 -------
3158 Z_OK if successful
3159 Z_ERR if not successful
3161 Arguments:
3162 ---------
3163 (IN) part_number = The part number
3164 (1-based index of part table, namely:
3166 1 ... Numparts_available.
3168 It is NOT the part_id that
3169 is loaded in USERD_get_gold_part_build_info)
3171 (OUT) nodeid_array = 1D array containing node ids of
3172 each node in the part.
3174 (IMPORTANT: This array is 1-based!!!)
3176 (Array will have been allocated
3177 (number_of_nodes + 1) for the part long
3178 see USERD_get_gold_part_build_info)
3180 ex) If number_of_nodes = 100
3181 as obtained in:
3182 USERD_get_gold_part_build_info
3184 Then the allocated dimensions of the
3185 pointer sent to this routine will be:
3186 nodeid_array[101]
3188 Ignore the nodeid_array[0] location and start
3189 the node ids at:
3190 nodeid_array[1]
3192 nodeid_array[2]
3194 etc.
3196 Notes:
3197 -----
3198 * Not called unless node label status is TRUE, as returned from
3199 USERD_get_node_label_status
3201 * Will be based on Current_time_step
3203 * The ids are purely labels, used when displaying or querying node ids.
3204 However, any node id < 0 will never be displayed
3207 --------------------------------------------------------------------
3208 USERD_get_reader_descrip
3210 Description:
3211 -----------
3212 Gets the description of the reader, so gui can give more info
3214 Specification:
3215 -------------
3216 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
3218 Returns:
3219 -------
3220 Z_OK if successful
3221 Z_ERR if not successful
3223 Arguments:
3224 ---------
3225 (OUT) descrip = the description of the reader (max length is MAXFILENP,
3226 which is 255)
3228 Notes:
3229 -----
3230 * OPTIONAL ROUTINE! You can have it or not.
3234 --------------------------------------------------------------------
3235 USERD_get_reader_version
3237 Description:
3238 -----------
3239 Gets the version number of the user defined reader
3241 Specification:
3242 -------------
3243 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
3245 Returns:
3246 -------
3247 Z_OK if successful
3248 Z_ERR if not successful (and will assume is version 1.0)
3250 Arguments:
3251 ---------
3252 (OUT) version_number = the version number of the reader
3253 (max length is Z_MAX_USERD_NAME, which
3254 is 20)
3256 Notes:
3257 -----
3258 * This needs to be "2.000" or greater. Otherwise EnSight will assume
3259 this reader is API 1.0
3261 * should set it to "2.010" for this version of the API
3266 --------------------------------------------------------------------
3267 USERD_get_sol_times
3269 Description:
3270 -----------
3271 Get the solution times associated with each time step for
3272 desired timeset.
3274 Specification:
3275 -------------
3276 int USERD_get_sol_times(int timeset_number,
3277 float *solution_times)
3279 Returns:
3280 -------
3281 Z_OK if successful
3282 Z_ERR if not successful
3284 Arguments:
3285 ---------
3286 (IN) timeset_number = the timeset number
3288 For example: If USERD_get_number_of_timesets
3289 returns 2, the valid
3290 timeset_number's would be 1 and 2
3292 (OUT) solution_times = 1D array of solution times per time step
3294 (Array will have been allocated
3295 Num_time_steps[timeset_number] long)
3297 Notes:
3298 -----
3299 * The solution times must be non-negative and increasing.
3303 --------------------------------------------------------------------
3304 USERD_get_timeset_description -
3306 Description:
3307 -----------
3308 Get the description to associate with the desired timeset.
3310 Specification:
3311 -------------
3312 int USERD_get_timeset_description(int timeset_number,
3313 char timeset_description[Z_BUFL])
3315 Returns:
3316 -------
3317 Z_OK if successful
3318 Z_ERR if not successful
3320 Arguments:
3321 ---------
3322 (IN) timeset_number = the timeset number
3324 For example: If USERD_get_number_of_timesets
3325 returns 2, the valid
3326 timeset_number's would be 1 and 2
3328 (OUT) timeset_description = timeset description string
3331 Notes:
3332 -----
3333 * A string of NULLs is valid for timeset_description
3338 --------------------------------------------------------------------
3339 USERD_get_var_by_component
3341 Description:
3342 -----------
3343 Gets the values of a variable component. Both unstructured and structured
3344 parts use this routine.
3346 if Z_PER_NODE:
3347 Get the component value at each node for a given variable in the part.
3349 or if Z_PER_ELEM:
3350 Get the component value at each element of a specific part and type
3351 for a given variable.
3353 Specification:
3354 -------------
3355 int USERD_get_var_by_component(int which_variable,
3356 int which_part,
3357 int var_type,
3358 int which_type,
3359 int imag_data,
3360 int component,
3361 float *var_array)
3363 Returns:
3364 -------
3365 Z_OK if successful
3366 Z_ERR if not successful
3368 or: Z_UNDEF, in which case you need not load any values into var_array
3371 Arguments:
3372 ---------
3373 (IN) which_variable = The variable number
3375 (IN) which_part Since EnSight Version 7.4
3376 -------------------------
3377 = The part number
3379 (1-based index of part table, namely:
3381 1 ... Numparts_available.
3383 It is NOT the part_id that
3384 is loaded in USERD_get_gold_part_build_info)
3386 Prior to EnSight Version 7.4
3387 ----------------------------
3388 = The part id This is the part_id label loaded
3389 in USERD_get_gold_part_build_info.
3390 It is NOT the part table index.
3392 (IN) var_type = Z_SCALAR
3393 Z_VECTOR
3394 Z_TENSOR (symmetric tensor)
3395 Z_TENSOR9 (asymmetric tensor)
3397 (IN) which_type
3399 if Z_PER_NODE: Not used
3401 if Z_PER_ELEM: = The element type
3402 Z_POINT node point element
3403 Z_BAR02 2 node bar
3404 Z_BAR03 3 node bar
3405 Z_TRI03 3 node triangle
3406 Z_TRI06 6 node triangle
3407 Z_QUA04 4 node quad
3408 Z_QUA08 8 node quad
3409 Z_TET04 4 node tetrahedron
3410 Z_TET10 10 node tetrahedron
3411 Z_PYR05 5 node pyramid
3412 Z_PYR13 13 node pyramid
3413 Z_PEN06 6 node pentahedron
3414 Z_PEN15 15 node pentahedron
3415 Z_HEX08 8 node hexahedron
3416 Z_HEX20 20 node hexahedron
3418 Z_G_POINT ghost node point element
3419 Z_G_BAR02 2 node ghost bar
3420 Z_G_BAR03 3 node ghost bar
3421 Z_G_TRI03 3 node ghost triangle
3422 Z_G_TRI06 6 node ghost triangle
3423 Z_G_QUA04 4 node ghost quad
3424 Z_G_QUA08 8 node ghost quad
3425 Z_G_TET04 4 node ghost tetrahedron
3426 Z_G_TET10 10 node ghost tetrahedron
3427 Z_G_PYR05 5 node ghost pyramid
3428 Z_G_PYR13 13 node ghost pyramid
3429 Z_G_PEN06 6 node ghost pentahedron
3430 Z_G_PEN15 15 node ghost pentahedron
3431 Z_G_HEX08 8 node ghost hexahedron
3432 Z_G_HEX20 20 node ghost hexahedron
3434 (IN) imag_data = TRUE if imag component
3435 FALSE if real component
3437 (IN) component = The component: (0 if Z_SCALAR)
3438 (0 - 2 if Z_VECTOR)
3439 (0 - 5 if Z_TENSOR)
3440 (0 - 8 if Z_TENSOR9)
3442 * 6 Symmetric Indicies, 0:5 *
3443 * ---------------------------- *
3444 * | 11 12 13 | | 0 3 4 | *
3445 * | | | | *
3446 * T = | 22 23 | = | 1 5 | *
3447 * | | | | *
3448 * | 33 | | 2 | *
3451 * 9 General Indicies, 0:8 *
3452 * ---------------------------- *
3453 * | 11 12 13 | | 0 3 4 | *
3454 * | | | | *
3455 * T = | 21 22 23 | = | 6 1 5 | *
3456 * | | | | *
3457 * | 31 32 33 | | 7 8 2 | *
3459 (OUT) var_array
3461 -----------------------------------------------------------------------
3462 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
3463 -----------------------------------------------------------------------
3465 if Z_PER_NODE: = 1D array containing variable component value
3466 for each node.
3468 (Array will have been allocated
3469 (number_of_nodes + 1) long)
3471 Info stored in this fashion:
3472 var_array[0] = not used
3473 var_array[1] = var component for node 1 of part
3474 var_array[2] = var_component for node 2 of part
3475 var_array[3] = var_component for node 3 of part
3476 etc.
3478 if Z_PER_ELEM: = 1D array containing variable component
3479 value for each element of a particular
3480 part and type.
3482 (Array will have been allocated
3483 (number_of_elements[which_part][which_type] + 1)
3484 long. See USERD_get_gold_part_build_info)
3486 Info stored in this fashion:
3487 var_array[1] = var component for elem 1 (of part and type)
3488 var_array[2] = var component for elem 2 (of part and type)
3489 var_array[3] = var component for elem 3 (of part and type)
3490 etc.
3492 Notes:
3493 -----
3494 * Not called unless Num_variables is > 0
3496 * The per_node or per_elem classification must be obtainable from the
3497 variable number (a var_classify array needs to be retained)
3499 * Will be based on Current_time_step
3501 * If the variable is not defined for this part, simply return with a
3502 value of Z_UNDEF. EnSight will treat the variable as undefined for
3503 this part.
3506 --------------------------------------------------------------------
3507 USERD_get_var_value_at_specific
3509 Description:
3510 -----------
3511 if Z_PER_NODE:
3512 Get the value of a particular variable at a particular node in a
3513 particular part at a particular time.
3515 or if Z_PER_ELEM:
3516 Get the value of a particular variable at a particular element of
3517 a particular type in a particular part at a particular time.
3520 Specification:
3521 -------------
3522 int USERD_get_var_value_at_specific(int which_var,
3523 int which_node_or_elem,
3524 int which_part,
3525 int which_elem_type,
3526 int time_step,
3527 float values[3],
3528 int imag_data)
3530 Returns:
3531 -------
3532 Z_OK if successful
3533 Z_ERR if not successful
3535 Arguments:
3536 ---------
3537 (IN) which_var = The variable number
3539 (IN) which_node_or_elem
3541 If Z_PER_NODE:
3542 = The node number. This is not the id, but is
3543 the index of the global node
3544 list (1 based), or the block's
3545 node list (1 based).
3547 Thus, coord_array[1]
3548 coord_array[2]
3549 coord_array[3]
3550 . |
3551 . |which_node_or_elem index
3552 . ----
3555 If Z_PER_ELEM:
3556 = The element number. This is not the id, but is
3557 the element number index
3558 of the number_of_element array
3559 (see USERD_get_gold_part_build_info),
3560 or the block's element list (1 based).
3562 Thus, for which_part:
3563 conn_array[which_elem_type][0]
3564 conn_array[which_elem_type][1]
3565 conn_array[which_elem_type][2]
3566 . |
3567 . which_node_or_elem index
3568 . ----
3571 (IN) which_part Since EnSight Version 7.4
3572 -------------------------
3573 = The part number
3575 (1-based index of part table, namely:
3577 1 ... Numparts_available.
3579 It is NOT the part_id that
3580 is loaded in USERD_get_gold_part_build_info)
3582 Prior to EnSight Version 7.4
3583 ----------------------------
3584 = The part id This is the part_id label loaded
3585 in USERD_get_gold_part_build_info.
3586 It is NOT the part table index.
3589 (IN) which_elem_type
3591 If Z_PER_NODE, or block part:
3592 = Not used
3594 If Z_PER_ELEM:
3595 = The element type. This is the element type index
3596 of the number_of_element array
3597 (see USERD_get_gold_part_build_info)
3599 (IN) time_step = The time step
3601 (IN) imag_data = TRUE if want imaginary value.
3602 FALSE if want real value.
3604 (OUT) values = scalar or vector component value(s)
3605 values[0] = scalar or vector[0]
3606 values[1] = vector[1]
3607 values[2] = vector[2]
3610 Notes:
3611 -----
3612 * This routine is used in node querys over time (or element querys over
3613 time for Z_PER_ELEM variables). If these operations are not critical
3614 to you, this can be a dummy routine.
3616 * The per_node or per_elem classification must be obtainable from the
3617 variable number (a var_classify array needs to be retained)
3619 * The time step given is for the proper variable timeset.
3622 ----------------------------------------------------------------------
3623 USERD_load_matf_data
3625 Description:
3626 -----------
3627 Get the material id list, mixed-material id list, or
3628 mixed-material values list for the given material set and part (and
3629 element type if material id list)
3631 Specification:
3632 -------------
3633 int USERD_load_matf_data( int set_index,
3634 int part_id,
3635 int wtyp,
3636 int mat_type,
3637 int *ids_list,
3638 float *val_list)
3641 Returns:
3642 -------
3643 Z_OK if successful
3644 Z_ERR if not successful
3646 Arguments:
3647 ---------
3648 (IN) set_index = the material set index (zero based)
3650 (IN) part_id = the part number desired
3652 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3654 Z_POINT node point element
3655 Z_BAR02 2 node bar
3656 Z_BAR03 3 node bar
3657 Z_TRI03 3 node triangle
3658 Z_TRI06 6 node triangle
3659 Z_QUA04 4 node quad
3660 Z_QUA08 8 node quad
3661 Z_TET04 4 node tetrahedron
3662 Z_TET10 10 node tetrahedron
3663 Z_PYR05 5 node pyramid
3664 Z_PYR13 13 node pyramid
3665 Z_PEN06 6 node pentahedron
3666 Z_PEN15 15 node pentahedron
3667 Z_HEX08 8 node hexahedron
3668 Z_HEX20 20 node hexahedron
3669 Z_NSIDED nsided polygon
3670 Z_NFACED nfaced polyhedron
3672 Z_G_POINT ghost node point element
3673 Z_G_BAR02 2 node ghost bar
3674 Z_G_BAR03 3 node ghost bar
3675 Z_G_TRI03 3 node ghost triangle
3676 Z_G_TRI06 6 node ghost triangle
3677 Z_G_QUA04 4 node ghost quad
3678 Z_G_QUA08 8 node ghost quad
3679 Z_G_TET04 4 node ghost tetrahedron
3680 Z_G_TET10 10 node ghost tetrahedron
3681 Z_G_PYR05 5 node ghost pyramid
3682 Z_G_PYR13 13 node ghost pyramid
3683 Z_G_PEN06 6 node ghost pentahedron
3684 Z_G_PEN15 15 node ghost pentahedron
3685 Z_G_HEX08 8 node ghost hexahedron
3686 Z_G_HEX20 20 node ghost hexahedron
3687 Z_G_NSIDED ghost nsided polygon
3688 Z_G_NFACED ghost nfaced polyhedron
3690 (IN) mat_type = Z_MAT_INDEX for material ids list
3691 Z_MIX_INDEX for mixed-material ids list
3692 Z_MIX_VALUE for mixed-material values list
3694 (OUT) ids_list = If mat_type is Z_MAT_INDEX:
3695 ---------------------------
3696 1D material id list
3697 (Int array will have been allocated
3698 the appropriate size, as returned in
3699 USERD_size_matf_data for mat_type Z_MAT_INDEX)
3701 If mat_type is Z_MIX_INDEX:
3702 ---------------------------
3703 1D mixed-material id list
3704 (Int array will have been allocated
3705 the appropriate size, as returned in
3706 USERD_size_matf_data for mat_type Z_MIX_INDEX)
3708 (OUT) val_list = 1D mixed-materials values list
3709 (only used if mat_type is Z_MIX_VALUE)
3711 (Float array will have been allocated
3712 the appropriate size, as returned in
3713 USERD_size_matf_data for mat_type Z_MIX_VALUE)
3715 Notes:
3716 -----
3717 * See USERD_get_number_of_material_sets header for explanatory example
3718 * Will not be called if Num_material_sets is zero,
3719 or Num_materials[set_index] is zero,
3720 or the appropriate size from USERD_size_matf_data is zero
3724 --------------------------------------------------------------------
3725 USERD_set_filenames
3727 Description:
3728 -----------
3729 Receives the geometry and result filenames entered in the data
3730 dialog. The user written code will have to store and use these
3731 as needed. The user written code must manage its own files!!
3733 Specification:
3734 -------------
3735 int USERD_set_filenames(char filename_1[],
3736 char filename_2[],
3737 char the_path[],
3738 int swapbytes)
3740 Returns:
3741 -------
3742 Z_OK if successful
3743 Z_ERR if not successful
3745 Arguments:
3746 ---------
3747 (IN) filename_1 = the filename entered into the geometry
3748 field of the data dialog.
3750 (IN) param_2 = The usage of this string depends on
3751 'two_fields' in USERD_get_name_of_reader.
3753 If two_fields is FALSE then it's empty.
3755 If two_fields is TRUE, this is the
3756 manditory results file entered
3757 into the result field of the data dialog.
3759 If two_fields is -1, then this contains
3760 optional text (filenames, modifiers, etc.)
3761 that can be parsed and used to modify
3762 reader
3764 (IN) the_path = the path info from the data dialog.
3765 Note: filename_1 and filename_2 have already
3766 had the path prepended to them. This
3767 is provided in case it is needed for
3768 filenames contained in one of the files
3770 (IN) swapbytes = TRUE if should swap bytes when reading data.
3771 = FALSE normally.
3773 Notes:
3774 -----
3775 * Since you must manage everything from the input that is entered in
3776 these data dialog fields, this is an important routine!
3778 * It may be that you will need to have an executive type file that contains
3779 info and other filenames within it, like EnSight6's case file.
3782 --------------------------------------------------------------------
3783 USERD_set_server_number
3785 Description:
3786 -----------
3787 Receives the server number of how many total servers.
3789 Specification:
3790 -------------
3791 int USERD_set_server_number(int cur_serv,
3792 int tot_servs)
3794 Returns:
3795 -------
3796 nothing
3798 Arguments:
3799 ---------
3800 (IN) cur_serv = the current server.
3802 (IN) tot_servs = the total number of servers.
3804 Notes:
3805 -----
3806 * Only useful if your user defined reader is being used with EnSight's
3807 Server-of-Server capability. And even then, it may or may not be
3808 something that you can take advantage of. If your data is already
3809 partitioned in some manner, such that you can access the proper
3810 portions using this information.
3812 For all non-SOS uses, this will simply be 1 of 1
3816 --------------------------------------------------------------------
3817 USERD_set_time_set_and_step
3819 Description:
3820 -----------
3821 Set the current time step in the desired timeset. All functions that
3822 need time, and that do not explicitly pass it in, will use the timeset
3823 and step set by this routine, if needed.
3825 Specification:
3826 -------------
3827 void USERD_set_time_set_and_step(int timeset_number,
3828 int time_step)
3830 Returns:
3831 -------
3832 nothing
3834 Arguments:
3835 ---------
3836 (IN) timeset_number = the timeset number (1 based).
3838 For example: If USERD_get_number_of_timesets
3839 returns 2, the valid timeset_number's
3840 would be 1 and 2.
3842 (IN) time_step = The current time step to set
3844 Notes:
3845 -----
3846 * Current_time_step and Current_timeset would be set here
3849 --------------------------------------------------------------------
3850 USERD_size_matf_data
3852 Description:
3853 -----------
3854 Get the length of the material id list, mixed-material id list, or
3855 mixed-material values list for the given material set and part (and
3856 element type if material id list)
3858 Specification:
3859 -------------
3860 int USERD_size_matf_data( int set_index,
3861 int part_id,
3862 int wtyp,
3863 int mat_type,
3864 int *matf_size)
3867 Returns:
3868 -------
3869 Z_OK if successful
3870 Z_ERR if not successful
3872 Arguments:
3873 ---------
3874 (IN) set_index = the material set index (zero based)
3876 (IN) part_id = the part number desired
3878 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3880 Z_POINT node point element
3881 Z_BAR02 2 node bar
3882 Z_BAR03 3 node bar
3883 Z_TRI03 3 node triangle
3884 Z_TRI06 6 node triangle
3885 Z_QUA04 4 node quad
3886 Z_QUA08 8 node quad
3887 Z_TET04 4 node tetrahedron
3888 Z_TET10 10 node tetrahedron
3889 Z_PYR05 5 node pyramid
3890 Z_PYR13 13 node pyramid
3891 Z_PEN06 6 node pentahedron
3892 Z_PEN15 15 node pentahedron
3893 Z_HEX08 8 node hexahedron
3894 Z_HEX20 20 node hexahedron
3895 Z_NSIDED nsided polygon
3896 Z_NFACED nfaced polyhedron
3898 Z_G_POINT ghost node point element
3899 Z_G_BAR02 2 node ghost bar
3900 Z_G_BAR03 3 node ghost bar
3901 Z_G_TRI03 3 node ghost triangle
3902 Z_G_TRI06 6 node ghost triangle
3903 Z_G_QUA04 4 node ghost quad
3904 Z_G_QUA08 8 node ghost quad
3905 Z_G_TET04 4 node ghost tetrahedron
3906 Z_G_TET10 10 node ghost tetrahedron
3907 Z_G_PYR05 5 node ghost pyramid
3908 Z_G_PYR13 13 node ghost pyramid
3909 Z_G_PEN06 6 node ghost pentahedron
3910 Z_G_PEN15 15 node ghost pentahedron
3911 Z_G_HEX08 8 node ghost hexahedron
3912 Z_G_HEX20 20 node ghost hexahedron
3913 Z_G_NSIDED ghost nsided polygon
3914 Z_G_NFACED ghost nfaced polyhedron
3916 (IN) mat_type = Z_MAT_INDEX for material ids list
3917 Z_MIX_INDEX for mixed-material ids list
3918 Z_MIX_VALUE for mixed-material values list
3920 (OUT) matf_size = the length of the material id list, or
3921 mixed-material id list, or
3922 mixed-material values list
3923 for the given material set and part number
3924 (and element type if Z_MAT_INDEX)
3926 Notes:
3927 -----
3928 * See USERD_get_number_of_material_sets header for explanatory example
3929 * Will not be called if Num_material_sets is zero, or
3930 Num_materials[set_index] is zero
3935 --------------------------------------------------------------------
3936 USERD_stop_part_building
3938 Description:
3939 -----------
3940 This routine called when the part building dialog is closed. It is
3941 provided in case you desire to release memory, etc. that was only needed
3942 during the part building process.
3944 Specification:
3945 -------------
3946 void USERD_stop_part_building( void )
3948 Returns:
3949 -------
3950 nothing
3952 Arguments:
3953 ---------
3954 none
3956 Notes:
3957 -----
3959 --------------------------------------------------------------------
3960 USERD_rigidbody_existence
3962 Description:
3963 -----------
3964 Gets the existence of rigid body values or not in the model
3966 Specification:
3967 -------------
3968 int USERD_rigidbody_existence( void )
3970 Returns:
3971 -------
3972 Z_OK if rigid body values exist for the model
3973 Z_UNDEF if no rigid body values exist
3974 Z_ERR if an error
3976 Arguments:
3977 ---------
3978 none
3980 Notes:
3981 -----
3982 * This will be based on Current_time_step
3985 --------------------------------------------------------------------
3986 USERD_rigidbody_values
3988 Description:
3989 -----------
3990 Gets the rigid body values for each part
3992 Specification:
3993 -------------
3994 int USERD_rigidbody_values(int part_number,
3995 float values[14])
3997 Returns:
3998 -------
3999 Z_OK if rigid body values exist for the model
4000 Z_UNDEF if no rigid body values exist
4001 Z_ERR if an error
4003 Arguments:
4004 ---------
4005 (IN) part_number = The part number
4007 (1-based index of part table, namely:
4009 1 ... Numparts_available.
4011 It is NOT the part_id that
4012 is loaded in USERD_get_gold_part_build_info)
4014 (OUT) values values[0] = IX (x location)
4015 values[1] = IY (y location)
4016 values[2] = IZ (z location)
4017 values[3] = E0 (e0 euler value)
4018 values[4] = E1 (e1 euler value)
4019 values[5] = E2 (e2 euler value)
4020 values[6] = E3 (e3 euler value)
4022 The next 3 are for an optional cg offset. If none is
4023 needed or desired (namely the first 7 values above
4024 contain all that is needed), then these should be
4025 set to 0.0
4027 values[7] = xoff (initial cg x offset)
4028 values[8] = yoff (initial cg y offset)
4029 values[9] = z0ff (initial cg z offset)
4031 The next 4 values are for and optional initial yaw, pitch, roll
4032 operation. This is useful to get parts from one
4033 standard layout to a different standard layout.
4034 (example, flex body parts computed in an axis system
4035 different than that of rigid body parts manipulation)
4036 If not needed or desired, set these to 0.0
4038 values[10] = rot_order (order the roations are applied
4039 0.0 = no rotations
4040 1.0 = xyz order
4041 2.0 = xzy order
4042 3.0 = yxz order
4043 4.0 = yzx order
4044 5.0 = zxy order
4045 6.0 = zyx order)
4046 values[11] = xrot (initial x rotation - degrees)
4047 values[12] = yrot (initial y rotation - degrees)
4048 values[13] = zrot (initial z rotation - degrees)
4050 Notes:
4051 -----
4052 * This will be based on Current_time_step
4053 * It will not be called unless USERD_rigidbody_existence indicates
4054 that there are some values in the model by returning Z_OK.
4055 * Order that transformations will be applied is:
4056 1. The yaw,pitch,roll rotations, if present (values[11] through values[13]
4057 in the order specified in rot_order, values[10])
4058 2. The cg offsets, if present (values[7] through values[9])
4059 3. The euler parameter rotations (values[3] through values[6])
4060 4. The translations (values[0] through values[2])
4062 --------------------------------------------------------------------
4063 USERD_set_right_side
4065 Description:
4066 -----------
4067 Informs the reader that the time currently set is the right side of a time
4068 span used for variable interpolation between time steps
4070 Specification:
4071 -------------
4072 void USERD_set_right_side( void )
4074 Returns:
4075 -------
4077 Arguments:
4078 ---------
4079 none
4081 Notes:
4082 -----
4083 * Applies to Current_time_step
4089 ------------------------------------------------------------------
4090 ENHANCED GUI ROUTINES
4092 --------------------------------------------------------------------
4093 USERD_get_extra_gui_numbers
4095 Description:
4096 -----------
4097 The Enhanced GUI routines are added to allow
4098 the user to customize a portion of the Data
4099 Reader dialog to pass in options to their
4100 user defined reader.
4102 Specification:
4103 -------------
4104 void USERD__get_extra_gui_numbers(int *num_Toggles,
4105 int *num_pulldowns,
4106 int *num_fields)
4108 Returns:
4109 -------
4111 Arguments:
4112 ---------
4113 (OUT) num_Toggles = number of toggles that will be provided
4115 num_pulldowns = number of pulldowns that will be provided
4117 num_fields = number of fields that will be provided
4119 Notes:
4120 -----
4121 There are three routines that work together:
4122 USERD_get_extra_gui_numbers
4123 USERD_get_extra_gui_defaults
4124 USERD_set_extra_gui_data
4126 The existence of these routine indicates that
4127 you wish to add customize entries to the
4128 Data Reader dialog.
4130 If you don't want the extra GUI features,
4131 simply delete these routines, or change their
4132 names to something such as
4133 USERD_DISABLED_get_extra_gui_defaults
4135 The presence of these routines
4136 will ensure that EnSight will call them and
4137 use their data to modify the extraction parameters set
4138 with some or all of the following:
4139 toggles, pulldown menu and fields.
4141 The user can then interact with the enhanced
4142 GUI and then send their choices to
4143 USERD_set_extra_gui_data
4145 Therefore if USERD_get_extra_gui_numbers
4146 exists then the other two must exist.
4148 If none exist, then the GUI will be unchanged.
4150 Toggle data will return an integer
4151 TRUE if checked
4152 FALSE if unchecked
4154 Pulldown menu will return an integer representing
4155 the menu item selected
4157 Field will return a string Z_LEN_GUI_FIELD_STR long.
4159 If all the enhanced GUI features are enabled it
4160 might look something like this
4162 ===================================================
4163 [] Title 1 [X] Title 3
4164 [X]Title 2 [X] Title 4
4166 Pulldown Menu ->
4167 Menu Choice 1
4168 Menu Choice 2
4169 Menu Choice 3
4171 Data Field Title 1 ____________________________
4173 Data Field Title 2 ____________________________
4174 =====================================================
4176 This routine defines the numbers of toggles, pulldowns & fields
4178 The following are defined in the global_extern.h
4179 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4180 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4181 Z_LEN_GUI_FIELD_STR max length of field string
4182 Z_LEN_GUI_TITLE_STR max length of title string
4184 The library is loaded, this routine is
4185 called, then the library is unloaded.
4187 Do not define globals in this routine
4188 as when the library is unloaded, you'll
4189 lose them.
4192 --------------------------------------------------------------------
4193 USERD_get_extra_gui_defaults
4195 Description:
4196 -----------
4197 This routine defines the Titles, status,
4198 List choices, strings, etc that are fed
4199 up to the GUI.
4201 Specification:
4202 -------------
4203 int USERD_get_extra_gui_defaults(char **toggle_Title,
4204 int *toggle_default_status,
4205 char **pulldown_Title,
4206 int *pulldown_number_in_list,
4207 int *pulldown_default_selection,
4208 char ***pulldown_item_strings,
4209 char **field_Title,
4210 char **field_user_string)
4212 Returns:
4213 -------
4214 Z_OK if successful
4215 Z_ERR if not successful
4217 Arguments:
4218 ---------
4219 (OUT) toggle_Title = title for each toggle
4220 array dimension is [num_toggles] by
4221 [Z_LEN_GUI_TITLE_STR] long
4223 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4224 array dimension is [num_toggles] long
4226 pulldown_Title = title for each pulldown
4227 array dimension is [num_pulldowns] by
4228 [Z_LEN_GUI_TITLE_STR] long
4230 pulldown_number_in_list = number of items in each pulldown
4231 array dimension is [num_pulldowns] long
4233 pulldown_default_selection = pulldown item selection for each pulldown
4234 array dimension is [num_pulldowns] long
4236 pulldown_item_strings = pulldown item strings
4237 array is [num_pulldowns] by
4238 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4239 [Z_LEN_GUI_PULL_STR] long
4241 field_Title = title for each field
4242 array dimension is [num_fields] by
4243 [Z_LEN_GUI_TITLE_STR] long
4245 field_user_string = content of the field
4246 array dimension is [num_fields] by
4247 [Z_LEN_GUI_TITLE_STR] long
4251 Notes:
4252 -----
4253 * The library is loaded, this routine is called, then the library is unloaded.
4255 * Do not define globals in this routine as when the library is unloaded, you'll
4256 lose them.
4260 --------------------------------------------------------------------
4261 USERD_set_extra_gui_data
4263 Description:
4264 -----------
4265 This routine sets the new values for the toggles, pulldowns, and fields.
4267 Specification:
4268 -------------
4269 void USERD_set_extra_gui_data(
4270 int *toggle, /* [num_toggle] */
4271 int *pulldown, /* [num_pulldown] */
4272 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4274 Returns:
4275 -------
4277 Arguments:
4278 ---------
4279 (IN) toggle = setting for each toggle. TRUE or FALSE
4280 array dimension is [num_toggles] long
4282 pulldown = item chosen in each pulldown. (0 based)
4283 array dimension is [num_pulldowns] long
4285 field_text = content of the field
4286 array dimension is [num_fields] by
4287 [Z_LEN_GUI_TITLE_STR] long
4290 Notes:
4291 -----
4292 * This routine is called when the library is permanently
4293 loaded to the EnSight session, so define your globals
4294 in this and later routines.
4296 * It's up to you to change your reader behavior according to
4297 user entries!
4301 --------------------------------------------------------------------
4302 USERD_get_var_extract_gui_numbers
4304 Description:
4305 -----------
4306 The Var_Extract_GUI routines are added to allow
4307 the user to customize a extraction parameters
4308 for variables "after" the file has been read.
4309 These things can be modified and the variables will
4310 be update/refreshed according to the new parameters set
4312 Specification:
4313 -------------
4314 void USERD_get_var_extract_gui_numbers(int *num_Toggles,
4315 int *num_pulldowns,
4316 int *num_fields)
4319 Returns:
4320 -------
4322 Arguments:
4323 ---------
4324 (OUT) num_Toggles = number of toggles that will be provided
4326 num_pulldowns = number of pulldowns that will be provided
4328 num_fields = number of fields that will be provided
4330 Notes:
4331 -----
4332 There are three routines that work together:
4333 USERD_get_var_extract_gui_numbers
4334 USERD_get_var_extract_gui_defaults (this one)
4335 USERD_set_var_extract_gui_data
4337 The existence of these routine indicates that
4338 you wish to have the Var Extract Parameters dialog.
4340 If you don't want the extra GUI features,
4341 simply delete these routines, or change their
4342 names to something such as
4343 USERD_DISABLED_get_var_extract_gui_defaults
4345 The presence of these routines
4346 will ensure that EnSight will call them and
4347 use their data to modify the extraction parameters set
4348 with some or all of the following:
4349 toggles, pulldown menu and fields.
4351 The user can then interact with the enhanced
4352 GUI and then send their choices to
4353 USERD_set_extra_gui_data
4355 Therefore if USERD_get_var_extract_gui_numbers
4356 exists then the other two must exist.
4358 If none exist, then the GUI will be unchanged.
4360 Toggle data will return an integer
4361 TRUE if checked
4362 FALSE if unchecked
4364 Pulldown menu will return an integer representing
4365 the menu item selected
4367 Field will return a string Z_LEN_GUI_FIELD_STR long.
4369 If all the enhanced GUI features are enabled it
4370 might look something like this
4372 ===================================================
4373 [] Title 1 [X] Title 3
4374 [X]Title 2 [X] Title 4
4376 Pulldown Menu ->
4377 Menu Choice 1
4378 Menu Choice 2
4379 Menu Choice 3
4381 Data Field Title 1 ____________________________
4383 Data Field Title 2 ____________________________
4384 =====================================================
4386 This routine defines the numbers of toggles, pulldowns & fields
4388 The following are defined in the global_extern.h
4389 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4390 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4391 Z_LEN_GUI_FIELD_STR max length of field string
4392 Z_LEN_GUI_TITLE_STR max length of title string
4394 The library is loaded, this routine is
4395 called, then the library is unloaded.
4397 Do not define globals in this routine
4398 as when the library is unloaded, you'll
4399 lose them.
4402 --------------------------------------------------------------------
4403 USERD_get_var_extract_gui_defaults
4405 Description:
4406 -----------
4407 This routine defines the Titles, status,
4408 List choices, strings, etc that are fed
4409 up to the GUI.
4411 Specification:
4412 -------------
4413 int USERD_get_var_extract_gui_defaults(char **toggle_Title,
4414 int *toggle_default_status,
4415 char **pulldown_Title,
4416 int *pulldown_number_in_list,
4417 int *pulldown_default_selection,
4418 char ***pulldown_item_strings,
4419 char **field_Title,
4420 char **field_user_string)
4422 Returns:
4423 -------
4424 Z_OK if successful
4425 Z_ERR if not successful
4427 Arguments:
4428 ---------
4429 (OUT) toggle_Title = title for each toggle
4430 array dimension is [num_toggles] by
4431 [Z_LEN_GUI_TITLE_STR] long
4433 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4434 array dimension is [num_toggles] long
4436 pulldown_Title = title for each pulldown
4437 array dimension is [num_pulldowns] by
4438 [Z_LEN_GUI_TITLE_STR] long
4440 pulldown_number_in_list = number of items in each pulldown
4441 array dimension is [num_pulldowns] long
4443 pulldown_default_selection = pulldown item selection for each pulldown
4444 array dimension is [num_pulldowns] long
4446 pulldown_item_strings = pulldown item strings
4447 array is [num_pulldowns] by
4448 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4449 [Z_LEN_GUI_PULL_STR] long
4451 field_Title = title for each field
4452 array dimension is [num_fields] by
4453 [Z_LEN_GUI_TITLE_STR] long
4455 field_user_string = content of the field
4456 array dimension is [num_fields] by
4457 [Z_LEN_GUI_TITLE_STR] long
4461 Notes:
4462 -----
4463 * The library is loaded, this routine is called, then the library is unloaded.
4465 * Do not define globals in this routine as when the library is unloaded, you'll
4466 lose them.
4470 --------------------------------------------------------------------
4471 USERD_set_var_extract_gui_data
4473 Description:
4474 -----------
4475 This routine sets the new values for the toggles, pulldowns, and fields.
4477 Specification:
4478 -------------
4479 void USERD_set_var_extract_gui_data(
4480 int *toggle, /* [num_toggle] */
4481 int *pulldown, /* [num_pulldown] */
4482 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4484 Returns:
4485 -------
4487 Arguments:
4488 ---------
4489 (IN) toggle = setting for each toggle. TRUE or FALSE
4490 array dimension is [num_toggles] long
4492 pulldown = item chosen in each pulldown. (0 based)
4493 array dimension is [num_pulldowns] long
4495 field_text = content of the field
4496 array dimension is [num_fields] by
4497 [Z_LEN_GUI_TITLE_STR] long
4500 Notes:
4501 -----
4502 * This routine is called when the library is permanently
4503 loaded to the EnSight session, so define your globals
4504 in this and later routines.
4506 * It's up to you to change your reader behavior according to
4507 user entries!
4513 -----------------------------------------------------------------------------------
4514 /* ----------------------------------------------------------
4515 * New in EnSight 8 is the capability to remove (fail) elements
4516 * based on variable threshold values. Basically the variable
4517 * name, a couple of thresholds, a couple of values and a logic
4518 * criteria are read in from this routine. Every element that
4519 * satisfies the failure criteria is removed and not used in
4520 * EnSight calculations.
4521 *
4522 * Example Failure criteria
4523 * Let fail_var_name = "fail_flag"
4524 * threshold_val1 = 0
4525 * threshold_operator1 = Z_EQUAL_TO
4526 * logic_criteria2 not used
4527 * threshold_val2 not used
4528 * threshold_operator2 not used
4529 * For each value of "fail_flag" at each element,
4530 * if fail flag == threshold_val1 (0.0) then element fails
4531 * Return (Z_ERR) if this is not used.
4532 * Return (Z_OK) if failed element feature should be used
4533 *
4534 * threshold_operator1 & 2 can be one of the following
4535 * Z_ELE_FAILED_NONE, - disables checking
4536 * Z_ELE_FAILED_GREATER, - greater than
4537 * Z_ELE_FAILED_LESS, - less than
4538 * Z_ELE_FAILED_EQUAL, - equal
4539 * Z_ELE_FAILED_NOT_EQUAL, - not equal
4540 * Z_ELE_FAILED_MANY - not used
4541 *
4542 * logic_criteria2
4543 * Z_ELE_FAILED_LOGIC_NONE,
4544 * Z_ELE_FAILED_LOGIC_AND,
4545 * Z_ELE_FAILED_LOGIC_OR,
4546 * Z_ELE_FAILED_LOGIC_MANY
4547 *
4548 * ---------------------------------------------------------- */
4549 int USERD_get_uns_failed_params(
4550 char *fail_var_name, /* variable name to be used in failure
4551 must be scalar, per elem */
4552 float *threshold_val1, /* number to compare for failure */
4553 float *threshold_val2, /* number to compare for failure */
4554 int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN,
4555 Z_EQUAL_TO */
4556 int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN,
4557 Z_EQUAL_TO */
4558 int *logic_criteria2
4561 /*--------------------------------------------------------------------
4562 * USERD_get_structured_reader_cinching -
4563 *--------------------------------------------------------------------
4564 *
4565 * Gets whether this reader will do structured cinching for block data
4566 * This means that it will handle the min, max, and step values for a
4567 * given block and return the coordinate components or variable components
4568 * in their "cinched" state when partial extraction or striding is used.
4569 * This is as opposed to returning the entire component (ignoring min, max
4570 * and stride) and letting Ensight pick out the values actually used.
4571 *
4572 * returns: Z_OK if the reader will handle the
4573 * min, max, and stride and return
4574 * the cinched values only.
4575 *
4576 * Z_UNDEF or Z_ERR if will return entire component
4577 * and rely on EnSight to cinch.
4578 *
4579 * Notes:
4580 * Unless you can actually pull out the desired min, max, and stride
4581 * without using a full component of memory, don't enable this feature.
4582 *--------------------------------------------------------------------*/
4583 int
4584 USERD_get_structured_reader_cinching( void )
4588 /*--------------------------------------------------------------------
4589 * USERD_set_block_range_and_stride -
4590 *--------------------------------------------------------------------
4591 *
4592 * Sets the min, max, and step values in each of the i, j, and k, directions
4593 * for the given part.
4594 *
4595 * (IN) part_number = The part number
4596 *
4597 * (1-based index of part table, namely:
4598 *
4599 * 1 ... Numparts_available.
4600 *
4601 * It is NOT the part_id that
4602 * is loaded in
4603 * USERD_get_gold_part_build_info)
4604 *
4605 * (IN) mini = min i plane desired (zero based)
4606 * maxi = max i plane desired (zero based)
4607 * stepi = i stride
4608 * minj = min j plane desired (zero based)
4609 * maxj = max j plane desired (zero based)
4610 * stepj = j stride
4611 * mink = min k plane desired (zero based)
4612 * maxk = max k plane desired (zero based)
4613 * stepk = k stride
4614 *
4615 *
4616 * returns: Z_OK if no problems
4617 * Z_ERR if an error
4618 *
4619 * Notes:
4620 * * It will not be called unless USERD_get_structured_reader_cinching
4621 * indicates that this reader does structured cinching by returning
4622 * a Z_OK.
4623 *
4624 * * It will actually be called before each geom component and before
4625 * each part variable - so if you are storing things locally, you should
4626 * make this routine be able to quickly check whether anything needs
4627 * updated or not.
4628 *
4629 * * If the stride (step) does not hit right on the max, the last element
4630 * in each direction will be shortened appropriately.
4631 * For example, if a block had 0 to 12 in the i direction,
4632 * and the user specified min = 1
4633 * max = 8
4634 * step = 3
4635 *
4636 * 0 1 2 3 4 5 6 7 8 9 10 11 12
4637 * | | | | | | | | | | | | |
4638 *
4639 * | | | |
4640 *
4641 * Namely, the coarser cell boundaries in this direction would be at 1, 4,
4642 7, and 8
4643 *
4644 *--------------------------------------------------------------------*/
4645 int
4646 USERD_set_block_range_and_stride(int part_number,
4647 int mini, int maxi, int stepi,
4648 int minj, int maxj, int stepj,
4649 int mink, int maxk, int stepk)
4653 ---- end of document ----