[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.07
| blob | 3b52eed3a35b84def62d261234314aaf7e387460 |
1 README_USERD_2.07
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.07)
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.07 additional capabilities (beyond API 2.06):
17 Optional routine to allow userd defined readers to indicate their auto
18 distribute preference when used with SOS. This is used to set the auto
19 distribute flag default in the client. If the function does not exist,
20 then it defaults to 'use auto distribute'. If the function does exist and
21 indicates 'no auto distribute', then it's up to the UDR to decompose a
22 distributed data set.
23 USERD_prefer_auto_distribute
24 Optional routine to allow userd defined readers to indicate their
25 preference for the 'Set file...' button labels in the client's File->Open
26 dialog. If the function does not exist or it returns a null string for
27 an argument, then the default values are used.
28 USERD_set_filename_button_labels
30 ***>> API 2.06 additional capabilities (beyond API 2.05):
31 Routines to allow userd defined readers for structured data
32 to deal with min, max, and stride within the reader itself
33 instead of within EnSight.
34 USERD_get_structured_reader_cinching
35 USERD_set_block_range_and_stride
38 ***>> API 2.05 additional capabilities (beyond API 2.04):
39 Routines to handle material species.
40 USERD_get_number_of_species
41 USERD_get_matsp_info
43 Routines to handle variable extraction parameters after a read, and then
44 update the variables accordingly. Similar to the extra GUI capabilities
45 (which are processed before a read). (Can actually be added to pre-2.05 readers)
46 USERD_get_var_extract_gui_numbers
47 USERD_get_var_extract_gui_defaults
48 USERD_set_var_extract_gui_data
50 Routines to obtain rigid body values from a reader.
51 (Routines were added - EnSight is now using for Nastran and STL readers
52 with Dynasty rigid body motion data file)
53 USERD_rigidbody_existence
54 USERD_rigidbody_values
56 Routine that lets reader know when EnSight is getting the right side of a time
57 interval for variable interpolation between steps. Not generally needed for
58 most readers - however, may be needed for those that implement rigid body, and
59 wish to cache left and right timespan information for interpolation within the
60 reader itself. (Can actually be added to pre-2.05 readers)
61 USERD_set_right_side
64 ***>> API 2.04 additional capabilities (beyond API 2.03):
65 Routines to handle failed elements. Basically
66 a.One routine to return a flag indicating the existence of
67 failed elements in at least one part in at least one
68 timestep in the model.
69 b.A second routine to return a matrix of flags indexed by part and
70 element type indicating which parts and element types have failed
71 elements at the current time step.
72 c.Finally a third routine to return an array of flags for a given
73 part and element type that is number of elements of that type long
74 indicating which elements have failed, and which have not failed.
77 ***>> API 2.03 additional capabilities (beyond API 2.01):
78 1. Routines to handle materials
79 2. Routines to handle nsided and nfaced elements
80 3. Modified routine to handle structured ranges
83 ****************************************************************************
84 Note: Only the the Ensight Gold example reader, has been moved to
85 this 2.06 API level. And it is purely for an example - it does not
86 actually provide a benefit.
87 ****************************************************************************
90 The process for producing a user defined reader is:
91 ---------------------------------------------------
92 1. Write code for all pertinent routines in the library (Unless someone else
93 has done this for you).
95 This is of course where the work is done by the user. The word
96 "pertinent" is used because depending on the nature of the data, some
97 of the routines in the library may be dummy routines.
99 The source code for a dummy_gold library and for various other
100 working or sample libraries is copied from the installation CD during
101 installation. These will be located in directories under:
103 $CEI_HOME/ensight76/user_defined_src/readers
105 examples:
106 --------
107 Basic dummy_gold routines provide skeleton for a new reader
108 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
110 Sample library which reads unstructured binary EnSight Gold data
111 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
113 You may find it useful to place your library source in this area as
114 well, but are not limited to this location.
116 * ===> The descriptions of each library routine and the order that the
117 routines are called, which is provided in this file, along with
118 the example libraries, should make it possible for you to produce
119 code for your own data reader.
122 2. Produce the dynamic shared library.
124 This is a compiling and loading process which varies according to
125 the type of machine you are on. In the user-defined-reader source
126 tree we have tried to isolate the machine dependent parts of the
127 build process using a set of files in the 'config' directory. In this
128 directory there is a configuration file for each platform on which
129 EnSight is supported. Before you can compile the installed readers
130 you should run the script called 'init' in the config directory.
132 i.e. (for UNIX)
133 cd config
134 ./init sgi_6.5_n64
135 cd ..
136 make
138 If you are compiling for Windows NT, there are two options. If you
139 have the Cygwin GNU utilities installed, you can use GNU make as for
140 Unix. Otherwise, there is a script called makeall.cmd which will
141 build all of the readers using nmake. The Makefiles in each reader
142 directory will work using either make or nmake.
144 i.e. (WIN32 Cygwin) (using nmake)
145 cd config cd config
146 sh init win32 cp win32 config
147 cd .. cd ..
148 mkdir lib
149 make makeall.cmd
151 If you have platform-specific portions of code in your reader, the
152 build system defines a set of flags which can be used within
153 #ifdef ... #endif regions in your source, as shown in the table
154 below.
156 Because the readers are now dynamically opened by EnSight, you may
157 have to include dependent libraries on your link-line to avoid having
158 unresolved symbols. If you are having problems with a reader, start
159 ensight as "ensight7 -readerdbg" and you will get feedback on any
160 problems encountered in loading a reader. If there are unresolved
161 symbols, you need to find the library which contains the missing
162 symbols and link it into your reader by adding it to the example
163 link commands below.
165 If you choose to use a different build environment for your reader,
166 you should take care to use compatible compilation flags to ensure
167 compatibilty with the EnSight executables, most notably on the SGI
168 and HP-UX 11.0 platforms, which should use the following flags:
170 sgi_6.2_o32: -mips2
171 sgi_6.2_n64: -mips4 -64
172 sgi_6.5_n32: -mips3
173 sgi_6.5_n64: -mips4 -64
174 hp_11.0_32: +DA2.0
175 hp_11.0_64: +DA2.0W
177 ______________________________________________________________________
178 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
179 | TYPE |------------------------------------------------------------|
180 | | LD COMMAND USED IN MAKEFILE |
181 ======================================================================
182 ______________________________________________________________________
183 | sgi | -DSGI | libuserd-X.so |
184 | |------------------------------------------------------------|
185 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
186 ----------------------------------------------------------------------
187 ______________________________________________________________________
188 | hp | -DHP | libuserd-X.sl |
189 | |------------------------------------------------------------|
190 | | ld -b -o libuserd-X.sl libuserd-X.o |
191 ----------------------------------------------------------------------
192 ______________________________________________________________________
193 | sun | -DSUN | libuserd-X.so |
194 | |------------------------------------------------------------|
195 | | ld -G -o libuserd-X.so libuserd-X.o |
196 ----------------------------------------------------------------------
197 ______________________________________________________________________
198 | dec | -DDEC | libuserd-X.so |
199 | |------------------------------------------------------------|
200 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
201 ----------------------------------------------------------------------
202 ______________________________________________________________________
203 | linux | -DLINUX | libuserd-X.so |
204 | |------------------------------------------------------------|
205 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
206 ----------------------------------------------------------------------
207 ______________________________________________________________________
208 | alpha | -DALINUX | libuserd-X.so |
209 | linux |------------------------------------------------------------|
210 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
211 ----------------------------------------------------------------------
212 ______________________________________________________________________
213 | ibm | -DIBM | libuserd-X.so |
214 | |------------------------------------------------------------|
215 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
216 ----------------------------------------------------------------------
218 Once you have created your library, you should place it in a directory
219 of your choice or in the standard reader location:
221 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
223 For example, if you created a reader for "mydata", you should create
224 the reader libuserd-mydata.so and place the file in your own reader
225 directory (see section 3 below) or in the standard location:
227 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
230 3. By default EnSight will load all readers found in the directory:
232 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
234 Files with names "libuserd-X.so" (where X is a name unique to the reader)
235 are assumed to be user-defined readers.
237 There are two methods which can be used to supplement the default
238 behavior.
240 (1) A feature which is useful for site-level or user-level configuration
241 is the optional environment variable $ENSIGHT7_READER. This
242 variable directs EnSight to load all readers in the specified reader
243 directory (you should probably specify a full path) before loading
244 the built-in readers. If the same reader exists in both directories
245 (as determined by the name returned by USERD_get_name_of_reader(),
246 NOT by the filename), the locally configured reader will take
247 precedence.
249 (2) A useful feature for end-users is the use of the libuserd-devel
250 reader. EnSight will search for a reader named libuserd-devel.so
251 (.sl for HP or .dll for NT). This reader can exist anywhere in the
252 library path (see below) of the user. This is useful for an
253 individual actively developing a reader because the existence of a
254 libuserd-devel library will take precedence over any other library
255 which returns the same name from USERD_get_name_of_reader().
257 As an example, a site may install commonly used readers in a common
258 location, and users can set the ENSIGHT7_READER variable to access them:
260 setenv ENSIGHT7_READER /usr/local/lib/e7readers
262 A user working on a new reader may compile the reader and place it in
263 a directory specified by the library path:
265 cp libuserd-myreader.so ~/lib/libuserd-devel.so
266 setenv <librarypath> ~/lib:$<librarypath>
268 The user is responsible for correctly configuring the library path
269 variable in order to make use of the libuserd-devel feature. The
270 library environment variables used are:
272 Machine type Environment variable to set
273 ------------ ---------------------------
274 sgi LD_LIBRARY_PATH
275 dec LD_LIBRARY_PATH
276 sun LD_LIBRARY_PATH
277 linux LD_LIBRARY_PATH
278 alpha linux LD_LIBRARY_PATH
279 hp SHLIB_PATH
280 ibm LIBPATH
282 As always, EnSight support is available if you need it.
284 -------------------------------
285 Quick Index of Library Routines
286 -------------------------------
288 Generally Needed for UNSTRUCTURED data
289 --------------------------------------
290 USERD_get_part_coords part's node coordinates
291 USERD_get_part_node_ids part's node ids
292 USERD_get_part_elements_by_type part's element connectivites
293 USERD_get_part_element_ids_by_type part's element ids
296 Generally Needed for BLOCK data
297 --------------------------------------
298 USERD_get_block_coords_by_component block coordinates
299 USERD_get_block_iblanking block iblanking values
300 USERD_get_ghosts_in_block_flag block ghost cell existence?
301 USERD_get_block_ghost_flags block ghost cell flags
303 These routines, which formerly were only for unstructured data, will now
304 also be called for structured data if you specify that ids will be given
305 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
306 ------------------------------------------------------------------------------
307 USERD_get_part_node_ids part's node ids
308 USERD_get_part_element_ids_by_type part's element ids
311 Generally needed for either or both kinds of data
312 -------------------------------------------------
313 USERD_get_name_of_reader name of reader for GUI
314 USERD_get_reader_release release string of reader
315 USERD_get_reader_version provide reader version number
316 USERD_get_reader_descrip provide GUI more description (optional)
318 USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields
319 USERD_get_extra_gui_defaults Gets the default values for the GUI members
320 USERD_set_extra_gui_data Returns the answers provided by the user
322 USERD_set_filenames filenames entered in GUI
323 USERD_set_server_number server which of how many
325 USERD_get_number_of_timesets number of timesets
326 USERD_get_timeset_description description of timeset
327 USERD_get_geom_timeset_number timeset # to use for geom
329 USERD_get_num_of_time_steps number of time steps
330 USERD_get_sol_times solution time values
331 USERD_set_time_set_and_step current timeset and time step
333 USERD_get_changing_geometry_status changing geometry?
334 USERD_get_node_label_status node labels?
335 USERD_get_element_label_status element labels?
336 USERD_get_model_extents provide model bounding extents
337 USERD_get_number_of_files_in_dataset number of files in model
338 USERD_get_dataset_query_file_info info about each model file
339 USERD_get_descrip_lines file associated description lines
340 USERD_get_number_of_model_parts number of model parts
341 USERD_get_gold_part_build_info Gets the info needed for part building process
342 USERD_get_part_build_info part/block type/descrip etc.
343 USERD_get_maxsize_info part/block allocation maximums
344 USERD_get_ghosts_in_model_flag model contains ghost cells?
345 USERD_get_nsided_conn Gets the element connectivities for nsided
346 elements. (utilizes the number of nodes
347 per element obtained in
348 USERD_get_part_elements_by_type)
349 USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced
350 elements (utilizes the number of faces
351 per element obtained in
352 USERD_get_part_elements_by_type)
353 USERD_get_nfaced_conn Gets the element connectivities for nfaced
354 elements (utilizes the number of nodes
355 per face obtained in
356 USERD_get_nfaced_nodes_per_face)
359 USERD_get_border_availability part border provided?
360 USERD_get_border_elements_by_type part border conn and parent info
362 USERD_get_number_of_variables number of variables
363 USERD_get_gold_variable_info variable type/descrip etc.
364 USERD_get_var_by_component part or block variable values
365 USERD_get_constant_val constant variable's value
366 USERD_get_var_value_at_specific node's or element's variable value over time
367 USERD_stop_part_building cleanup after part build routine
369 USERD_get_number_of_material_sets Gets the number of material sets
370 USERD_get_matf_set_info Gets the material set indices and names
371 USERD_get_number_of_materials Gets the number of materials
372 USERD_get_matf_var_info Gets the material indices and descriptions
373 USERD_size_matf_data Gets the length of either the
374 material ids list,
375 mixed-material ids list, or
376 mixed-material values list
377 USERD_load_matf_data Gets the material ids list,
378 mixed-material ids list, or
379 mixed-material values list
381 USERD_bkup archive routine
383 USERD_exit_routine cleanup upon exit routine
385 USERD_get_uns_failed_params Gets thresholds/criteria for failure
387 USERD_rigidbody_existence Returns whether rigid body transformation
388 data exists for the model.
389 USERD_rigidbody_values Returns the euler and location values for a
390 given part
392 USERD_set_right_side Simply informs the reader when the time set
393 is for the right side of a time span during
394 variable interpolation between time steps.
396 USERD_get_structured_reader_cinching Tells if the reader will do structured
397 cinching
398 USERD_set_block_range_and_stride Sets the min, max, and stride of a block
399 if doing structured cinching
402 -------------------------
403 Order Routines are called
404 -------------------------
406 The various main operations are given basically in the order they will
407 be performed. Within each operation, the order the routines will be
408 called is given.
410 1. Setting name in the gui, and specifying one or two input fields
412 USERD_get_name_of_reader
413 USERD_get_reader_descrip (optional)
414 USERD_get_extra_gui_numbers (optional)
415 USERD_get_extra_gui_defaults (optional)
417 2. Getting the reader version (also distinguishes between API's)
419 USERD_get_reader_version
421 3. Setting filenames and getting timeset and time info
423 <USERD_set_extra_gui_data> (optional if reader has
424 USERD_get_extra_gui_defaults routine)
425 USERD_get_structured_reader_cinching
426 USERD_set_server_number
427 USERD_set_extra_gui_data (optional)
428 USERD_set_filenames
429 USERD_get_number_of_timesets
430 USERD_get_geom_timeset_number
432 for each timeset:
433 USERD_get_timeset_description
434 USERD_get_num_of_time_steps
435 USERD_get_sol_times
437 USERD_set_time_set_and_step
439 4. Gathering info for part builder
441 USERD_set_time_set_and_step
442 USERD_get_changing_geometry_status
443 USERD_get_node_label_status
444 USERD_get_element_label_status
445 USERD_get_number_of_files_in_dataset
446 USERD_get_dataset_query_file_info
447 USERD_get_descrip_lines (for geometry)
448 USERD_get_number_of_model_parts
449 USERD_get_gold_part_build_info
450 USERD_get_ghosts_in_model_flag
451 USERD_get_maxsize_info
452 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
453 USERD_get_model_extents OR (for model extents)
454 USERD_get_part_coords AND/OR
455 <USERD_set_block_range_and_stride> (if doing structured reader cinching
456 USERD_get_block_coords_by_component
458 5. Gathering Variable info
460 USERD_get_number_of_variables
461 USERD_get_gold_variable_info
463 6. Part building (per part created)
465 both unstructured and structured:
466 --------------------------------
467 USERD_set_time_set_and_step
469 if unstructured part:
470 --------------------
471 USERD_get_part_element_ids_by_type
472 USERD_get_part_elements_by_type
474 If any nsided elements:
476 USERD_get_nsided_conn
478 If any nfaced elements:
480 USERD_get_nfaced_nodes_per_face
481 USERD_get_nfaced_conn
483 USERD_get_part_coords
484 USERD_get_part_node_ids
486 else if structured part:
487 -----------------------
488 USERD_get_block_iblanking
489 <USERD_set_block_range_and_stride> (if doing structured reader cinching
490 USERD_get_block_coords_by_component
491 USERD_get_block_ghost_flags (If ghost cells in part)
492 USERD_get_part_node_ids (If node ids given)
493 USERD_get_part_element_ids_by_type (If element ids given)
495 both again:
496 ----------
497 USERD_get_border_availability (If border representation
498 USERD_get_border_elements_by_type is selected)
500 USERD_stop_part_building (only once when part builder
501 dialog is closed)
503 7. Loading Variables
505 constants:
506 ---------
507 USERD_set_time_set_and_step
508 USERD_get_constant_val
510 scalars/vectors/tensors:
511 ------------------------
512 USERD_get_descrip_lines
513 USERD_set_time_set_and_step
514 <USERD_set_block_range_and_stride> (if doing structured reader cinching
515 USERD_get_var_by_component
517 8. Changing geometry
519 changing coords only (per part):
520 --------------------
521 USERD_set_time_set_and_step
522 USERD_get_descrip_lines
523 USERD_get_part_coords
524 <USERD_set_block_range_and_stride> (if doing structured reader cinching
525 USERD_get_block_coords_by_component
527 changing connectivity (per part):
528 ---------------------
529 USERD_set_time_set_and_step
530 USERD_get_descrip_lines
531 USERD_get_number_of_model_parts
532 USERD_get_gold_part_build_info
533 USERD_get_ghosts_in_model_flag
534 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
535 USERD_get_model_extents OR
536 USERD_get_part_coords AND/OR
537 <USERD_set_block_range_and_stride> (if doing structured reader cinching
538 USERD_get_block_coords_by_component
539 USERD_get_part_element_ids_by_type
540 USERD_get_part_elements_by_type
541 USERD_get_part_coords
542 USERD_get_part_node_ids
543 USERD_get_block_iblanking
544 <USERD_set_block_range_and_stride> (if doing structured reader cinching
545 USERD_get_block_coords_by_component
546 USERD_get_block_ghost_flags (If ghost cells in part)
547 USERD_get_part_node_ids (If node ids given)
548 USERD_get_part_element_ids_by_type (If element ids given)
550 USERD_get_border_availability (If border representation
551 USERD_get_border_elements_by_type is selected)
554 9. Node or Element queries over time
556 USERD_get_var_value_at_specific
558 10. To see if materials in the model
560 USERD_get_number_of_material_sets
561 USERD_get_matf_set_info
563 If any material sets in the model (calls these once per material set):
564 USERD_get_number_of_materials
565 USERD_get_matf_var_info
567 For each elment type of each part containing material ids, calls:
568 USERD_size_matf_data
569 USERD_load_matf_data
571 If there are any elements with mixed materials, when a domain or
572 interface is created, calls these again per part:
574 USERD_size_matf_data
575 USERD_load_matf_data
577 11. To modify the variable extraction parameters and have the variables
578 update accordingly.
580 USERD_get_var_extract_gui_numbers
581 USERD_get_var_extract_gui_defaults
582 USERD_set_var_extract_gui_data
586 -----------------------
587 Detailed Specifications
588 -----------------------
590 Include files:
591 --------------
592 The following header file is required in any file containing these library
593 routines.
595 #include "global_extern.h"
597 And it references:
599 #include "global_extern_proto.h"
603 *******************************************************************************
604 ****************************** Special Note ***********************************
605 *******************************************************************************
607 Make sure you use the proper define in the global_extern.h header file, namely:
608 #define USERD_API_204
610 Also, Make sure the api version in the USERD_get_reader_version routine is set
611 to "2.04" or larger.
613 Make sure your reader has access to the global_extern_proto.h This is a new
614 file which is accessed from the new global_extern.h
616 *******************************************************************************
617 *******************************************************************************
620 Basis of arrays:
621 ---------------
622 Unless explicitly stated otherwise, all arrays are zero based - in true C
623 fashion.
626 Global variables:
627 ----------------
628 You will generally need to have a few global variables which are shared by
629 the various library routines. The detailed specifications below have assumed
630 the following are available. (Their names describe their purpose, and they
631 will be used in helping describe the details of the routines below).
633 static int Numparts_available = 0;
634 static int Num_unstructured_parts = 0;
635 static int Num_structured_blocks = 0;
637 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
639 static int Num_timesets = 1;
640 static int Current_timeset = 1;
641 static int Geom_timeset_number = 1;
643 static int Num_time_steps[Z_MAXSETS] = 1;
644 static int Current_time_step = 0;
645 static int Num_variables = 0;
646 static int Num_dataset_files = 0;
648 static int Server_Number = 1; Which server of
649 static int Tot_Servers = 1; the total number of servers
653 _________________________________________
654 -----------------------------------------
655 Library Routines (in alphabetical order):
656 _________________________________________
657 -----------------------------------------
659 --------------------------------------------------------------------
660 USERD_bkup
662 Description:
663 -----------
664 This routine is called during the EnSight archive process. You can
665 use it to save or restore info relating to your user defined reader.
667 Specification:
668 -------------
669 int USERD_bkup(FILE *archive_file,
670 int backup_type)
672 Returns:
673 -------
674 Z_OK if successful
675 Z_ERR if not successful
677 Arguments:
678 ---------
679 (IN) archive_file = The archive file pointer
681 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
682 Z_REST_ARCHIVE for restoring archive
684 Notes:
685 -----
686 * Since EnSight's archive file is saved in binary form, you should
687 also do any writing to it or reading from it in binary.
689 * You should archive any variables, which will be needed for
690 future operations, that will not be read or computed again
691 before they will be needed. These are typically global
692 variables.
694 * Make sure that the number of bytes that you write on a save and
695 the number of bytes that you read on a restore are identical!!
697 * If any of the variables you save are allocated arrays, you must
698 do the allocations before restoring into them.
700 --------------------------------------------------------------------
701 USERD_exit_routine
703 Description:
704 -----------
705 This routine is called as EnSight is exiting. It can be used to clean
706 up anything needed - such as removing temporary files, etc. - or can simply
707 be a dummy.
709 Specification:
710 -------------
711 void USERD_exit_routine( void )
713 Arguments:
714 ---------
715 none
717 --------------------------------------------------------------------
718 USERD_get_block_coords_by_component
720 Description:
721 -----------
722 Get the coordinates of a given structured block, a component at a time.
724 Specification:
725 -------------
726 int USERD_get_block_coords_by_component(int block_number,
727 int which_component,
728 float *coord_array)
730 Returns:
731 -------
732 Z_OK if successful
733 Z_ERR if not successful
735 Arguments:
736 ---------
737 (IN) block_number = The block part number
738 (1-based index of part table, namely:
740 1 ... Numparts_available.
742 It is NOT the part_id that
743 is loaded in USERD_get_gold_part_build_info)
745 (IN) which_component = Z_COMPX if x component wanted
746 = Z_COMPY if y component wanted
747 = Z_COMPZ if z component wanted
749 (OUT) coord_array = 1D array containing x,y, or z
750 coordinate component of each node
752 (Array will have been allocated
753 i*j*k for the block long)
755 Notes:
756 -----
757 * Not called unless Num_structured_blocks is > 0
759 * Will be based on Current_time_step
763 --------------------------------------------------------------------
764 USERD_get_block_iblanking
766 Description:
767 -----------
768 Get the iblanking value at each node of a block (if the block is
769 iblanked).
771 Specification:
772 -------------
773 int USERD_get_block_iblanking(int block_number,
774 int *iblank_array)
776 Returns:
777 -------
778 Z_OK if successful
779 Z_ERR if not successful
781 Arguments:
782 ---------
783 (IN) block_number = The block part number
784 (1-based index of part table, namely:
786 1 ... Numparts_available.
788 It is NOT the part_id that
789 is loaded in USERD_get_gold_part_build_info)
791 (OUT) iblank_array = 1D array containing iblank value
792 for each node.
794 (Array will have been allocated
795 i*j*k for the block long)
797 possible values are: Z_EXT = exterior
798 Z_INT = interior
799 Z_BND = boundary
800 Z_INTBND = internal boundary
801 Z_SYM = symmetry plane
803 Notes:
804 -----
805 * Not called unless Num_structured_blocks is > 0 and you have
806 some iblanked blocks
808 * Will be based on Current_time_step
812 ----------------------------------------------------------------------
813 USERD_get_block_ghost_flags
815 Description:
816 -----------
817 Get the ghost_flags value at each element of a block containing ghost cells.
819 Specification:
820 -------------
821 int USERD_get_block_ghost_flags(int block_number,
822 int *ghost_flags)
823 Returns:
824 -------
825 Z_OK if successful
826 Z_ERR if not successful
828 Arguments:
829 ---------
830 (IN) block_number = The block number
831 (1-based index of part table, namely:
833 1 ... Numparts_available.
835 It is NOT the part_id that
836 is loaded in USERD_get_gold_part_build_info)
838 (OUT) ghost_flags = 1D array containing ghost flag value
839 for each block cell.
841 (Array will have been allocated
842 (i-1)*(j-1)*(k-1) for the block long)
844 possible values are: 0 = non-ghost cell (normal cell)
845 >0 = ghost cell
847 Notes:
848 -----
849 * This routine is new in the 2.01 API
851 * This will be based on Current_time_step
853 * Only called for structured "block" parts that have some ghost cells
854 as indicated by the USERD_get_ghost_in_block_flag. The model must
855 of course also have been indicated to have some ghost cells in the
856 USERD_get_ghost_in_model_flag routine.
858 * It is sufficient to set the value to be 1 to flag as a ghost cell,
859 but the value can be any non-zero value, so you could use it to
860 indicate which block or which server (for Server-of-server use) the
861 cell is actually in.
865 --------------------------------------------------------------------
866 USERD_get_border_availability
868 Description:
869 -----------
870 Finds out if border elements are provided by the reader for the
871 desired part, or will need to be computed internally by EnSight.
873 Specification:
874 -------------
875 int USERD_get_border_availability(int part_number,
876 int number_of_elements[Z_MAXTYPE])
878 Returns:
879 -------
880 Z_OK if border elements will be provided by the reader.
881 (number_of_elements array will be loaded and
882 USERD_get_border_elements_by_type will be called)
884 Z_ERR if border elements are not available - thus EnSight must compute.
885 (USERD_get_border_elements_by_type will not be called)
888 Arguments:
889 ---------
890 (IN) part_number = The part number
891 (1-based index of part table, namely:
893 1 ... Numparts_available.
895 It is NOT the part_id that
896 is loaded in USERD_get_gold_part_build_info)
898 (OUT) number_of_elements = 2D array containing number of
899 each type of border element in
900 the part.
901 ------------
902 Possible types are:
904 Z_POINT = point
905 Z_BAR02 = 2-noded bar
906 Z_BAR03 = 3-noded bar
907 Z_TRI03 = 3-noded triangle
908 Z_TRI06 = 6-noded triangle
909 Z_QUA04 = 4-noded quadrilateral
910 Z_QUA08 = 8-noded quadrilateral
912 Notes:
913 -----
914 * Only called if border representation is used.
916 * Will be based on Current_time_step
920 --------------------------------------------------------------------
921 USERD_get_border_elements_by_type
923 Description:
924 -----------
925 Provides border element connectivity and parent information.
927 Specification:
928 -------------
929 int USERD_get_border_elements_by_type(int part_number,
930 int element_type,
931 int **conn_array,
932 short *parent_element_type,
933 int *parent_element_num)
935 Returns:
936 -------
937 Z_OK if successful
938 Z_ERR if not successful
940 Arguments:
941 ---------
942 (IN) part_number = The part number
943 (1-based index of part table, namely:
945 1 ... Numparts_available.
947 It is NOT the part_id that
948 is loaded in USERD_get_gold_part_build_info)
950 (IN) element_type = One of the following (See global_extern.h)
951 Z_POINT node point element
952 Z_BAR02 2 node bar
953 Z_BAR03 3 node bar
954 Z_TRI03 3 node triangle
955 Z_TRI06 6 node triangle
956 Z_QUA04 4 node quad
957 Z_QUA08 8 node quad
959 (OUT) conn_array = 2D array containing connectivity
960 of each border element of the type.
962 (Array will have been allocated
963 num_of_elements of the type by
964 connectivity length of the type)
966 ex) If number_of_elements[Z_TRI03] = 25
967 number_of_elements[Z_QUA04] = 100
968 number_of_elements[Z_QUA08] = 30
969 as obtained in:
970 USERD_get_border_availability
972 Then the allocated dimensions available
973 for this routine will be:
974 conn_array[25][3] when called with Z_TRI03
976 conn_array[100][4] when called with Z_QUA04
978 conn_array[30][8] when called with Z_QUA08
980 (OUT) parent_element_type = 1D array containing element type of the
981 parent element (the one that the border
982 element is a face/edge of).
984 (Array will have been allocated
985 num_of_elements of the type long)
987 (OUT) parent_element_num = 1D array containing element number of the
988 parent element (the one that the border
989 element is a face/edge of).
991 (Array will have been allocated
992 num_of_elements of the type long)
995 Notes:
996 -----
997 * Not called unless USERD_get_border_availability returned Z_OK
999 * Will be based on Current_time_step
1003 --------------------------------------------------------------------
1004 USERD_get_changing_geometry_status
1006 Description:
1007 -----------
1008 Gets the changing geometry status for the model
1010 Specification:
1011 -------------
1012 int USERD_get_changing_geometry_status( void )
1014 Returns:
1015 -------
1016 Z_STATIC if geometry does not change
1017 Z_CHANGE_COORDS if changing coordinates only
1018 Z_CHANGE_CONN if changing connectivity
1020 Arguments:
1021 ---------
1022 none
1024 Notes:
1025 -----
1026 * EnSight does not support changing number of parts. But the
1027 coords and/or the connectivity of the parts can change. Note that
1028 a part is allowed to be empty (number of nodes and elements equal
1029 to zero).
1032 --------------------------------------------------------------------
1033 USERD_get_constant_val
1035 Description:
1036 -----------
1037 Get the value of a constant at a time step
1039 Specification:
1040 -------------
1041 float USERD_get_constant_value(int which_var,
1042 int imag_data)
1044 Returns:
1045 -------
1046 Value of the requested constant variable
1048 Arguments:
1049 ---------
1050 (IN) which_var = The variable number
1052 (IN) imag_data = TRUE if want imaginary data value.
1053 FALSE if want real data value.
1055 Notes:
1056 -----
1057 * Will be based on Current_time_step
1061 --------------------------------------------------------------------
1062 USERD_get_dataset_query_file_info
1064 Description:
1065 -----------
1066 Get the information about files in the dataset. Used for the
1067 dataset query option within EnSight.
1069 Specification:
1070 -------------
1071 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
1073 Returns:
1074 -------
1075 Z_OK if successful
1076 Z_ERR if not successful
1078 Arguments:
1079 ---------
1080 (OUT) qfiles = Structure containing information about each file
1081 of the dataset. The Z_QFILES structure is defined
1082 in the global_extern.h file
1084 (The structure will have been allocated
1085 Num_dataset_files long, with 10 description
1086 lines per file).
1088 qfiles[].name = The name of the file
1089 (Z_MAXFILENP is the dimensioned length
1090 of the name)
1092 qfiles[].sizeb = The number of bytes in the file
1093 (Typically obtained with a call to the
1094 "stat" system routine) (Is a long)
1096 qfiles[].timemod = The time the file was last modified
1097 (Z_MAXTIMLEN is the dimensioned length
1098 of this string)
1099 (Typically obtained with a call to the
1100 "stat" system routine)
1102 qfiles[].num_d_lines = The number of description lines you
1103 are providing from the file. Max = 10
1105 qfiles[].f_desc[] = The description line(s) per file,
1106 qfiles[].num_d_lines of them
1107 (Z_MAXFILENP is the allocated length of
1108 each line)
1110 Notes:
1111 -----
1112 * If Num_dataset_files is 0, this routine will not be called.
1113 (See USERD_get_number_of_files_in_dataset)
1116 --------------------------------------------------------------------
1117 USERD_get_descrip_lines
1119 Description:
1120 -----------
1121 Get two description lines associated with geometry per time step,
1122 or one description line associated with a variable per time step.
1124 Specification:
1125 -------------
1126 int USERD_get_descrip_lines(int which_type,
1127 int which_var,
1128 int imag_data,
1129 char line1[Z_BUFL],
1130 char line2[Z_BUFL])
1132 Returns:
1133 -------
1134 Z_OK if successful
1135 Z_ERR if not successful
1137 Arguments:
1138 ---------
1139 (IN) which_type = Z_GEOM for geometry (2 lines)
1140 = Z_VARI for variable (1 line)
1142 (IN) which_var = If it is a variable, which one.
1143 Ignored if geometry type.
1145 (IN) imag_data = TRUE if want imaginary data file.
1146 FALSE if want real data file.
1148 (OUT) line1 = The 1st geometry description line,
1149 or the variable description line.
1151 (OUT) line2 = The 2nd geometry description line
1152 Not used if variable type.
1154 Notes:
1155 -----
1156 * Will be based on Current_time_step
1158 * These are the lines EnSight can echo to the screen in
1159 annotation mode.
1163 --------------------------------------------------------------------
1164 USERD_get_element_label_status
1166 Description:
1167 -----------
1168 Answers the question as to whether element labels will be provided.
1170 Specification:
1171 -------------
1172 int USERD_get_element_label_status( void )
1174 Returns:
1175 -------
1176 TRUE if element labels will be provided
1177 FALSE if element labels will NOT be provided
1179 Arguments:
1180 ---------
1181 none
1183 Notes:
1184 -----
1185 * element lables are needed in order to do any element querying, or
1186 element labeling on-screen within EnSight.
1188 * Prior to API 2.01:
1189 -----------------
1190 For unstructured parts, you can read them from your file if
1191 available, or can assign them, etc. They need to be unique
1192 per part, and are often unique per model.
1194 API 1.0:
1195 USERD_get_element_ids_for_part is used to obtain the ids,
1196 on a part by part basis, if TRUE status is returned here.
1198 API 2.0:
1199 USERD_get_part_element_ids_by_type is used to obtain the ids,
1200 on a per part, per type basis, if TRUE status is returned here.
1202 For structured parts, EnSight will assign ids if you return a
1203 status of TRUE here. You cannot assign them youself!!
1205 * Starting at API 2.01:
1206 --------------------
1207 For both unstructured and structured parts, you can read them
1208 from your file if available, or can assign them, etc. They need
1209 to be unique per part, and are often unique per model (especially
1210 if you are dealing with a decomposed dataset).
1212 USERD_get_part_element_ids_by_type is used to obtain the ids,
1213 on an element type by part basis, if TRUE status is returned here.
1215 * Will call USERD_get_part_element_ids_by_type for each type of
1216 of each part if this routine returns TRUE.
1217 --------------------------------------------------------------------
1218 USERD_get_geom_timeset_number -
1220 Description:
1221 -----------
1222 Gets the timeset number to be used for geometry
1224 Specification:
1225 -------------
1226 int USERD_get_geom_timeset_number( void )
1228 Returns:
1229 -------
1230 Geom_timeset_number = The timeset number that will be used for geometry.
1231 For example, if USERD_get_number_of timesets
1232 returns 2, the valid timeset numbers would be
1233 1 or 2.
1235 Arguments:
1236 ---------
1237 none
1239 Notes:
1240 -----
1241 * If your model is static, which you indicated by returning a zero
1242 in USERD_get_number_of_timesets, you can return a zero here as well.
1246 --------------------------------------------------------------------
1247 USERD_get_gold_part_build_info
1249 Description:
1250 -----------
1251 Gets the info needed for the part building process.
1253 Specification:
1254 -------------
1255 int USERD_get_gold_part_build_info(int *part_id,
1256 int *part_types,
1257 char *part_description[Z_BUFL],
1258 int *number_of_nodes,
1259 int *number_of_elements[Z_MAXTYPE],
1260 int *ijk_dimensions[9],
1261 int *iblanking_options[6])
1263 Returns:
1264 -------
1265 Z_OK if successful
1266 Z_ERR if not successful
1268 Arguments:
1269 ---------
1270 (OUT) part_id = Array containing the external part
1271 ids for each of the model parts.
1273 IMPORTANT:
1274 Parts numbers must be >= 1, because
1275 of the way they are used in the GUI
1277 *******************************************
1278 The ids provided here are the numbers by
1279 which the parts will be referred to in the
1280 GUI (if possible). They are basically
1281 labels as far as you are concerned.
1283 Note: The part numbers you pass to routines
1284 which receive a part_number or block_number
1285 or which_part as an argument are the 1-based
1286 table index of the parts!
1288 example: If Numparts_available = 3
1290 Table index part_id
1291 ----------- -------
1292 1 13
1293 2 57
1294 3 125
1296 ^ ^
1297 | |
1298 | These are placed in:
1299 | part_id[0] = 13
1300 | part_id[1] = 57
1301 | part_id[2] = 125
1302 | for GUI labeling purposes.
1303 |
1304 These implied table indices are the part_number,
1305 block_number, or which_part numbers that you would
1306 pass to routines like:
1308 USERD_get_part_coords(int part_number,...
1309 USERD_get_part_node_ids(int part_number,...
1310 USERD_get_part_elements_by_type(int part_number,...
1311 USERD_get_part_element_ids_by_type(int part_number,...
1312 USERD_get_block_coords_by_component(int block_number,...
1313 USERD_get_block_iblanking(int block_number,...
1314 USERD_get_block_ghost_flags(int block_number,...
1315 USERD_get_ghosts_in_block_flag(int block_number)
1316 USERD_get_border_availability(int part_number,...
1317 USERD_get_border_elements_by_type(int part_number,...
1318 USERD_get_var_by_component(int which_variable,
1319 int which_part,...
1320 USERD_get_var_value_at_specific(int which_var,
1321 int which_node_or_elem,
1322 int which_part,...
1323 ********************************************
1325 (Array will have been allocated
1326 Numparts_available long)
1328 (OUT) part_types = Array containing one of the
1329 following for each model part:
1331 Z_UNSTRUCTURED or
1332 Z_STRUCTURED or
1333 Z_IBLANKED
1335 (Array will have been allocated
1336 Numparts_available long)
1338 (OUT) part_description = Array containing a description
1339 for each of the model parts
1341 (Array will have been allocated
1342 Numparts_available by Z_BUFL
1343 long)
1345 (OUT) number_of_nodes = Number of unstructured nodes in the part
1347 (Array will have been allocated
1348 Numparts_available long)
1350 (OUT) number_of_elements = 2D array containing number of
1351 each type of element for each
1352 unstructured model part.
1353 ------------
1354 Possible types are:
1356 Z_POINT = point
1357 Z_BAR02 = 2-noded bar
1358 Z_BAR03 = 3-noded bar
1359 Z_TRI03 = 3-noded triangle
1360 Z_TRI06 = 6-noded triangle
1361 Z_QUA04 = 4-noded quadrilateral
1362 Z_QUA08 = 8-noded quadrilateral
1363 Z_TET04 = 4-noded tetrahedron
1364 Z_TET10 = 10-noded tetrahedron
1365 Z_PYR05 = 5-noded pyramid
1366 Z_PYR13 = 13-noded pyramid
1367 Z_PEN06 = 6-noded pentahedron
1368 Z_PEN15 = 15-noded pentahedron
1369 Z_HEX08 = 8-noded hexahedron
1370 Z_HEX20 = 20-noded hexahedron
1372 Z_G_POINT = ghost node point element
1373 Z_G_BAR02 = 2 node ghost bar
1374 Z_G_BAR03 = 3 node ghost bar
1375 Z_G_TRI03 = 3 node ghost triangle
1376 Z_G_TRI06 = 6 node ghost triangle
1377 Z_G_QUA04 = 4 node ghost quad
1378 Z_G_QUA08 = 8 node ghost quad
1379 Z_G_TET04 = 4 node ghost tetrahedron
1380 Z_G_TET10 = 10 node ghost tetrahedron
1381 Z_G_PYR05 = 5 node ghost pyramid
1382 Z_G_PYR13 = 13 node ghost pyramid
1383 Z_G_PEN06 = 6 node ghost pentahedron
1384 Z_G_PEN15 = 15 node ghost pentahedron
1385 Z_G_HEX08 = 8 node ghost hexahedron
1386 Z_G_HEX20 = 20 node ghost hexahedron
1388 (Ignored unless Z_UNSTRUCTURED type)
1390 (Array will have been allocated
1391 Numparts_available by
1392 Z_MAXTYPE long)
1394 (OUT) ijk_dimensions = 2D array containing ijk dimension info
1395 for structured blocks
1397 For Z_UNSTRUCTURED - is ignored
1399 For Z_STRUCTURED or Z_IBLANKED
1401 Prior to version 2.03:
1402 ----------------------
1403 (Array will have been allocated
1404 Numparts_available by 3 long)
1406 ijk_dimensions[][0] = I dimension
1407 ijk_dimensions[][1] = J dimension
1408 ijk_dimensions[][2] = K dimension
1411 Starting at version 2.03:
1412 ------------------------
1413 (Array will have been allocated
1414 Numparts_available by 9 long)
1416 There are two ways to do this:
1417 ------------------------------
1418 1. The simple one, without ranges.
1420 This is good for all structured models
1421 that will NOT be used in EnSight's
1422 Server of Servers
1424 Simply provide the ijk dimensions in the
1425 first three slots and place a -1 in
1426 the 4th slot. (The remaining slots will
1427 be ignored).
1429 Thus,
1430 ijk_dimensions[][0] = I dimension of block
1431 ijk_dimensions[][1] = J dimension of block
1432 ijk_dimensions[][2] = K dimension of block
1433 ijk_dimensions[][3] = -1
1435 (J planes)
1436 4 *-------*-------*
1437 | | | ijk_dimension[0][0] = 3
1438 | | | ijk_dimension[0][1] = 4
1439 | | | ijk_dimension[0][2] = 1
1440 3 *-------*-------*
1441 | | | ijk_dimension[0][4] = -1
1442 | | |
1443 | | |
1444 2 *-------*-------*
1445 | | |
1446 | | |
1447 | | |
1448 1 *-------*-------*
1449 1 2 3 (I planes)
1453 2. Using ranges.
1455 This one can be used anytime, but MUST
1456 be used if EnSight's Server of Servers
1457 is to be used!
1459 The first 3 slots contain the ijk dimension
1460 of the complete block (of which this may be
1461 a portion). The last 6 slots contain the
1462 ijk min and max ranges within the complete.
1464 Thus,
1465 ijk_dimensions[][0] = I dim of complete block
1466 ijk_dimensions[][1] = J dim of complete block
1467 ijk_dimensions[][2] = K dim of complete block
1469 ijk_dimensions[][3] = Imin of portion (1-based)
1470 ijk_dimensions[][4] = Imax of portion (1-based)
1471 ijk_dimensions[][5] = Jmin of portion (1-based)
1472 ijk_dimensions[][6] = Jmax of portion (1-based)
1473 ijk_dimensions[][7] = Kmin of portion (1-based)
1474 ijk_dimensions[][8] = Kmax of portion (1-based)
1477 example1: (Model has one part, a simple 2D block,
1478 and want whole thing)
1480 (J planes)
1481 4 *-------*-------*
1482 | | | ijk_dimension[0][0] = 3
1483 | | | ijk_dimension[0][1] = 4
1484 | | | ijk_dimension[0][2] = 1
1485 3 *-------*-------*
1486 | | | ijk_dimension[0][3] = 1
1487 | | | ijk_dimension[0][4] = 3
1488 | | | ijk_dimension[0][5] = 1
1489 2 *-------*-------* ijk_dimension[0][6] = 4
1490 | | | ijk_dimension[0][7] = 1
1491 | | | ijk_dimension[0][8] = 1
1492 | | |
1493 1 *-------*-------*
1494 1 2 3 (I planes)
1497 example2: (Want to have the block represented
1498 in two portions - 2 parts)
1500 (J planes) top portion
1501 4 *-------*-------*
1502 | | | ijk_dimension[0][0] = 3
1503 | | | ijk_dimension[0][1] = 4
1504 | | | ijk_dimension[0][2] = 1
1505 3 *-------*-------*
1506 . . . ijk_dimension[0][3] = 1
1507 . . . ijk_dimension[0][4] = 3
1508 . . . ijk_dimension[0][5] = 3
1509 2 ................. ijk_dimension[0][6] = 4
1510 . . . ijk_dimension[0][7] = 1
1511 . . . ijk_dimension[0][8] = 1
1512 . . .
1513 1 .................
1514 1 2 3 (I planes)
1517 (J planes) bottom portion
1518 4 .................
1519 . . . ijk_dimension[1][0] = 3
1520 . . . ijk_dimension[2][1] = 4
1521 . . . ijk_dimension[3][2] = 1
1522 3 *-------*-------*
1523 | | | ijk_dimension[1][3] = 1
1524 | | | ijk_dimension[1][4] = 3
1525 | | | ijk_dimension[1][5] = 1
1526 2 *-------*-------* ijk_dimension[1][6] = 3
1527 | | | ijk_dimension[1][7] = 1
1528 | | | ijk_dimension[1][8] = 1
1529 | | |
1530 1 *-------*-------*
1531 1 2 3 (I planes)
1534 And note that if you were partioning this block for
1535 EnSight's Server of Servers, you would only have one part,
1536 instead of two. Each SOS server would return its appropriate
1537 ranges in the last 6 slots. The first 3 slots would remain constant.
1540 (OUT) iblanking_options = 2D array containing iblanking
1541 options possible for each
1542 structured model part.
1543 ----------
1544 (Ignored unless Z_IBLANKED type)
1546 (Array will have been allocated
1547 Numparts_available by 6 long)
1549 iblanking_options[][Z_EXT] = TRUE if external (outside)
1550 [][Z_INT] = TRUE if internal (inside)
1551 [][Z_BND] = TRUE if boundary
1552 [][Z_INTBND] = TRUE if internal boundary
1553 [][Z_SYM] = TRUE if symmetry surface
1556 Notes:
1557 -----
1558 * If you haven't built a table of pointers to the different parts,
1559 you might want to do so here as you gather the needed info.
1561 * Will be based on Current_time_step
1564 --------------------------------------------------------------------
1565 USERD_get_gold_variable_info
1567 Description:
1568 -----------
1569 Get the variable descriptions, types and filenames
1571 Specification:
1572 -------------
1573 int USERD_get_gold_variable_info(char **var_description,
1574 char **var_filename,
1575 int *var_type,
1576 int *var_classify,
1577 int *var_complex,
1578 char **var_ifilename,
1579 float *var_freq,
1580 int *var_contran,
1581 int *var_timeset)
1583 Returns:
1584 -------
1585 Z_OK if successful
1586 Z_ERR if not successful
1588 Arguments:
1589 ---------
1590 (OUT) var_description = Variable descriptions
1592 (Array will have been allocated
1593 Num_variables by Z_BUFL long)
1595 variable description restrictions:
1596 ----------------------------------
1597 1. Only first 19 characters used in EnSight.
1598 2. Leading and trailing whitespace will be removed by EnSight.
1599 3. Illegal characters will be replaced by underscores.
1600 4. Thay may not start with a numeric digit.
1601 4. No two variables may have the same description.
1604 (OUT) var_filename = Variable real filenames
1606 (Array will have been allocated
1607 Num_variables by Z_BUFL long)
1609 (OUT) var_type = Variable type
1611 (Array will have been allocated
1612 Num_variables long)
1614 types are: Z_CONSTANT
1615 Z_SCALAR
1616 Z_VECTOR
1617 Z_TENSOR
1618 Z_TENSOR9
1620 (OUT) var_classify = Variable classification
1622 (Array will have been allocated
1623 Num_variables long)
1625 types are: Z_PER_NODE
1626 Z_PER_ELEM
1628 (OUT) var_complex = TRUE if complex, FALSE otherwise
1630 (Array will have been allocated
1631 Num_variables long)
1633 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1635 (Array will have been allocated
1636 Num_variables by Z_BUFL long)
1638 (OUT) var_freq = complex frequency (if complex)
1640 (Array will have been allocated
1641 Num_variables long)
1643 (OUT) var_contran = TRUE if constant changes per time step
1644 FALSE if constant truly same at all time steps
1646 (Array will have been allocated
1647 Num_variables long)
1649 (OUT) var_timeset = Timeset the variable will use (1 based).
1650 (For static models, set it to 1)
1652 (Array will have been allocated
1653 Num_variables long)
1655 For example: If USERD_get_number_of_timesets
1656 returns 2, the valid
1657 timeset_number's would be 1 or 2
1660 Notes:
1661 -----
1662 * The implied variable numbers apply, but be aware that the
1663 arrays are zero based.
1664 So for variable 1, will need to provide var_description[0]
1665 var_filename[0]
1666 var_type[0]
1667 var_classify[0]
1668 var_complex[0]
1669 var_ifilename[0]
1670 var_freq[0]
1671 var_contran[0]
1672 var_timeset[0]
1675 for variable 2, will need to provide var_description[1]
1676 var_filename[1]
1677 var_type[1]
1678 var_classify[1]
1679 var_complex[1]
1680 var_ifilename[1]
1681 var_freq[1]
1682 var_contran[1]
1683 var_timeset[1]
1684 etc.
1689 --------------------------------------------------------------------
1690 USERD_get_ghosts_in_block_flag
1692 Description:
1693 -----------
1694 Gets whether ghost cells present in block or not
1696 Specification:
1697 -------------
1698 int USERD_get_ghosts_in_block_flag(int block_number)
1700 Returns:
1701 -------
1702 TRUE if any ghost cells in this structured part
1703 FALSE if no ghost cells in this structured part
1705 Arguments:
1706 ---------
1707 (IN) block_number = The block part number
1708 (1-based index of part table, namely:
1710 1 ... Numparts_available.
1712 It is NOT the part_id that
1713 is loaded in USERD_get_gold_part_build_info)
1715 Notes:
1716 -----
1717 * This routine is new in the 2.01 API
1718 * This will be based on Current_time_step
1720 * Intended for structured parts only, value will be ignored for
1721 unstructured parts
1725 --------------------------------------------------------------------
1726 USERD_get_ghosts_in_model_flag
1728 Description:
1729 -----------
1730 Answers the question as to whether any ghost cells in the model.
1732 Specification:
1733 -------------
1734 int USERD_get_ghosts_in_model_flag( void )
1736 Returns:
1737 -------
1738 TRUE if any ghost cells in the model
1739 FALSE if no ghost cells in the model
1741 Arguments:
1742 ---------
1744 Notes:
1745 -----
1746 * This routine is new in the 2.01 API
1748 -------------------------------------------------------------------------
1749 USERD_get_matf_set_info
1751 Description:
1752 -----------
1753 Get the material set ids and names
1755 Specification:
1756 -------------
1757 int USERD_get_matf_set_info(int *mat_set_ids,
1758 char **mat_set_name)
1760 Returns:
1761 -------
1762 Z_OK if successful
1763 Z_ERR if not successful
1765 Arguments:
1766 ---------
1767 (OUT) mat_set_ids = 1D material set ids array
1769 (Array will have been allocated
1770 Num_material_sets long)
1772 (OUT) mat_set_name = 2D material set name array
1774 (Array will have been allocated
1775 Num_material_sets by Z_BUFL long)
1777 Notes:
1778 -----
1779 * Will not be called if Num_material_sets is zero
1780 * See USERD_get_number_of_material_sets header for explanatory example
1783 --------------------------------------------------------------------
1784 USERD_get_matf_var_info
1786 Description:
1787 -----------
1788 Gets the material ids and descriptions for the material set
1790 Specification:
1791 -------------
1792 int USERD_get_matf_var_info(int set_index,
1793 int *mat_ids,
1794 char **mat_desc)
1796 Returns:
1797 -------
1798 Z_OK if successful
1799 Z_ERR if not successful
1801 Arguments:
1802 ---------
1803 (IN) set_index = the material set index (zero based)
1805 (OUT) mat_ids[set_index] = 1D integer array containing the material
1806 ids to associated with each material
1808 (Array will have been allocated
1809 Num_materials[set_index] long)
1811 (OUT) mat_desc[set_index] = 2D char array containing the material
1812 descriptions to associated with each material
1814 (Array will have been allocated
1815 Num_materials[set_index] by Z_BUFL long)
1817 Notes:
1818 -----
1819 * See USERD_get_number_of_material_sets header for explanatory example
1820 * Will not be called if Num_material_sets is zero, or
1821 Num_materials[set_index] is zero
1826 --------------------------------------------------------------------
1827 USERD_get_maxsize_info
1829 Description:
1830 -----------
1831 Gets maximum part sizes for efficient memory allocation.
1833 Transient models (especially those that increase in size) can cause
1834 reallocations, at time step changes, to keep chewing up more and
1835 more memory. The way to avoid this is to know what the maximum
1836 size of such memory will be, and allocate for this maximum initially.
1838 Accordingly, if you choose to provide this information (it is optional),
1839 EnSight will take advantage of it.
1842 Specification:
1843 -------------
1844 int USERD_get_maxsize_info(int *max_number_of_nodes,
1845 int *max_number_of_elements[Z_MAXTYPE],
1846 int *max_ijk_dimensions[3])
1848 Returns:
1849 -------
1850 Z_OK if supplying maximum data
1851 Z_ERR if not supplying maximum data, or some error occurred
1852 while trying to obtain it.
1854 Arguments:
1855 ---------
1856 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1857 in the part (over all time).
1859 (Array will have been allocated
1860 Numparts_available long)
1862 (OUT) max_number_of_elements = 2D array containing maximum number of
1863 each type of element for each
1864 unstructured model part (over all time).
1865 ------------
1866 Possible types are:
1868 Z_POINT = point
1869 Z_BAR02 = 2-noded bar
1870 Z_BAR03 = 3-noded bar
1871 Z_TRI03 = 3-noded triangle
1872 Z_TRI06 = 6-noded triangle
1873 Z_QUA04 = 4-noded quadrilateral
1874 Z_QUA08 = 8-noded quadrilateral
1875 Z_TET04 = 4-noded tetrahedron
1876 Z_TET10 = 10-noded tetrahedron
1877 Z_PYR05 = 5-noded pyramid
1878 Z_PYR13 = 13-noded pyramid
1879 Z_PEN06 = 6-noded pentahedron
1880 Z_PEN15 = 15-noded pentahedron
1881 Z_HEX08 = 8-noded hexahedron
1882 Z_HEX20 = 20-noded hexahedron
1884 Z_G_POINT = ghost node point element
1885 Z_G_BAR02 = 2 node ghost bar
1886 Z_G_BAR03 = 3 node ghost bar
1887 Z_G_TRI03 = 3 node ghost triangle
1888 Z_G_TRI06 = 6 node ghost triangle
1889 Z_G_QUA04 = 4 node ghost quad
1890 Z_G_QUA08 = 8 node ghost quad
1891 Z_G_TET04 = 4 node ghost tetrahedron
1892 Z_G_TET10 = 10 node ghost tetrahedron
1893 Z_G_PYR05 = 5 node ghost pyramid
1894 Z_G_PYR13 = 13 node ghost pyramid
1895 Z_G_PEN06 = 6 node ghost pentahedron
1896 Z_G_PEN15 = 15 node ghost pentahedron
1897 Z_G_HEX08 = 8 node ghost hexahedron
1898 Z_G_HEX20 = 20 node ghost hexahedron
1900 (Ignored unless Z_UNSTRUCTURED type)
1902 (Array will have been allocated
1903 Numparts_available by
1904 Z_MAXTYPE long)
1906 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1907 for each structured model part (over all time).
1908 ----------
1909 (Ignored if Z_UNSTRUCTURED type)
1911 (Array will have been allocated
1912 Numparts_available by 3 long)
1914 max_ijk_dimensions[][0] = maximum I dimension
1915 max_ijk_dimensions[][1] = maximum J dimension
1916 max_ijk_dimensions[][2] = maximum K dimension
1918 Notes:
1919 -----
1920 * You need to have first called USERD_get_number_of_model_parts and
1921 USERD_get_gold_part_build_info, so Numparts_available is known and
1922 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1923 or Z_IBLANKED) of each part.
1925 * This will NOT be based on Current_time_step - it is to be the maximum
1926 values over all time!!
1928 * This information is optional. If you return Z_ERR, Ensight will still
1929 process things fine, reallocating as needed, etc. However, for
1930 large transient models you will likely use considerably more memory
1931 and take more processing time for the memory reallocations. So, if it
1932 is possible to provide this information "up front", it is recommended
1933 to do so.
1936 --------------------------------------------------------------------
1937 USERD_get_model_extents
1939 Description:
1940 -----------
1941 Gets the model bounding box extents. If this routine supplys them
1942 EnSight will not have to spend time doing so. If this routine
1943 returns Z_ERR, EnSight will have to take the time to touch all the
1944 nodes and gather the extent info.
1946 Specification:
1947 -------------
1948 int USERD_get_model_extents(float extents[6])
1950 Returns:
1951 -------
1952 Z_OK if successful
1953 Z_ERR if not successful (whereupon EnSight will determine by reading
1954 all coords of all parts)
1956 Arguments:
1957 ---------
1958 (OUT) extents[0] = min x
1959 [1] = max x
1960 [2] = min y
1961 [3] = max y
1962 [4] = min z
1963 [5] = max z
1965 Notes:
1966 -----
1967 * This will be based on Current_time_step
1970 --------------------------------------------------------------------
1971 USERD_get_name_of_reader
1973 Description:
1974 -----------
1975 Gets the name of your user defined reader. The user interface will
1976 ask for this and include it in the available reader list.
1978 Specification:
1979 -------------
1980 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1981 int *two_fields)
1983 Returns:
1984 -------
1985 Z_OK if successful
1986 Z_ERR if not successful
1988 Arguments:
1989 ---------
1990 (OUT) reader_name = the name of the your reader or data format.
1991 (max length is Z_MAX_USERD_NAME, which is 20)
1993 (OUT) two_fields = FALSE if only one data field is
1994 required.
1995 TRUE if two data fields required
1997 -1 if one field (Geom) required
1998 and one field (Param) is optional
1999 Param field can contain any text
2000 for example a file name, modifiers,
2001 etc. that can be used to modify the
2002 reader's behavior.
2005 Notes:
2006 -----
2007 * Always called. Please be sure to provide a name for your custom
2008 reader format.
2010 --------------------------------------------------------------------
2011 USERD_get_nfaced_conn
2013 Description:
2014 -----------
2015 Gets the array containing the connectivity of nsided faces of nfaced elements
2017 Specification:
2018 -------------int
2019 int USERD_get_nfaced_conn(int part_number,
2020 int *nfaced_conn_array)
2022 Returns:
2023 -------
2024 Z_OK if successful
2025 Z_ERR if not successful
2027 Arguments:
2028 ---------
2029 (IN) part_number = the part number
2031 (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced
2032 elements
2034 (int array will have been allocated long enough to
2035 hold all the nsided face connectivities. Which is
2036 the sum of all the nodes per face values in the
2037 nfaced_npf_array of USERD_get_nfaced_nodes_per_face)
2039 Notes:
2040 -----
2041 * Will not be called unless there are some nfaced elements in the part
2043 * Providing nfaced information to Ensight:
2045 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2046 polyhedral elements in the part.
2048 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2049 the number of faces per nfaced element. (as if connectivity
2050 length of an nfaced element is one)
2052 3. In this routine, provide the streamed number of nodes per face
2053 for each of the faces of the nfaced elements.
2056 Simple example: 11 10 12
2057 +--------+-----+
2058 2 nfaced elements: /| |\ /|
2059 (1 7-faced / | | \ / |
2060 1 5-sided) / | | +9 |
2061 / | | /| |
2062 /7 | 8 / | |
2063 +-----------+/ | | |
2064 | |5 | |4 | |6
2065 | +-----|--+--|--+
2066 | / | \ | /
2067 | / | \|/3
2068 | / | +
2069 | / | /
2070 |/1 |2 /
2071 +-----------+/
2073 1. In USERD_get_gold_part_build_info:
2074 number_of_elements[Z_NFACED] = 2
2075 .
2076 /|\
2077 |
2078 2. In USERD_get_part_elements_by_type:
2079 length of conn_array will be: 2 x 1
2080 for element_type of Z_NFACED:
2081 conn_array[0][0] = 7 (for the 7-faced element)
2082 conn_array[1][0] = 5 (for the 5-faced element)
2084 ==
2085 Sum 12 <---------+
2086 |
2087 3. In USERD_get_faced_nodes_per_face: |
2088 length of nfaced_npf_array will be: 12
2090 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2091 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2092 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2093 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2094 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2095 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2096 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2098 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2099 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2100 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2101 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2102 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2104 ==
2105 Sum 48 <-------------+
2106 |
2107 4. In this function: |
2108 length of the nfaced_conn_array will be: 48
2110 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2111 nsided_conn_array[1] = 8
2112 nsided_conn_array[2] = 9
2113 nsided_conn_array[3] = 10
2114 nsided_conn_array[4] = 11
2116 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2117 nsided_conn_array[6] = 5
2118 nsided_conn_array[7] = 4
2119 nsided_conn_array[8] = 3
2120 nsided_conn_array[9] = 2
2122 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2123 nsided_conn_array[11] = 2
2124 nsided_conn_array[12] = 8
2125 nsided_conn_array[13] = 7
2127 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2128 nsided_conn_array[15] = 1
2129 nsided_conn_array[16] = 7
2130 nsided_conn_array[17] = 11
2132 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2133 nsided_conn_array[19] = 5
2134 nsided_conn_array[20] = 11
2135 nsided_conn_array[21] = 10
2137 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2138 nsided_conn_array[23] = 3
2139 nsided_conn_array[24] = 9
2140 nsided_conn_array[25] = 8
2142 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2143 nsided_conn_array[27] = 4
2144 nsided_conn_array[28] = 10
2145 nsided_conn_array[29] = 9
2147 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2148 nsided_conn_array[32] = 12
2149 nsided_conn_array[32] = 10
2151 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2152 nsided_conn_array[34] = 4
2153 nsided_conn_array[35] = 6
2155 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2156 nsided_conn_array[37] = 4
2157 nsided_conn_array[38] = 10
2158 nsided_conn_array[39] = 12
2160 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2161 nsided_conn_array[41] = 6
2162 nsided_conn_array[42] = 12
2163 nsided_conn_array[43] = 9
2165 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2166 nsided_conn_array[45] = 3
2167 nsided_conn_array[46] = 9
2168 nsided_conn_array[47] = 10
2172 --------------------------------------------------------------------
2173 USERD_get_nfaced_nodes_per_face -
2175 Description:
2176 -----------
2177 Gets the array containing the number of nodes per face for each face
2178 of the nfaced elements.
2180 Specification:
2181 -------------
2182 int USERD_get_nfaced_nodes_per_face(int part_number,
2183 int *nfaced_npf_array)
2185 Returns:
2186 -------
2187 Z_OK if successful
2188 Z_ERR if not successful
2190 Arguments:
2191 ---------
2192 (IN) part_number = the part number
2194 (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of
2195 nfaced elements
2197 (int array will have been allocated long enough
2198 to hold all the nodes_per_face values. Which is
2199 the sum of all the number of faces per element
2200 values in the conn_array of
2201 USERD_get_part_elements_by_type)
2203 Notes:
2204 -----
2205 * Will not be called unless there are some nfaced elements in the
2206 the part
2208 * Providing nfaced information to Ensight:
2210 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2211 polyhedral elements in the part.
2213 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2214 the number of faces per nfaced element. (as if connectivity
2215 length of an nfaced element is one)
2217 3. In this routine, provide the streamed number of nodes per face
2218 for each of the faces of the nfaced elements.
2221 Simple example: 11 10 12
2222 +--------+-----+
2223 2 nfaced elements: /| |\ /|
2224 (1 7-faced / | | \ / |
2225 1 5-sided) / | | +9 |
2226 / | | /| |
2227 /7 | 8 / | |
2228 +-----------+/ | | |
2229 | |5 | |4 | |6
2230 | +-----|--+--|--+
2231 | / | \ | /
2232 | / | \|/3
2233 | / | +
2234 | / | /
2235 |/1 |2 /
2236 +-----------+/
2238 1. In USERD_get_gold_part_build_info:
2239 number_of_elements[Z_NFACED] = 2
2240 .
2241 /|\
2242 |
2243 2. In USERD_get_part_elements_by_type:
2244 length of conn_array will be: 2 x 1
2245 for element_type of Z_NFACED:
2246 conn_array[0][0] = 7 (for the 7-faced element)
2247 conn_array[1][0] = 5 (for the 5-faced element)
2249 ==
2250 Sum 12 <---------+
2251 |
2252 3. In this routine: |
2253 length of nfaced_npf_array will be: 12
2255 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2256 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2257 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2258 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2259 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2260 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2261 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2263 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2264 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2265 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2266 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2267 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2269 ==
2270 Sum 48 <-------------+
2271 |
2272 4. In USERD_get_nfaced_conn: |
2273 length of the nfaced_conn_array will be: 48
2275 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2276 nsided_conn_array[1] = 8
2277 nsided_conn_array[2] = 9
2278 nsided_conn_array[3] = 10
2279 nsided_conn_array[4] = 11
2281 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2282 nsided_conn_array[6] = 5
2283 nsided_conn_array[7] = 4
2284 nsided_conn_array[8] = 3
2285 nsided_conn_array[9] = 2
2287 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2288 nsided_conn_array[11] = 2
2289 nsided_conn_array[12] = 8
2290 nsided_conn_array[13] = 7
2292 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2293 nsided_conn_array[15] = 1
2294 nsided_conn_array[16] = 7
2295 nsided_conn_array[17] = 11
2297 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2298 nsided_conn_array[19] = 5
2299 nsided_conn_array[20] = 11
2300 nsided_conn_array[21] = 10
2302 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2303 nsided_conn_array[23] = 3
2304 nsided_conn_array[24] = 9
2305 nsided_conn_array[25] = 8
2307 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2308 nsided_conn_array[27] = 4
2309 nsided_conn_array[28] = 10
2310 nsided_conn_array[29] = 9
2312 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2313 nsided_conn_array[32] = 12
2314 nsided_conn_array[32] = 10
2316 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2317 nsided_conn_array[34] = 4
2318 nsided_conn_array[35] = 6
2320 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2321 nsided_conn_array[37] = 4
2322 nsided_conn_array[38] = 10
2323 nsided_conn_array[39] = 12
2325 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2326 nsided_conn_array[41] = 6
2327 nsided_conn_array[42] = 12
2328 nsided_conn_array[43] = 9
2330 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2331 nsided_conn_array[45] = 3
2332 nsided_conn_array[46] = 9
2333 nsided_conn_array[47] = 10
2338 --------------------------------------------------------------------
2339 USERD_get_node_label_status
2341 Description:
2342 -----------
2343 Answers the question as to whether node labels will be provided.
2345 Specification:
2346 -------------
2347 int USERD_get_node_label_status( void )
2349 Returns:
2350 -------
2351 TRUE if node labels will be provided
2352 FALSE if node labels will NOT be provided
2354 Arguments:
2355 ---------
2356 none
2358 Notes:
2359 -----
2360 * Node ids are needed in order to do any node querying, or node
2361 labeling on-screen within EnSight.
2363 * Prior to API 2.01:
2364 -----------------
2365 For unstructured parts, you can read them from your file if
2366 available, or can assign them, etc. They need to be unique
2367 per part, and are often unique per model. They must also be
2368 positive numbers greater than zero.
2370 USERD_get_part_node_ids is used to obtain the ids, if the
2371 status returned here is TRUE.
2373 (Unlike API 1.0, where the connectivity of elements had to be
2374 according to the node ids - API 2.0's element connectivities
2375 are not affected either way by the status here.)
2377 For structured parts, EnSight will assign ids if you return a
2378 status of TRUE here. You cannot assign them yourself!!
2380 * Starting at API 2.01:
2381 --------------------
2382 For both unstructured and structured parts, you can read them
2383 from your file if available, or can assign them, etc. They need
2384 to be unique per part, and are often unique per model. They must
2385 also be positive numbers greater than zero.
2387 USERD_get_part_node_ids is used to obtain the ids, if the
2388 status returned here is TRUE.
2390 * Will call USERD_get_part_node_ids for each part if this routine
2391 returns TRUE.
2393 --------------------------------------------------------------------
2394 USERD_get_nsided_conn -
2396 Description:
2397 -----------
2398 Gets the array containing the connectivity of nsided elements
2400 Specification:
2401 -------------
2402 int USERD_get_nsided_conn(int part_number,
2403 int *nsided_conn_array)
2405 Returns:
2406 -------
2407 Z_OK if successful
2408 Z_ERR if not successful
2410 Arguments:
2411 ---------
2412 (IN) part_number = the part number
2414 (OUT) nsided_conn_array = 1D array of nsided connectivies
2416 (int array will have been allocated long enough
2417 to hold all the nsided connectivities. Which is
2418 the sum of all the nodes_per_element values in
2419 the conn_array of USERD_get_part_elements_by_type)
2422 Notes:
2423 -----
2424 * Will not be called unless there are some nsided elements in the the part.
2426 * Providing nsided information to Ensight:
2428 1. In USERD_get_gold_part_build_info, provide the number of nsided
2429 elements in the part.
2431 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2432 the number of nodes per nsided element. (as if connectivity
2433 length of an nsided element is one)
2435 3. In this routine, provide the streamed connectivities for each of the
2436 nsided elements.
2439 Simple example: 5 6
2440 +--------+
2441 3 nsided elements: /| \
2442 (1 4-sided / | \
2443 1 3-sided / | \
2444 1 7-sided) / | \ 7
2445 /3 |4 +
2446 +-----+ |
2447 | | |
2448 | | |8
2449 | | +
2450 | | /
2451 | | /
2452 | | /
2453 |1 |2 /9
2454 +-----+--------+
2456 1. In USERD_get_gold_part_build_info:
2457 number_of_elements[Z_NSIDED] = 3
2458 .
2459 /|\
2460 |
2461 2. In USERD_get_part_elements_by_type:
2462 length of conn_array will be: 3 x 1
2464 for element_type of Z_NSIDED:
2465 conn_array[0][0] = 4 (for the 4-sided element)
2466 conn_array[1][0] = 3 (for the 3-sided element)
2467 conn_array[2][0] = 7 (for the 7-sided element)
2469 Sum ===
2470 14 <---------+
2471 |
2472 3. In this routine: |
2473 length of nsided_conn_array will be: 14
2475 nsided_conn_array[0] = 1 (connectivity of 4-sided element)
2476 nsided_conn_array[1] = 2
2477 nsided_conn_array[2] = 4
2478 nsided_conn_array[3] = 3
2480 nsided_conn_array[4] = 3 (connectivity of 3-sided element)
2481 nsided_conn_array[5] = 4
2482 nsided_conn_array[6] = 5
2484 nsided_conn_array[7] = 2 (connectivity of 7-sided element)
2485 nsided_conn_array[8] = 9
2486 nsided_conn_array[9] = 8
2487 nsided_conn_array[10] = 7
2488 nsided_conn_array[11] = 6
2489 nsided_conn_array[12] = 5
2490 nsided_conn_array[13] = 4
2495 --------------------------------------------------------------------
2496 USERD_get_num_of_time_steps
2498 Description:
2499 -----------
2500 Gets the number of time steps of data available for desired timeset.
2502 Specification:
2503 -------------
2504 int USERD_get_num_of_time_steps( int timeset_number )
2506 Returns:
2507 -------
2508 Number of time steps in timeset (>0 if okay, <=0 if problems).
2510 Arguments:
2511 ---------
2512 (IN) timeset number = the timeset number
2514 For example: If USERD_get_number_of_timesets
2515 returns 2, the valid
2516 timeset_number's would be 1 and 2
2518 Notes:
2519 -----
2520 * This should be >= 1 1 indicates a static model
2521 >1 indicates a transient model
2523 * Num_time_steps[timeset_number] would be set here
2527 --------------------------------------------------------------------
2528 USERD_get_number_of_files_in_dataset
2530 Description:
2531 -----------
2532 Get the total number of files in the dataset. Used for the
2533 dataset query option within EnSight.
2535 Specification:
2536 -------------
2537 int USERD_get_number_of_files_in_dataset( void )
2539 Returns:
2540 -------
2541 The total number of files in the dataset.
2543 Arguments:
2544 ---------
2545 none
2547 Notes:
2548 -----
2549 * You can be as complete as you want about this. If you don't
2550 care about the dataset query option, return a value of 0
2551 If you only want certain files, you can just include them. But,
2552 you will need to supply the info in USERD_get_dataset_query_file_info
2553 for each file you include here.
2555 * Num_dataset_files would be set here
2558 --------------------------------------------------------------------
2559 USERD_get_number_of_material_sets -
2561 Description:
2562 -----------
2563 Get the number of material sets in the model
2565 Specification:
2566 -------------
2567 int USERD_get_number_of_material_sets( void )
2570 Returns:
2571 -------
2572 Num_material_sets = number of material sets
2573 (Zero would indicate that you have no materials
2574 to deal with in the model)
2576 or
2578 -1 if an error condition
2580 Arguments:
2581 ---------
2582 none
2584 Notes:
2585 -----
2586 * You may want to keep this as a global for use in other routines.
2588 ###############################################################
2589 NOTE: For EnSight 7.6, only one material set is supported
2590 within EnSight.
2591 Thus the only valid returns here are:
2592 0 (no materials)
2593 1 (for the one material set allowed)
2594 or -1 (if an error)
2596 If the casefile has more than this, this reader will
2597 read them, but EnSight will issue an error message and
2598 choke on them!
2599 ###############################################################
2601 ================================================================
2602 A very simple explanatory example, to use as a reference for the
2603 materials routines:
2605 Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
2606 Most of the model is material 1, but the top left corner is material 9 -
2607 basically as shown:
2610 *--------*--------*--------*
2611 | | / | |
2612 | Mat 9 / | |
2613 | | / | |
2614 | |/ | |
2615 | e7 / e8 | e9 |
2616 | /| | |
2617 | / | | |
2618 | / | | |
2619 *----/---*--------*--------*
2620 | / | | |
2621 | / | | |
2622 | / | Mat 1 |
2623 |/ | | |
2624 | e4 | e5 | e6 |
2625 | | | |
2626 | | | |
2627 | | | |
2628 *--------*--------*--------*
2629 | | | |
2630 | | | |
2631 | | | |
2632 | | | |
2633 | e1 | e2 | e3 |
2634 | | | |
2635 | | | |
2636 | | | |
2637 *--------*--------*--------*
2640 Thus, in this routine, set:
2641 Num_material_sets = 1
2643 In USERD_get_matf_set_info, set:
2644 mat_set_ids[0] = 1
2645 mat_set_name[0] = "Material Set 1" (or whatever name desired)
2647 In USERD_get_number_of_materials, input would be set_index = 0, and
2648 would need to set:
2649 Num_materials[0] = 2
2651 For simplicity, the ids and descriptions that would be returned in
2652 USERD_get_matf_var_info could be:
2653 mat_ids[0] = 1
2654 mat_ids[1] = 9
2655 mat_desc[0] = "mat 1" (or whatever desired)
2656 mat_desc[2] = "mat 9"
2658 The per element material ids list would need to be:
2660 material ids:
2661 -------------
2662 ids_list[0] = 1 (material id 1, for elem e1)
2663 ids_list[1] = 1 ( " e2)
2664 ids_list[2] = 1 ( " e3)
2665 ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
2666 ids_list[5] = 1 (material id 1, for elem e5)
2667 ids_list[5] = 1 ( " e6)
2668 ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
2669 ids_list[5] = -9 ( " e8)
2670 ids_list[5] = 1 (material id 1, for elem e9)
2672 Finally we need the mixed material ids list and the mixed materials values list,
2673 which would need to be:
2675 mixed-material ids:
2676 -------------------
2677 ==> 1 ids_list[0] = 2 (the -1 in the material variable points here,
2678 2 indicates that two materials are present)
2679 2 ids_list[1] = 1 (1st material is 1)
2680 3 ids_list[2] = 9 (2nd material is 9)
2681 4 ids_list[3] = -1 (negative of index into mixed-material val_list)
2682 ==> 5 ids_list[4] = 2 (the -5 in the material variable points here,
2683 2 indicates that two materials are present)
2684 6 ids_list[5] = 1 (1st material is 1)
2685 7 ids_list[6] = 9 (2nd material is 9)
2686 8 ids_list[7] = -3 (negative of index into mixed-material val_list)
2687 ==> 9 ids_list[8] = 2 etc.
2688 10 ids_list[9] = 1
2689 11 ids_list[10] = 9
2690 12 ids_list[11] = -5
2692 mixed-material values:
2693 ----------------------
2694 ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here,
2695 and this is the value for material 1)
2696 2 val_list[1] = 0.125 (the value for material 9)
2697 ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
2698 4 val_list[3] = 0.875
2699 ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
2700 6 val_list[5] = 0.125
2702 So, USERD_size_matf_data would need to return
2703 matf_size = 8, when called with set_id = 1
2704 part_id = 1
2705 wtyp = Z_QUA04
2706 mat_type = Z_MAT_INDEX
2708 matf_size = 12, when called with set_id = 1
2709 part_id = 1
2710 mat_type = Z_MIX_INDEX
2712 = 6, when called with set_id = 1
2713 part_id = 1
2714 mat_type = Z_MIX_VALUE
2716 And, USERD_load_matf_data would need to return:
2717 the int array ids_list as shown above when called with:
2718 set_id = 1
2719 part_id = 1
2720 wtyp = Z_QUA04
2721 mat_type = Z_MAT_INDEX (indicating id list).
2723 the int array ids_list as shown above when called with:
2724 set_id = 1
2725 part_id = 1
2726 mat_type = Z_MIX_INDEX (indicating id list).
2728 the float array val_list as shown above when called with:
2729 set_id = 1
2730 part_id = 1
2731 mat_type = Z_MIX_VALUE (indicating val list).
2734 -------------------------------------------------------------------------
2735 USERD_get_number_of_materials
2737 Description:
2738 -----------
2739 Gets the number of materials in the material set
2741 Specification:
2742 -------------
2743 int USERD_get_number_of_materials( int set_index )
2745 Returns:
2746 -------
2747 Num_materials[set_index] = Number of materials in the set
2748 0 indicates no materials information present
2749 -1 indicates an error
2750 Arguments:
2751 ---------
2752 (IN) set_index = the material set index (zero based)
2754 Notes:
2755 -----
2756 * See USERD_get_number_of_material_sets header for explanatory example
2757 * Will not be called if Num_material_sets is zero
2758 * You may want to keep this as a global for use in other routines.
2762 --------------------------------------------------------------------
2763 USERD_get_number_of_model_parts
2765 Description:
2766 -----------
2767 Gets the total number of unstructured and structured parts
2768 in the model, for which you can supply information.
2770 Specification:
2771 -------------
2772 int USERD_get_number_of_model_parts( void )
2774 Returns:
2775 -------
2776 Number of parts (>0 if okay, <=0 if problems).
2778 Arguments:
2779 ---------
2780 none
2782 Notes:
2783 -----
2784 * If going to have to read down through the parts in order to
2785 know how many, you may want to build a table of pointers to
2786 the various parts, so you can easily get to particular parts in
2787 later processes. If you can simply read the number of parts
2788 at the head of the file, then you would probably not build the
2789 table at this time.
2791 * This routine would set Numparts_available, which is equal to
2792 Num_unstructured_parts + Num_structured_blocks.
2796 --------------------------------------------------------------------
2797 USERD_get_number_of_timesets
2799 Description:
2800 -----------
2801 Gets the number of timesets used in the model.
2803 Specification:
2804 -------------
2805 int USERD_get_number_of_timesets( void )
2807 Returns:
2808 -------
2809 Number of timesets in the model
2811 Arguments:
2812 ---------
2813 none
2815 Notes:
2816 -----
2817 * Num_timesets would be set here
2819 * If you have a static model, both geometry and variables, you should
2820 return a value of zero.
2822 * If you have a transient model, then you should return one or more.
2824 For example:
2826 Geometry Variables No. of timesets
2827 --------- ------------------------------ ---------------
2828 static static 0
2829 static transient, all using same timeset 1
2831 transient transient, all using same timeset as geom 1
2833 static transient, using 3 different timesets 3
2835 transient transient, using 3 different timesets and
2836 none of them the same as the
2837 geometry timeset 4
2838 etc.
2840 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
2841 the timeset number to use
2842 for geometry in:
2843 USERD_get_geom_timeset_number
2845 Variables can use the same timeset as the geometry, or can use
2846 other timesets. More than one variable can use the same timeset.
2848 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
2849 variable 1 provided at these same five steps
2850 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
2852 This routine should return a value of 2, because only
2853 two different timesets are needed. Timeset 1 would be for the
2854 geometry and variable 1 (they both use it). Timeset 2 would
2855 be for variable 2, which needs its own in this case.
2861 --------------------------------------------------------------------
2862 USERD_get_number_of_variables
2864 Description:
2865 -----------
2866 Get the number of variables for which you will be providing info.
2868 Specification:
2869 -------------
2870 int USERD_get_number_of_variables( void )
2872 Returns:
2873 -------
2874 Number of variables (includes constant, scalar, vector and tensor types)
2875 (>=0 if okay, <0 if problem)
2877 Arguments:
2878 ---------
2879 none
2881 Notes:
2882 -----
2883 *****************************************************************
2884 * Variable numbers, by which references will be made, are implied
2885 here. If you say there are 3 variables, the variable numbers
2886 will be 1, 2, and 3.
2887 *****************************************************************
2889 * Num_variables would be set here
2893 --------------------------------------------------------------------
2894 USERD_get_part_coords
2896 Description:
2897 -----------
2898 Gets the coordinates for an unstructured part.
2900 Specification:
2901 -------------
2902 int USERD_get_part_coords(int part_number, float **coord_array)
2904 Returns:
2905 -------
2906 Z_OK if successful
2907 Z_ERR if not successful
2909 Arguments:
2910 ---------
2911 (IN) part_number = The part number
2912 (1-based index of part table, namely:
2914 1 ... Numparts_available.
2916 It is NOT the part_id that
2917 is loaded in USERD_get_gold_part_build_info)
2919 (OUT) coord_array = 2D float array which contains,
2920 x,y,z coordinates of each node
2921 in the part.
2923 (IMPORTANT: The second dimension of this aray is 1-based!!!)
2925 (Array will have been allocated
2926 3 by (number_of_nodes + 1) for the part
2927 long - see USERD_get_gold_part_build_info)
2930 ex) If number_of_nodes = 100
2931 as obtained in:
2932 USERD_get_gold_part_build_info
2934 Then the allocated dimensions of the
2935 pointer sent to this routine will be:
2936 coord_array[3][101]
2938 Ignore the coord_array[0][0]
2939 coord_array[1][0]
2940 coord_array[2][0] locations and start
2941 the node coordinates at:
2942 coord_array[0][1]
2943 coord_array[1][1]
2944 coord_array[2][1]
2946 coord_array[0][2]
2947 coord_array[1][2]
2948 coord_array[2][2]
2950 etc.
2952 Notes:
2953 -----
2954 * Not called unless Num_unstructured_parts is > 0
2956 * Will be based on Current_time_step
2959 --------------------------------------------------------------------
2960 USERD_get_part_element_ids_by_type
2962 Description:
2963 -----------
2964 Gets the ids for the elements of a particular type for an unstructured
2965 or structured part.
2967 Specification:
2968 -------------
2969 int USERD_get_part_element_ids_by_type(int part_number,
2970 int element_type,
2971 int *elemid_array)
2973 Returns:
2974 -------
2975 Z_OK if successful
2976 Z_ERR if not successful
2978 Arguments:
2979 ---------
2980 (IN) part_number = The part number
2981 (1-based index of part table, namely:
2983 1 ... Numparts_available.
2985 It is NOT the part_id that
2986 is loaded in USERD_get_gold_part_build_info)
2988 (IN) element_type = One of the following (See global_extern.h)
2989 Z_POINT node point element
2990 Z_BAR02 2 node bar
2991 Z_BAR03 3 node bar
2992 Z_TRI03 3 node triangle
2993 Z_TRI06 6 node triangle
2994 Z_QUA04 4 node quad
2995 Z_QUA08 8 node quad
2996 Z_TET04 4 node tetrahedron
2997 Z_TET10 10 node tetrahedron
2998 Z_PYR05 5 node pyramid
2999 Z_PYR13 13 node pyramid
3000 Z_PEN06 6 node pentahedron
3001 Z_PEN15 15 node pentahedron
3002 Z_HEX08 8 node hexahedron
3003 Z_HEX20 20 node hexahedron
3005 Z_G_POINT ghost node point element
3006 Z_G_BAR02 2 node ghost bar
3007 Z_G_BAR03 3 node ghost bar
3008 Z_G_TRI03 3 node ghost triangle
3009 Z_G_TRI06 6 node ghost triangle
3010 Z_G_QUA04 4 node ghost quad
3011 Z_G_QUA08 8 node ghost quad
3012 Z_G_TET04 4 node ghost tetrahedron
3013 Z_G_TET10 10 node ghost tetrahedron
3014 Z_G_PYR05 5 node ghost pyramid
3015 Z_G_PYR13 13 node ghost pyramid
3016 Z_G_PEN06 6 node ghost pentahedron
3017 Z_G_PEN15 15 node ghost pentahedron
3018 Z_G_HEX08 8 node ghost hexahedron
3019 Z_G_HEX20 20 node ghost hexahedron
3021 (OUT) elemid_array = 1D array containing id of each
3022 element of the type.
3024 (Array will have been allocated
3025 number_of_elements of the type long)
3027 ex) If number_of_elements[Z_TRI03] = 25
3028 number_of_elements[Z_QUA04] = 100
3029 number_of_elements[Z_HEX08] = 30
3030 as obtained in:
3031 USERD_get_gold_part_build_info
3033 Then the allocated dimensions available
3034 for this routine will be:
3035 conn_array[25] when called with Z_TRI03
3037 conn_array[100] when called with Z_QUA04
3039 conn_array[30] when called with Z_HEX08
3041 Notes:
3042 -----
3043 * Not called unless element label status is set to TRUE in
3044 USERD_get_element_label_status
3046 * Will be based on Current_time_step
3050 --------------------------------------------------------------------
3051 USERD_get_part_elements_by_type
3053 Description:
3054 -----------
3055 Gets the connectivities for the elements of a particular type in an
3056 unstructured part
3058 Specification:
3059 -------------
3060 int USERD_get_part_elements_by_type(int part_number,
3061 int element_type,
3062 int **conn_array)
3064 Returns:
3065 -------
3066 Z_OK if successful
3067 Z_ERR if not successful
3069 Arguments:
3070 ---------
3071 (IN) part_number = The part number
3072 (1-based index of part table, namely:
3074 1 ... Numparts_available.
3076 It is NOT the part_id that
3077 is loaded in USERD_get_gold_part_build_info)
3079 (IN) element_type = One of the following (See global_extern.h)
3080 Z_POINT node point element
3081 Z_BAR02 2 node bar
3082 Z_BAR03 3 node bar
3083 Z_TRI03 3 node triangle
3084 Z_TRI06 6 node triangle
3085 Z_QUA04 4 node quad
3086 Z_QUA08 8 node quad
3087 Z_TET04 4 node tetrahedron
3088 Z_TET10 10 node tetrahedron
3089 Z_PYR05 5 node pyramid
3090 Z_PYR13 13 node pyramid
3091 Z_PEN06 6 node pentahedron
3092 Z_PEN15 15 node pentahedron
3093 Z_HEX08 8 node hexahedron
3094 Z_HEX20 20 node hexahedron
3096 Z_G_POINT ghost node point element
3097 Z_G_BAR02 2 node ghost bar
3098 Z_G_BAR03 3 node ghost bar
3099 Z_G_TRI03 3 node ghost triangle
3100 Z_G_TRI06 6 node ghost triangle
3101 Z_G_QUA04 4 node ghost quad
3102 Z_G_QUA08 8 node ghost quad
3103 Z_G_TET04 4 node ghost tetrahedron
3104 Z_G_TET10 10 node ghost tetrahedron
3105 Z_G_PYR05 5 node ghost pyramid
3106 Z_G_PYR13 13 node ghost pyramid
3107 Z_G_PEN06 6 node ghost pentahedron
3108 Z_G_PEN15 15 node ghost pentahedron
3109 Z_G_HEX08 8 node ghost hexahedron
3110 Z_G_HEX20 20 node ghost hexahedron
3113 (OUT) conn_array = 2D array containing connectivity
3114 of each element of the type.
3116 (Array will have been allocated
3117 num_of_elements of the type by
3118 connectivity length of the type)
3120 ex) If number_of_elements[Z_TRI03] = 25
3121 number_of_elements[Z_QUA04] = 100
3122 number_of_elements[Z_HEX08] = 30
3123 as obtained in:
3124 USERD_get_gold_part_build_info
3126 Then the allocated dimensions available
3127 for this routine will be:
3128 conn_array[25][3] when called with Z_TRI03
3130 conn_array[100][4] when called with Z_QUA04
3132 conn_array[30][8] when called with Z_HEX08
3134 Notes:
3135 -----
3136 * Not called unless Num_unstructured_parts is > 0
3138 * Will be based on Current_time_step
3141 --------------------------------------------------------------------
3142 USERD_get_part_node_ids
3144 Description:
3145 -----------
3146 Gets the node ids of an unstructured or structured part.
3148 Specification:
3149 -------------
3150 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
3152 Returns:
3153 -------
3154 Z_OK if successful
3155 Z_ERR if not successful
3157 Arguments:
3158 ---------
3159 (IN) part_number = The part number
3160 (1-based index of part table, namely:
3162 1 ... Numparts_available.
3164 It is NOT the part_id that
3165 is loaded in USERD_get_gold_part_build_info)
3167 (OUT) nodeid_array = 1D array containing node ids of
3168 each node in the part.
3170 (IMPORTANT: This array is 1-based!!!)
3172 (Array will have been allocated
3173 (number_of_nodes + 1) for the part long
3174 see USERD_get_gold_part_build_info)
3176 ex) If number_of_nodes = 100
3177 as obtained in:
3178 USERD_get_gold_part_build_info
3180 Then the allocated dimensions of the
3181 pointer sent to this routine will be:
3182 nodeid_array[101]
3184 Ignore the nodeid_array[0] location and start
3185 the node ids at:
3186 nodeid_array[1]
3188 nodeid_array[2]
3190 etc.
3192 Notes:
3193 -----
3194 * Not called unless node label status is TRUE, as returned from
3195 USERD_get_node_label_status
3197 * Will be based on Current_time_step
3199 * The ids are purely labels, used when displaying or querying node ids.
3200 However, any node id < 0 will never be displayed
3203 --------------------------------------------------------------------
3204 USERD_get_reader_descrip
3206 Description:
3207 -----------
3208 Gets the description of the reader, so gui can give more info
3210 Specification:
3211 -------------
3212 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
3214 Returns:
3215 -------
3216 Z_OK if successful
3217 Z_ERR if not successful
3219 Arguments:
3220 ---------
3221 (OUT) descrip = the description of the reader (max length is MAXFILENP,
3222 which is 255)
3224 Notes:
3225 -----
3226 * OPTIONAL ROUTINE! You can have it or not.
3230 --------------------------------------------------------------------
3231 USERD_get_reader_version
3233 Description:
3234 -----------
3235 Gets the version number of the user defined reader
3237 Specification:
3238 -------------
3239 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
3241 Returns:
3242 -------
3243 Z_OK if successful
3244 Z_ERR if not successful (and will assume is version 1.0)
3246 Arguments:
3247 ---------
3248 (OUT) version_number = the version number of the reader
3249 (max length is Z_MAX_USERD_NAME, which
3250 is 20)
3252 Notes:
3253 -----
3254 * This needs to be "2.000" or greater. Otherwise EnSight will assume
3255 this reader is API 1.0
3257 * should set it to "2.010" for this version of the API
3262 --------------------------------------------------------------------
3263 USERD_get_sol_times
3265 Description:
3266 -----------
3267 Get the solution times associated with each time step for
3268 desired timeset.
3270 Specification:
3271 -------------
3272 int USERD_get_sol_times(int timeset_number,
3273 float *solution_times)
3275 Returns:
3276 -------
3277 Z_OK if successful
3278 Z_ERR if not successful
3280 Arguments:
3281 ---------
3282 (IN) timeset_number = the timeset number
3284 For example: If USERD_get_number_of_timesets
3285 returns 2, the valid
3286 timeset_number's would be 1 and 2
3288 (OUT) solution_times = 1D array of solution times per time step
3290 (Array will have been allocated
3291 Num_time_steps[timeset_number] long)
3293 Notes:
3294 -----
3295 * The solution times must be non-negative and increasing.
3299 --------------------------------------------------------------------
3300 USERD_get_timeset_description -
3302 Description:
3303 -----------
3304 Get the description to associate with the desired timeset.
3306 Specification:
3307 -------------
3308 int USERD_get_timeset_description(int timeset_number,
3309 char timeset_description[Z_BUFL])
3311 Returns:
3312 -------
3313 Z_OK if successful
3314 Z_ERR if not successful
3316 Arguments:
3317 ---------
3318 (IN) timeset_number = the timeset number
3320 For example: If USERD_get_number_of_timesets
3321 returns 2, the valid
3322 timeset_number's would be 1 and 2
3324 (OUT) timeset_description = timeset description string
3327 Notes:
3328 -----
3329 * A string of NULLs is valid for timeset_description
3334 --------------------------------------------------------------------
3335 USERD_get_var_by_component
3337 Description:
3338 -----------
3339 Gets the values of a variable component. Both unstructured and structured
3340 parts use this routine.
3342 if Z_PER_NODE:
3343 Get the component value at each node for a given variable in the part.
3345 or if Z_PER_ELEM:
3346 Get the component value at each element of a specific part and type
3347 for a given variable.
3349 Specification:
3350 -------------
3351 int USERD_get_var_by_component(int which_variable,
3352 int which_part,
3353 int var_type,
3354 int which_type,
3355 int imag_data,
3356 int component,
3357 float *var_array)
3359 Returns:
3360 -------
3361 Z_OK if successful
3362 Z_ERR if not successful
3364 or: Z_UNDEF, in which case you need not load any values into var_array
3367 Arguments:
3368 ---------
3369 (IN) which_variable = The variable number
3371 (IN) which_part Since EnSight Version 7.4
3372 -------------------------
3373 = The part number
3375 (1-based index of part table, namely:
3377 1 ... Numparts_available.
3379 It is NOT the part_id that
3380 is loaded in USERD_get_gold_part_build_info)
3382 Prior to EnSight Version 7.4
3383 ----------------------------
3384 = The part id This is the part_id label loaded
3385 in USERD_get_gold_part_build_info.
3386 It is NOT the part table index.
3388 (IN) var_type = Z_SCALAR
3389 Z_VECTOR
3390 Z_TENSOR (symmetric tensor)
3391 Z_TENSOR9 (asymmetric tensor)
3393 (IN) which_type
3395 if Z_PER_NODE: Not used
3397 if Z_PER_ELEM: = The element type
3398 Z_POINT node point element
3399 Z_BAR02 2 node bar
3400 Z_BAR03 3 node bar
3401 Z_TRI03 3 node triangle
3402 Z_TRI06 6 node triangle
3403 Z_QUA04 4 node quad
3404 Z_QUA08 8 node quad
3405 Z_TET04 4 node tetrahedron
3406 Z_TET10 10 node tetrahedron
3407 Z_PYR05 5 node pyramid
3408 Z_PYR13 13 node pyramid
3409 Z_PEN06 6 node pentahedron
3410 Z_PEN15 15 node pentahedron
3411 Z_HEX08 8 node hexahedron
3412 Z_HEX20 20 node hexahedron
3414 Z_G_POINT ghost node point element
3415 Z_G_BAR02 2 node ghost bar
3416 Z_G_BAR03 3 node ghost bar
3417 Z_G_TRI03 3 node ghost triangle
3418 Z_G_TRI06 6 node ghost triangle
3419 Z_G_QUA04 4 node ghost quad
3420 Z_G_QUA08 8 node ghost quad
3421 Z_G_TET04 4 node ghost tetrahedron
3422 Z_G_TET10 10 node ghost tetrahedron
3423 Z_G_PYR05 5 node ghost pyramid
3424 Z_G_PYR13 13 node ghost pyramid
3425 Z_G_PEN06 6 node ghost pentahedron
3426 Z_G_PEN15 15 node ghost pentahedron
3427 Z_G_HEX08 8 node ghost hexahedron
3428 Z_G_HEX20 20 node ghost hexahedron
3430 (IN) imag_data = TRUE if imag component
3431 FALSE if real component
3433 (IN) component = The component: (0 if Z_SCALAR)
3434 (0 - 2 if Z_VECTOR)
3435 (0 - 5 if Z_TENSOR)
3436 (0 - 8 if Z_TENSOR9)
3438 * 6 Symmetric Indicies, 0:5 *
3439 * ---------------------------- *
3440 * | 11 12 13 | | 0 3 4 | *
3441 * | | | | *
3442 * T = | 22 23 | = | 1 5 | *
3443 * | | | | *
3444 * | 33 | | 2 | *
3447 * 9 General Indicies, 0:8 *
3448 * ---------------------------- *
3449 * | 11 12 13 | | 0 3 4 | *
3450 * | | | | *
3451 * T = | 21 22 23 | = | 6 1 5 | *
3452 * | | | | *
3453 * | 31 32 33 | | 7 8 2 | *
3455 (OUT) var_array
3457 -----------------------------------------------------------------------
3458 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
3459 -----------------------------------------------------------------------
3461 if Z_PER_NODE: = 1D array containing variable component value
3462 for each node.
3464 (Array will have been allocated
3465 (number_of_nodes + 1) long)
3467 Info stored in this fashion:
3468 var_array[0] = not used
3469 var_array[1] = var component for node 1 of part
3470 var_array[2] = var_component for node 2 of part
3471 var_array[3] = var_component for node 3 of part
3472 etc.
3474 if Z_PER_ELEM: = 1D array containing variable component
3475 value for each element of a particular
3476 part and type.
3478 (Array will have been allocated
3479 (number_of_elements[which_part][which_type] + 1)
3480 long. See USERD_get_gold_part_build_info)
3482 Info stored in this fashion:
3483 var_array[1] = var component for elem 1 (of part and type)
3484 var_array[2] = var component for elem 2 (of part and type)
3485 var_array[3] = var component for elem 3 (of part and type)
3486 etc.
3488 Notes:
3489 -----
3490 * Not called unless Num_variables is > 0
3492 * The per_node or per_elem classification must be obtainable from the
3493 variable number (a var_classify array needs to be retained)
3495 * Will be based on Current_time_step
3497 * If the variable is not defined for this part, simply return with a
3498 value of Z_UNDEF. EnSight will treat the variable as undefined for
3499 this part.
3502 --------------------------------------------------------------------
3503 USERD_get_var_value_at_specific
3505 Description:
3506 -----------
3507 if Z_PER_NODE:
3508 Get the value of a particular variable at a particular node in a
3509 particular part at a particular time.
3511 or if Z_PER_ELEM:
3512 Get the value of a particular variable at a particular element of
3513 a particular type in a particular part at a particular time.
3516 Specification:
3517 -------------
3518 int USERD_get_var_value_at_specific(int which_var,
3519 int which_node_or_elem,
3520 int which_part,
3521 int which_elem_type,
3522 int time_step,
3523 float values[3],
3524 int imag_data)
3526 Returns:
3527 -------
3528 Z_OK if successful
3529 Z_ERR if not successful
3531 Arguments:
3532 ---------
3533 (IN) which_var = The variable number
3535 (IN) which_node_or_elem
3537 If Z_PER_NODE:
3538 = The node number. This is not the id, but is
3539 the index of the global node
3540 list (1 based), or the block's
3541 node list (1 based).
3543 Thus, coord_array[1]
3544 coord_array[2]
3545 coord_array[3]
3546 . |
3547 . |which_node_or_elem index
3548 . ----
3551 If Z_PER_ELEM:
3552 = The element number. This is not the id, but is
3553 the element number index
3554 of the number_of_element array
3555 (see USERD_get_gold_part_build_info),
3556 or the block's element list (1 based).
3558 Thus, for which_part:
3559 conn_array[which_elem_type][0]
3560 conn_array[which_elem_type][1]
3561 conn_array[which_elem_type][2]
3562 . |
3563 . which_node_or_elem index
3564 . ----
3567 (IN) which_part Since EnSight Version 7.4
3568 -------------------------
3569 = The part number
3571 (1-based index of part table, namely:
3573 1 ... Numparts_available.
3575 It is NOT the part_id that
3576 is loaded in USERD_get_gold_part_build_info)
3578 Prior to EnSight Version 7.4
3579 ----------------------------
3580 = The part id This is the part_id label loaded
3581 in USERD_get_gold_part_build_info.
3582 It is NOT the part table index.
3585 (IN) which_elem_type
3587 If Z_PER_NODE, or block part:
3588 = Not used
3590 If Z_PER_ELEM:
3591 = The element type. This is the element type index
3592 of the number_of_element array
3593 (see USERD_get_gold_part_build_info)
3595 (IN) time_step = The time step
3597 (IN) imag_data = TRUE if want imaginary value.
3598 FALSE if want real value.
3600 (OUT) values = scalar or vector component value(s)
3601 values[0] = scalar or vector[0]
3602 values[1] = vector[1]
3603 values[2] = vector[2]
3606 Notes:
3607 -----
3608 * This routine is used in node querys over time (or element querys over
3609 time for Z_PER_ELEM variables). If these operations are not critical
3610 to you, this can be a dummy routine.
3612 * The per_node or per_elem classification must be obtainable from the
3613 variable number (a var_classify array needs to be retained)
3615 * The time step given is for the proper variable timeset.
3618 ----------------------------------------------------------------------
3619 USERD_load_matf_data
3621 Description:
3622 -----------
3623 Get the material id list, mixed-material id list, or
3624 mixed-material values list for the given material set and part (and
3625 element type if material id list)
3627 Specification:
3628 -------------
3629 int USERD_load_matf_data( int set_index,
3630 int part_id,
3631 int wtyp,
3632 int mat_type,
3633 int *ids_list,
3634 float *val_list)
3637 Returns:
3638 -------
3639 Z_OK if successful
3640 Z_ERR if not successful
3642 Arguments:
3643 ---------
3644 (IN) set_index = the material set index (zero based)
3646 (IN) part_id = the part number desired
3648 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3650 Z_POINT node point element
3651 Z_BAR02 2 node bar
3652 Z_BAR03 3 node bar
3653 Z_TRI03 3 node triangle
3654 Z_TRI06 6 node triangle
3655 Z_QUA04 4 node quad
3656 Z_QUA08 8 node quad
3657 Z_TET04 4 node tetrahedron
3658 Z_TET10 10 node tetrahedron
3659 Z_PYR05 5 node pyramid
3660 Z_PYR13 13 node pyramid
3661 Z_PEN06 6 node pentahedron
3662 Z_PEN15 15 node pentahedron
3663 Z_HEX08 8 node hexahedron
3664 Z_HEX20 20 node hexahedron
3665 Z_NSIDED nsided polygon
3666 Z_NFACED nfaced polyhedron
3668 Z_G_POINT ghost node point element
3669 Z_G_BAR02 2 node ghost bar
3670 Z_G_BAR03 3 node ghost bar
3671 Z_G_TRI03 3 node ghost triangle
3672 Z_G_TRI06 6 node ghost triangle
3673 Z_G_QUA04 4 node ghost quad
3674 Z_G_QUA08 8 node ghost quad
3675 Z_G_TET04 4 node ghost tetrahedron
3676 Z_G_TET10 10 node ghost tetrahedron
3677 Z_G_PYR05 5 node ghost pyramid
3678 Z_G_PYR13 13 node ghost pyramid
3679 Z_G_PEN06 6 node ghost pentahedron
3680 Z_G_PEN15 15 node ghost pentahedron
3681 Z_G_HEX08 8 node ghost hexahedron
3682 Z_G_HEX20 20 node ghost hexahedron
3683 Z_G_NSIDED ghost nsided polygon
3684 Z_G_NFACED ghost nfaced polyhedron
3686 (IN) mat_type = Z_MAT_INDEX for material ids list
3687 Z_MIX_INDEX for mixed-material ids list
3688 Z_MIX_VALUE for mixed-material values list
3690 (OUT) ids_list = If mat_type is Z_MAT_INDEX:
3691 ---------------------------
3692 1D material id list
3693 (Int array will have been allocated
3694 the appropriate size, as returned in
3695 USERD_size_matf_data for mat_type Z_MAT_INDEX)
3697 If mat_type is Z_MIX_INDEX:
3698 ---------------------------
3699 1D mixed-material id list
3700 (Int array will have been allocated
3701 the appropriate size, as returned in
3702 USERD_size_matf_data for mat_type Z_MIX_INDEX)
3704 (OUT) val_list = 1D mixed-materials values list
3705 (only used if mat_type is Z_MIX_VALUE)
3707 (Float array will have been allocated
3708 the appropriate size, as returned in
3709 USERD_size_matf_data for mat_type Z_MIX_VALUE)
3711 Notes:
3712 -----
3713 * See USERD_get_number_of_material_sets header for explanatory example
3714 * Will not be called if Num_material_sets is zero,
3715 or Num_materials[set_index] is zero,
3716 or the appropriate size from USERD_size_matf_data is zero
3720 --------------------------------------------------------------------
3721 USERD_set_filenames
3723 Description:
3724 -----------
3725 Receives the geometry and result filenames entered in the data
3726 dialog. The user written code will have to store and use these
3727 as needed. The user written code must manage its own files!!
3729 Specification:
3730 -------------
3731 int USERD_set_filenames(char filename_1[],
3732 char filename_2[],
3733 char the_path[],
3734 int swapbytes)
3736 Returns:
3737 -------
3738 Z_OK if successful
3739 Z_ERR if not successful
3741 Arguments:
3742 ---------
3743 (IN) filename_1 = the filename entered into the geometry
3744 field of the data dialog.
3746 (IN) param_2 = The usage of this string depends on
3747 'two_fields' in USERD_get_name_of_reader.
3749 If two_fields is FALSE then it's empty.
3751 If two_fields is TRUE, this is the
3752 manditory results file entered
3753 into the result field of the data dialog.
3755 If two_fields is -1, then this contains
3756 optional text (filenames, modifiers, etc.)
3757 that can be parsed and used to modify
3758 reader
3760 (IN) the_path = the path info from the data dialog.
3761 Note: filename_1 and filename_2 have already
3762 had the path prepended to them. This
3763 is provided in case it is needed for
3764 filenames contained in one of the files
3766 (IN) swapbytes = TRUE if should swap bytes when reading data.
3767 = FALSE normally.
3769 Notes:
3770 -----
3771 * Since you must manage everything from the input that is entered in
3772 these data dialog fields, this is an important routine!
3774 * It may be that you will need to have an executive type file that contains
3775 info and other filenames within it, like EnSight6's case file.
3778 --------------------------------------------------------------------
3779 USERD_set_server_number
3781 Description:
3782 -----------
3783 Receives the server number of how many total servers.
3785 Specification:
3786 -------------
3787 int USERD_set_server_number(int cur_serv,
3788 int tot_servs)
3790 Returns:
3791 -------
3792 nothing
3794 Arguments:
3795 ---------
3796 (IN) cur_serv = the current server.
3798 (IN) tot_servs = the total number of servers.
3800 Notes:
3801 -----
3802 * Only useful if your user defined reader is being used with EnSight's
3803 Server-of-Server capability. And even then, it may or may not be
3804 something that you can take advantage of. If your data is already
3805 partitioned in some manner, such that you can access the proper
3806 portions using this information.
3808 For all non-SOS uses, this will simply be 1 of 1
3812 --------------------------------------------------------------------
3813 USERD_set_time_set_and_step
3815 Description:
3816 -----------
3817 Set the current time step in the desired timeset. All functions that
3818 need time, and that do not explicitly pass it in, will use the timeset
3819 and step set by this routine, if needed.
3821 Specification:
3822 -------------
3823 void USERD_set_time_set_and_step(int timeset_number,
3824 int time_step)
3826 Returns:
3827 -------
3828 nothing
3830 Arguments:
3831 ---------
3832 (IN) timeset_number = the timeset number (1 based).
3834 For example: If USERD_get_number_of_timesets
3835 returns 2, the valid timeset_number's
3836 would be 1 and 2.
3838 (IN) time_step = The current time step to set
3840 Notes:
3841 -----
3842 * Current_time_step and Current_timeset would be set here
3845 --------------------------------------------------------------------
3846 USERD_size_matf_data
3848 Description:
3849 -----------
3850 Get the length of the material id list, mixed-material id list, or
3851 mixed-material values list for the given material set and part (and
3852 element type if material id list)
3854 Specification:
3855 -------------
3856 int USERD_size_matf_data( int set_index,
3857 int part_id,
3858 int wtyp,
3859 int mat_type,
3860 int *matf_size)
3863 Returns:
3864 -------
3865 Z_OK if successful
3866 Z_ERR if not successful
3868 Arguments:
3869 ---------
3870 (IN) set_index = the material set index (zero based)
3872 (IN) part_id = the part number desired
3874 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3876 Z_POINT node point element
3877 Z_BAR02 2 node bar
3878 Z_BAR03 3 node bar
3879 Z_TRI03 3 node triangle
3880 Z_TRI06 6 node triangle
3881 Z_QUA04 4 node quad
3882 Z_QUA08 8 node quad
3883 Z_TET04 4 node tetrahedron
3884 Z_TET10 10 node tetrahedron
3885 Z_PYR05 5 node pyramid
3886 Z_PYR13 13 node pyramid
3887 Z_PEN06 6 node pentahedron
3888 Z_PEN15 15 node pentahedron
3889 Z_HEX08 8 node hexahedron
3890 Z_HEX20 20 node hexahedron
3891 Z_NSIDED nsided polygon
3892 Z_NFACED nfaced polyhedron
3894 Z_G_POINT ghost node point element
3895 Z_G_BAR02 2 node ghost bar
3896 Z_G_BAR03 3 node ghost bar
3897 Z_G_TRI03 3 node ghost triangle
3898 Z_G_TRI06 6 node ghost triangle
3899 Z_G_QUA04 4 node ghost quad
3900 Z_G_QUA08 8 node ghost quad
3901 Z_G_TET04 4 node ghost tetrahedron
3902 Z_G_TET10 10 node ghost tetrahedron
3903 Z_G_PYR05 5 node ghost pyramid
3904 Z_G_PYR13 13 node ghost pyramid
3905 Z_G_PEN06 6 node ghost pentahedron
3906 Z_G_PEN15 15 node ghost pentahedron
3907 Z_G_HEX08 8 node ghost hexahedron
3908 Z_G_HEX20 20 node ghost hexahedron
3909 Z_G_NSIDED ghost nsided polygon
3910 Z_G_NFACED ghost nfaced polyhedron
3912 (IN) mat_type = Z_MAT_INDEX for material ids list
3913 Z_MIX_INDEX for mixed-material ids list
3914 Z_MIX_VALUE for mixed-material values list
3916 (OUT) matf_size = the length of the material id list, or
3917 mixed-material id list, or
3918 mixed-material values list
3919 for the given material set and part number
3920 (and element type if Z_MAT_INDEX)
3922 Notes:
3923 -----
3924 * See USERD_get_number_of_material_sets header for explanatory example
3925 * Will not be called if Num_material_sets is zero, or
3926 Num_materials[set_index] is zero
3931 --------------------------------------------------------------------
3932 USERD_stop_part_building
3934 Description:
3935 -----------
3936 This routine called when the part building dialog is closed. It is
3937 provided in case you desire to release memory, etc. that was only needed
3938 during the part building process.
3940 Specification:
3941 -------------
3942 void USERD_stop_part_building( void )
3944 Returns:
3945 -------
3946 nothing
3948 Arguments:
3949 ---------
3950 none
3952 Notes:
3953 -----
3955 --------------------------------------------------------------------
3956 USERD_rigidbody_existence
3958 Description:
3959 -----------
3960 Gets the existence of rigid body values or not in the model
3962 Specification:
3963 -------------
3964 int USERD_rigidbody_existence( void )
3966 Returns:
3967 -------
3968 Z_OK if rigid body values exist for the model
3969 Z_UNDEF if no rigid body values exist
3970 Z_ERR if an error
3972 Arguments:
3973 ---------
3974 none
3976 Notes:
3977 -----
3978 * This will be based on Current_time_step
3981 --------------------------------------------------------------------
3982 USERD_rigidbody_values
3984 Description:
3985 -----------
3986 Gets the rigid body values for each part
3988 Specification:
3989 -------------
3990 int USERD_rigidbody_values(int part_number,
3991 float values[7])
3993 Returns:
3994 -------
3995 Z_OK if rigid body values exist for the model
3996 Z_UNDEF if no rigid body values exist
3997 Z_ERR if an error
3999 Arguments:
4000 ---------
4001 (IN) part_number = The part number
4003 (1-based index of part table, namely:
4005 1 ... Numparts_available.
4007 It is NOT the part_id that
4008 is loaded in USERD_get_gold_part_build_info)
4010 (OUT) values values[0] = IX (x location)
4011 values[1] = IY (y location)
4012 values[2] = IZ (z location)
4013 values[3] = E0 (e0 euler value)
4014 values[4] = E1 (e1 euler value)
4015 values[5] = E2 (e2 euler value)
4016 values[6] = E3 (e3 euler value)
4019 Notes:
4020 -----
4021 * This will be based on Current_time_step
4022 * It will not be called unless USERD_rigidbody_existence indicates
4023 that there are some values in the model by returning Z_OK.
4026 --------------------------------------------------------------------
4027 USERD_set_right_side
4029 Description:
4030 -----------
4031 Informs the reader that the time currently set is the right side of a time
4032 span used for variable interpolation between time steps
4034 Specification:
4035 -------------
4036 void USERD_set_right_side( void )
4038 Returns:
4039 -------
4041 Arguments:
4042 ---------
4043 none
4045 Notes:
4046 -----
4047 * Applies to Current_time_step
4053 ------------------------------------------------------------------
4054 ENHANCED GUI ROUTINES
4056 --------------------------------------------------------------------
4057 USERD_get_extra_gui_numbers
4059 Description:
4060 -----------
4061 The Enhanced GUI routines are added to allow
4062 the user to customize a portion of the Data
4063 Reader dialog to pass in options to their
4064 user defined reader.
4066 Specification:
4067 -------------
4068 void USERD__get_extra_gui_numbers(int *num_Toggles,
4069 int *num_pulldowns,
4070 int *num_fields)
4072 Returns:
4073 -------
4075 Arguments:
4076 ---------
4077 (OUT) num_Toggles = number of toggles that will be provided
4079 num_pulldowns = number of pulldowns that will be provided
4081 num_fields = number of fields that will be provided
4083 Notes:
4084 -----
4085 There are three routines that work together:
4086 USERD_get_extra_gui_numbers
4087 USERD_get_extra_gui_defaults
4088 USERD_set_extra_gui_data
4090 The existence of these routine indicates that
4091 you wish to add customize entries to the
4092 Data Reader dialog.
4094 If you don't want the extra GUI features,
4095 simply delete these routines, or change their
4096 names to something such as
4097 USERD_DISABLED_get_extra_gui_defaults
4099 The presence of these routines
4100 will ensure that EnSight will call them and
4101 use their data to modify the extraction parameters set
4102 with some or all of the following:
4103 toggles, pulldown menu and fields.
4105 The user can then interact with the enhanced
4106 GUI and then send their choices to
4107 USERD_set_extra_gui_data
4109 Therefore if USERD_get_extra_gui_numbers
4110 exists then the other two must exist.
4112 If none exist, then the GUI will be unchanged.
4114 Toggle data will return an integer
4115 TRUE if checked
4116 FALSE if unchecked
4118 Pulldown menu will return an integer representing
4119 the menu item selected
4121 Field will return a string Z_LEN_GUI_FIELD_STR long.
4123 If all the enhanced GUI features are enabled it
4124 might look something like this
4126 ===================================================
4127 [] Title 1 [X] Title 3
4128 [X]Title 2 [X] Title 4
4130 Pulldown Menu ->
4131 Menu Choice 1
4132 Menu Choice 2
4133 Menu Choice 3
4135 Data Field Title 1 ____________________________
4137 Data Field Title 2 ____________________________
4138 =====================================================
4140 This routine defines the numbers of toggles, pulldowns & fields
4142 The following are defined in the global_extern.h
4143 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4144 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4145 Z_LEN_GUI_FIELD_STR max length of field string
4146 Z_LEN_GUI_TITLE_STR max length of title string
4148 The library is loaded, this routine is
4149 called, then the library is unloaded.
4151 Do not define globals in this routine
4152 as when the library is unloaded, you'll
4153 lose them.
4156 --------------------------------------------------------------------
4157 USERD_get_extra_gui_defaults
4159 Description:
4160 -----------
4161 This routine defines the Titles, status,
4162 List choices, strings, etc that are fed
4163 up to the GUI.
4165 Specification:
4166 -------------
4167 int USERD_get_extra_gui_defaults(char **toggle_Title,
4168 int *toggle_default_status,
4169 char **pulldown_Title,
4170 int *pulldown_number_in_list,
4171 int *pulldown_default_selection,
4172 char ***pulldown_item_strings,
4173 char **field_Title,
4174 char **field_user_string)
4176 Returns:
4177 -------
4178 Z_OK if successful
4179 Z_ERR if not successful
4181 Arguments:
4182 ---------
4183 (OUT) toggle_Title = title for each toggle
4184 array dimension is [num_toggles] by
4185 [Z_LEN_GUI_TITLE_STR] long
4187 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4188 array dimension is [num_toggles] long
4190 pulldown_Title = title for each pulldown
4191 array dimension is [num_pulldowns] by
4192 [Z_LEN_GUI_TITLE_STR] long
4194 pulldown_number_in_list = number of items in each pulldown
4195 array dimension is [num_pulldowns] long
4197 pulldown_default_selection = pulldown item selection for each pulldown
4198 array dimension is [num_pulldowns] long
4200 pulldown_item_strings = pulldown item strings
4201 array is [num_pulldowns] by
4202 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4203 [Z_LEN_GUI_PULL_STR] long
4205 field_Title = title for each field
4206 array dimension is [num_fields] by
4207 [Z_LEN_GUI_TITLE_STR] long
4209 field_user_string = content of the field
4210 array dimension is [num_fields] by
4211 [Z_LEN_GUI_TITLE_STR] long
4215 Notes:
4216 -----
4217 * The library is loaded, this routine is called, then the library is unloaded.
4219 * Do not define globals in this routine as when the library is unloaded, you'll
4220 lose them.
4224 --------------------------------------------------------------------
4225 USERD_set_extra_gui_data
4227 Description:
4228 -----------
4229 This routine sets the new values for the toggles, pulldowns, and fields.
4231 Specification:
4232 -------------
4233 void USERD_set_extra_gui_data(
4234 int *toggle, /* [num_toggle] */
4235 int *pulldown, /* [num_pulldown] */
4236 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4238 Returns:
4239 -------
4241 Arguments:
4242 ---------
4243 (IN) toggle = setting for each toggle. TRUE or FALSE
4244 array dimension is [num_toggles] long
4246 pulldown = item chosen in each pulldown. (0 based)
4247 array dimension is [num_pulldowns] long
4249 field_text = content of the field
4250 array dimension is [num_fields] by
4251 [Z_LEN_GUI_TITLE_STR] long
4254 Notes:
4255 -----
4256 * This routine is called when the library is permanently
4257 loaded to the EnSight session, so define your globals
4258 in this and later routines.
4260 * It's up to you to change your reader behavior according to
4261 user entries!
4265 --------------------------------------------------------------------
4266 USERD_get_var_extract_gui_numbers
4268 Description:
4269 -----------
4270 The Var_Extract_GUI routines are added to allow
4271 the user to customize a extraction parameters
4272 for variables "after" the file has been read.
4273 These things can be modified and the variables will
4274 be update/refreshed according to the new parameters set
4276 Specification:
4277 -------------
4278 void USERD_get_var_extract_gui_numbers(int *num_Toggles,
4279 int *num_pulldowns,
4280 int *num_fields)
4283 Returns:
4284 -------
4286 Arguments:
4287 ---------
4288 (OUT) num_Toggles = number of toggles that will be provided
4290 num_pulldowns = number of pulldowns that will be provided
4292 num_fields = number of fields that will be provided
4294 Notes:
4295 -----
4296 There are three routines that work together:
4297 USERD_get_var_extract_gui_numbers
4298 USERD_get_var_extract_gui_defaults (this one)
4299 USERD_set_var_extract_gui_data
4301 The existence of these routine indicates that
4302 you wish to have the Var Extract Parameters dialog.
4304 If you don't want the extra GUI features,
4305 simply delete these routines, or change their
4306 names to something such as
4307 USERD_DISABLED_get_var_extract_gui_defaults
4309 The presence of these routines
4310 will ensure that EnSight will call them and
4311 use their data to modify the extraction parameters set
4312 with some or all of the following:
4313 toggles, pulldown menu and fields.
4315 The user can then interact with the enhanced
4316 GUI and then send their choices to
4317 USERD_set_extra_gui_data
4319 Therefore if USERD_get_var_extract_gui_numbers
4320 exists then the other two must exist.
4322 If none exist, then the GUI will be unchanged.
4324 Toggle data will return an integer
4325 TRUE if checked
4326 FALSE if unchecked
4328 Pulldown menu will return an integer representing
4329 the menu item selected
4331 Field will return a string Z_LEN_GUI_FIELD_STR long.
4333 If all the enhanced GUI features are enabled it
4334 might look something like this
4336 ===================================================
4337 [] Title 1 [X] Title 3
4338 [X]Title 2 [X] Title 4
4340 Pulldown Menu ->
4341 Menu Choice 1
4342 Menu Choice 2
4343 Menu Choice 3
4345 Data Field Title 1 ____________________________
4347 Data Field Title 2 ____________________________
4348 =====================================================
4350 This routine defines the numbers of toggles, pulldowns & fields
4352 The following are defined in the global_extern.h
4353 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4354 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4355 Z_LEN_GUI_FIELD_STR max length of field string
4356 Z_LEN_GUI_TITLE_STR max length of title string
4358 The library is loaded, this routine is
4359 called, then the library is unloaded.
4361 Do not define globals in this routine
4362 as when the library is unloaded, you'll
4363 lose them.
4366 --------------------------------------------------------------------
4367 USERD_get_var_extract_gui_defaults
4369 Description:
4370 -----------
4371 This routine defines the Titles, status,
4372 List choices, strings, etc that are fed
4373 up to the GUI.
4375 Specification:
4376 -------------
4377 int USERD_get_var_extract_gui_defaults(char **toggle_Title,
4378 int *toggle_default_status,
4379 char **pulldown_Title,
4380 int *pulldown_number_in_list,
4381 int *pulldown_default_selection,
4382 char ***pulldown_item_strings,
4383 char **field_Title,
4384 char **field_user_string)
4386 Returns:
4387 -------
4388 Z_OK if successful
4389 Z_ERR if not successful
4391 Arguments:
4392 ---------
4393 (OUT) toggle_Title = title for each toggle
4394 array dimension is [num_toggles] by
4395 [Z_LEN_GUI_TITLE_STR] long
4397 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4398 array dimension is [num_toggles] long
4400 pulldown_Title = title for each pulldown
4401 array dimension is [num_pulldowns] by
4402 [Z_LEN_GUI_TITLE_STR] long
4404 pulldown_number_in_list = number of items in each pulldown
4405 array dimension is [num_pulldowns] long
4407 pulldown_default_selection = pulldown item selection for each pulldown
4408 array dimension is [num_pulldowns] long
4410 pulldown_item_strings = pulldown item strings
4411 array is [num_pulldowns] by
4412 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4413 [Z_LEN_GUI_PULL_STR] long
4415 field_Title = title for each field
4416 array dimension is [num_fields] by
4417 [Z_LEN_GUI_TITLE_STR] long
4419 field_user_string = content of the field
4420 array dimension is [num_fields] by
4421 [Z_LEN_GUI_TITLE_STR] long
4425 Notes:
4426 -----
4427 * The library is loaded, this routine is called, then the library is unloaded.
4429 * Do not define globals in this routine as when the library is unloaded, you'll
4430 lose them.
4434 --------------------------------------------------------------------
4435 USERD_set_var_extract_gui_data
4437 Description:
4438 -----------
4439 This routine sets the new values for the toggles, pulldowns, and fields.
4441 Specification:
4442 -------------
4443 void USERD_set_var_extract_gui_data(
4444 int *toggle, /* [num_toggle] */
4445 int *pulldown, /* [num_pulldown] */
4446 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4448 Returns:
4449 -------
4451 Arguments:
4452 ---------
4453 (IN) toggle = setting for each toggle. TRUE or FALSE
4454 array dimension is [num_toggles] long
4456 pulldown = item chosen in each pulldown. (0 based)
4457 array dimension is [num_pulldowns] long
4459 field_text = content of the field
4460 array dimension is [num_fields] by
4461 [Z_LEN_GUI_TITLE_STR] long
4464 Notes:
4465 -----
4466 * This routine is called when the library is permanently
4467 loaded to the EnSight session, so define your globals
4468 in this and later routines.
4470 * It's up to you to change your reader behavior according to
4471 user entries!
4477 -----------------------------------------------------------------------------------
4478 /* ----------------------------------------------------------
4479 * New in EnSight 8 is the capability to remove (fail) elements
4480 * based on variable threshold values. Basically the variable
4481 * name, a couple of thresholds, a couple of values and a logic
4482 * criteria are read in from this routine. Every element that
4483 * satisfies the failure criteria is removed and not used in
4484 * EnSight calculations.
4485 *
4486 * Example Failure criteria
4487 * Let fail_var_name = "fail_flag"
4488 * threshold_val1 = 0
4489 * threshold_operator1 = Z_EQUAL_TO
4490 * logic_criteria2 not used
4491 * threshold_val2 not used
4492 * threshold_operator2 not used
4493 * For each value of "fail_flag" at each element,
4494 * if fail flag == threshold_val1 (0.0) then element fails
4495 * Return (Z_ERR) if this is not used.
4496 * Return (Z_OK) if failed element feature should be used
4497 *
4498 * threshold_operator1 & 2 can be one of the following
4499 * Z_ELE_FAILED_NONE, - disables checking
4500 * Z_ELE_FAILED_GREATER, - greater than
4501 * Z_ELE_FAILED_LESS, - less than
4502 * Z_ELE_FAILED_EQUAL, - equal
4503 * Z_ELE_FAILED_NOT_EQUAL, - not equal
4504 * Z_ELE_FAILED_MANY - not used
4505 *
4506 * logic_criteria2
4507 * Z_ELE_FAILED_LOGIC_NONE,
4508 * Z_ELE_FAILED_LOGIC_AND,
4509 * Z_ELE_FAILED_LOGIC_OR,
4510 * Z_ELE_FAILED_LOGIC_MANY
4511 *
4512 * ---------------------------------------------------------- */
4513 int USERD_get_uns_failed_params(
4514 char *fail_var_name, /* variable name to be used in failure
4515 must be scalar, per elem */
4516 float *threshold_val1, /* number to compare for failure */
4517 float *threshold_val2, /* number to compare for failure */
4518 int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN,
4519 Z_EQUAL_TO */
4520 int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN,
4521 Z_EQUAL_TO */
4522 int *logic_criteria2
4525 /*--------------------------------------------------------------------
4526 * USERD_get_structured_reader_cinching -
4527 *--------------------------------------------------------------------
4528 *
4529 * Gets whether this reader will do structured cinching for block data
4530 * This means that it will handle the min, max, and step values for a
4531 * given block and return the coordinate components or variable components
4532 * in their "cinched" state when partial extraction or striding is used.
4533 * This is as opposed to returning the entire component (ignoring min, max
4534 * and stride) and letting Ensight pick out the values actually used.
4535 *
4536 * returns: Z_OK if the reader will handle the
4537 * min, max, and stride and return
4538 * the cinched values only.
4539 *
4540 * Z_UNDEF or Z_ERR if will return entire component
4541 * and rely on EnSight to cinch.
4542 *
4543 * Notes:
4544 * Unless you can actually pull out the desired min, max, and stride
4545 * without using a full component of memory, don't enable this feature.
4546 *--------------------------------------------------------------------*/
4547 int
4548 USERD_get_structured_reader_cinching( void )
4552 /*--------------------------------------------------------------------
4553 * USERD_set_block_range_and_stride -
4554 *--------------------------------------------------------------------
4555 *
4556 * Sets the min, max, and step values in each of the i, j, and k, directions
4557 * for the given part.
4558 *
4559 * (IN) part_number = The part number
4560 *
4561 * (1-based index of part table, namely:
4562 *
4563 * 1 ... Numparts_available.
4564 *
4565 * It is NOT the part_id that
4566 * is loaded in
4567 * USERD_get_gold_part_build_info)
4568 *
4569 * (IN) mini = min i plane desired (zero based)
4570 * maxi = max i plane desired (zero based)
4571 * stepi = i stride
4572 * minj = min j plane desired (zero based)
4573 * maxj = max j plane desired (zero based)
4574 * stepj = j stride
4575 * mink = min k plane desired (zero based)
4576 * maxk = max k plane desired (zero based)
4577 * stepk = k stride
4578 *
4579 *
4580 * returns: Z_OK if no problems
4581 * Z_ERR if an error
4582 *
4583 * Notes:
4584 * * It will not be called unless USERD_get_structured_reader_cinching
4585 * indicates that this reader does structured cinching by returning
4586 * a Z_OK.
4587 *
4588 * * It will actually be called before each geom component and before
4589 * each part variable - so if you are storing things locally, you should
4590 * make this routine be able to quickly check whether anything needs
4591 * updated or not.
4592 *
4593 * * If the stride (step) does not hit right on the max, the last element
4594 * in each direction will be shortened appropriately.
4595 * For example, if a block had 0 to 12 in the i direction,
4596 * and the user specified min = 1
4597 * max = 8
4598 * step = 3
4599 *
4600 * 0 1 2 3 4 5 6 7 8 9 10 11 12
4601 * | | | | | | | | | | | | |
4602 *
4603 * | | | |
4604 *
4605 * Namely, the coarser cell boundaries in this direction would be at 1, 4,
4606 7, and 8
4607 *
4608 *--------------------------------------------------------------------*/
4609 int
4610 USERD_set_block_range_and_stride(int part_number,
4611 int mini, int maxi, int stepi,
4612 int minj, int maxj, int stepj,
4613 int mink, int maxk, int stepk)
4617 ---- end of document ----