[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.06
| blob | 88c4955c810c5273db3a5240921714c7fc13fc5c |
1 README_USERD_2.06
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.06)
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.06 additional capabilities (beyond API 2.05):
17 Routines to allow userd defined readers for structured data
18 to deal with min, max, and stride within the reader itself
19 instead of within EnSight.
20 USERD_get_structured_reader_cinching
21 USERD_set_block_range_and_stride
24 ***>> API 2.05 additional capabilities (beyond API 2.04):
25 Routines to handle material species.
26 USERD_get_number_of_species
27 USERD_get_matsp_info
29 Routines to handle variable extraction parameters after a read, and then
30 update the variables accordingly. Similar to the extra GUI capabilities
31 (which are processed before a read). (Can actually be added to pre-2.05 readers)
32 USERD_get_var_extract_gui_numbers
33 USERD_get_var_extract_gui_defaults
34 USERD_set_var_extract_gui_data
36 Routines to obtain rigid body values from a reader.
37 (Routines were added - EnSight is now using for Nastran and STL readers
38 with Dynasty rigid body motion data file)
39 USERD_rigidbody_existence
40 USERD_rigidbody_values
42 Routine that lets reader know when EnSight is getting the right side of a time
43 interval for variable interpolation between steps. Not generally needed for
44 most readers - however, may be needed for those that implement rigid body, and
45 wish to cache left and right timespan information for interpolation within the
46 reader itself. (Can actually be added to pre-2.05 readers)
47 USERD_set_right_side
50 ***>> API 2.04 additional capabilities (beyond API 2.03):
51 Routines to handle failed elements. Basically
52 a.One routine to return a flag indicating the existence of
53 failed elements in at least one part in at least one
54 timestep in the model.
55 b.A second routine to return a matrix of flags indexed by part and
56 element type indicating which parts and element types have failed
57 elements at the current time step.
58 c.Finally a third routine to return an array of flags for a given
59 part and element type that is number of elements of that type long
60 indicating which elements have failed, and which have not failed.
63 ***>> API 2.03 additional capabilities (beyond API 2.01):
64 1. Routines to handle materials
65 2. Routines to handle nsided and nfaced elements
66 3. Modified routine to handle structured ranges
69 ****************************************************************************
70 Note: Only the the Ensight Gold example reader, has been moved to
71 this 2.06 API level. And it is purely for an example - it does not
72 actually provide a benefit.
73 ****************************************************************************
76 The process for producing a user defined reader is:
77 ---------------------------------------------------
78 1. Write code for all pertinent routines in the library (Unless someone else
79 has done this for you).
81 This is of course where the work is done by the user. The word
82 "pertinent" is used because depending on the nature of the data, some
83 of the routines in the library may be dummy routines.
85 The source code for a dummy_gold library and for various other
86 working or sample libraries is copied from the installation CD during
87 installation. These will be located in directories under:
89 $CEI_HOME/ensight76/user_defined_src/readers
91 examples:
92 --------
93 Basic dummy_gold routines provide skeleton for a new reader
94 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
96 Sample library which reads unstructured binary EnSight Gold data
97 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
99 You may find it useful to place your library source in this area as
100 well, but are not limited to this location.
102 * ===> The descriptions of each library routine and the order that the
103 routines are called, which is provided in this file, along with
104 the example libraries, should make it possible for you to produce
105 code for your own data reader.
108 2. Produce the dynamic shared library.
110 This is a compiling and loading process which varies according to
111 the type of machine you are on. In the user-defined-reader source
112 tree we have tried to isolate the machine dependent parts of the
113 build process using a set of files in the 'config' directory. In this
114 directory there is a configuration file for each platform on which
115 EnSight is supported. Before you can compile the installed readers
116 you should run the script called 'init' in the config directory.
118 i.e. (for UNIX)
119 cd config
120 ./init sgi_6.5_n64
121 cd ..
122 make
124 If you are compiling for Windows NT, there are two options. If you
125 have the Cygwin GNU utilities installed, you can use GNU make as for
126 Unix. Otherwise, there is a script called makeall.cmd which will
127 build all of the readers using nmake. The Makefiles in each reader
128 directory will work using either make or nmake.
130 i.e. (WIN32 Cygwin) (using nmake)
131 cd config cd config
132 sh init win32 cp win32 config
133 cd .. cd ..
134 mkdir lib
135 make makeall.cmd
137 If you have platform-specific portions of code in your reader, the
138 build system defines a set of flags which can be used within
139 #ifdef ... #endif regions in your source, as shown in the table
140 below.
142 Because the readers are now dynamically opened by EnSight, you may
143 have to include dependent libraries on your link-line to avoid having
144 unresolved symbols. If you are having problems with a reader, start
145 ensight as "ensight7 -readerdbg" and you will get feedback on any
146 problems encountered in loading a reader. If there are unresolved
147 symbols, you need to find the library which contains the missing
148 symbols and link it into your reader by adding it to the example
149 link commands below.
151 If you choose to use a different build environment for your reader,
152 you should take care to use compatible compilation flags to ensure
153 compatibilty with the EnSight executables, most notably on the SGI
154 and HP-UX 11.0 platforms, which should use the following flags:
156 sgi_6.2_o32: -mips2
157 sgi_6.2_n64: -mips4 -64
158 sgi_6.5_n32: -mips3
159 sgi_6.5_n64: -mips4 -64
160 hp_11.0_32: +DA2.0
161 hp_11.0_64: +DA2.0W
163 ______________________________________________________________________
164 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
165 | TYPE |------------------------------------------------------------|
166 | | LD COMMAND USED IN MAKEFILE |
167 ======================================================================
168 ______________________________________________________________________
169 | sgi | -DSGI | libuserd-X.so |
170 | |------------------------------------------------------------|
171 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
172 ----------------------------------------------------------------------
173 ______________________________________________________________________
174 | hp | -DHP | libuserd-X.sl |
175 | |------------------------------------------------------------|
176 | | ld -b -o libuserd-X.sl libuserd-X.o |
177 ----------------------------------------------------------------------
178 ______________________________________________________________________
179 | sun | -DSUN | libuserd-X.so |
180 | |------------------------------------------------------------|
181 | | ld -G -o libuserd-X.so libuserd-X.o |
182 ----------------------------------------------------------------------
183 ______________________________________________________________________
184 | dec | -DDEC | libuserd-X.so |
185 | |------------------------------------------------------------|
186 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
187 ----------------------------------------------------------------------
188 ______________________________________________________________________
189 | linux | -DLINUX | libuserd-X.so |
190 | |------------------------------------------------------------|
191 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
192 ----------------------------------------------------------------------
193 ______________________________________________________________________
194 | alpha | -DALINUX | libuserd-X.so |
195 | linux |------------------------------------------------------------|
196 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
197 ----------------------------------------------------------------------
198 ______________________________________________________________________
199 | ibm | -DIBM | libuserd-X.so |
200 | |------------------------------------------------------------|
201 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
202 ----------------------------------------------------------------------
204 Once you have created your library, you should place it in a directory
205 of your choice or in the standard reader location:
207 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
209 For example, if you created a reader for "mydata", you should create
210 the reader libuserd-mydata.so and place the file in your own reader
211 directory (see section 3 below) or in the standard location:
213 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
216 3. By default EnSight will load all readers found in the directory:
218 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
220 Files with names "libuserd-X.so" (where X is a name unique to the reader)
221 are assumed to be user-defined readers.
223 There are two methods which can be used to supplement the default
224 behavior.
226 (1) A feature which is useful for site-level or user-level configuration
227 is the optional environment variable $ENSIGHT7_READER. This
228 variable directs EnSight to load all readers in the specified reader
229 directory (you should probably specify a full path) before loading
230 the built-in readers. If the same reader exists in both directories
231 (as determined by the name returned by USERD_get_name_of_reader(),
232 NOT by the filename), the locally configured reader will take
233 precedence.
235 (2) A useful feature for end-users is the use of the libuserd-devel
236 reader. EnSight will search for a reader named libuserd-devel.so
237 (.sl for HP or .dll for NT). This reader can exist anywhere in the
238 library path (see below) of the user. This is useful for an
239 individual actively developing a reader because the existence of a
240 libuserd-devel library will take precedence over any other library
241 which returns the same name from USERD_get_name_of_reader().
243 As an example, a site may install commonly used readers in a common
244 location, and users can set the ENSIGHT7_READER variable to access them:
246 setenv ENSIGHT7_READER /usr/local/lib/e7readers
248 A user working on a new reader may compile the reader and place it in
249 a directory specified by the library path:
251 cp libuserd-myreader.so ~/lib/libuserd-devel.so
252 setenv <librarypath> ~/lib:$<librarypath>
254 The user is responsible for correctly configuring the library path
255 variable in order to make use of the libuserd-devel feature. The
256 library environment variables used are:
258 Machine type Environment variable to set
259 ------------ ---------------------------
260 sgi LD_LIBRARY_PATH
261 dec LD_LIBRARY_PATH
262 sun LD_LIBRARY_PATH
263 linux LD_LIBRARY_PATH
264 alpha linux LD_LIBRARY_PATH
265 hp SHLIB_PATH
266 ibm LIBPATH
268 As always, EnSight support is available if you need it.
270 -------------------------------
271 Quick Index of Library Routines
272 -------------------------------
274 Generally Needed for UNSTRUCTURED data
275 --------------------------------------
276 USERD_get_part_coords part's node coordinates
277 USERD_get_part_node_ids part's node ids
278 USERD_get_part_elements_by_type part's element connectivites
279 USERD_get_part_element_ids_by_type part's element ids
282 Generally Needed for BLOCK data
283 --------------------------------------
284 USERD_get_block_coords_by_component block coordinates
285 USERD_get_block_iblanking block iblanking values
286 USERD_get_ghosts_in_block_flag block ghost cell existence?
287 USERD_get_block_ghost_flags block ghost cell flags
289 These routines, which formerly were only for unstructured data, will now
290 also be called for structured data if you specify that ids will be given
291 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
292 ------------------------------------------------------------------------------
293 USERD_get_part_node_ids part's node ids
294 USERD_get_part_element_ids_by_type part's element ids
297 Generally needed for either or both kinds of data
298 -------------------------------------------------
299 USERD_get_name_of_reader name of reader for GUI
300 USERD_get_reader_release release string of reader
301 USERD_get_reader_version provide reader version number
302 USERD_get_reader_descrip provide GUI more description (optional)
304 USERD_get_extra_gui_numbers Gets the number of toggles, pulldowns and fields
305 USERD_get_extra_gui_defaults Gets the default values for the GUI members
306 USERD_set_extra_gui_data Returns the answers provided by the user
308 USERD_set_filenames filenames entered in GUI
309 USERD_set_server_number server which of how many
311 USERD_get_number_of_timesets number of timesets
312 USERD_get_timeset_description description of timeset
313 USERD_get_geom_timeset_number timeset # to use for geom
315 USERD_get_num_of_time_steps number of time steps
316 USERD_get_sol_times solution time values
317 USERD_set_time_set_and_step current timeset and time step
319 USERD_get_changing_geometry_status changing geometry?
320 USERD_get_node_label_status node labels?
321 USERD_get_element_label_status element labels?
322 USERD_get_model_extents provide model bounding extents
323 USERD_get_number_of_files_in_dataset number of files in model
324 USERD_get_dataset_query_file_info info about each model file
325 USERD_get_descrip_lines file associated description lines
326 USERD_get_number_of_model_parts number of model parts
327 USERD_get_gold_part_build_info Gets the info needed for part building process
328 USERD_get_part_build_info part/block type/descrip etc.
329 USERD_get_maxsize_info part/block allocation maximums
330 USERD_get_ghosts_in_model_flag model contains ghost cells?
331 USERD_get_nsided_conn Gets the element connectivities for nsided
332 elements. (utilizes the number of nodes
333 per element obtained in
334 USERD_get_part_elements_by_type)
335 USERD_get_nfaced_nodes_per_face Gets the number of nodes per face for nfaced
336 elements (utilizes the number of faces
337 per element obtained in
338 USERD_get_part_elements_by_type)
339 USERD_get_nfaced_conn Gets the element connectivities for nfaced
340 elements (utilizes the number of nodes
341 per face obtained in
342 USERD_get_nfaced_nodes_per_face)
345 USERD_get_border_availability part border provided?
346 USERD_get_border_elements_by_type part border conn and parent info
348 USERD_get_number_of_variables number of variables
349 USERD_get_gold_variable_info variable type/descrip etc.
350 USERD_get_var_by_component part or block variable values
351 USERD_get_constant_val constant variable's value
352 USERD_get_var_value_at_specific node's or element's variable value over time
353 USERD_stop_part_building cleanup after part build routine
355 USERD_get_number_of_material_sets Gets the number of material sets
356 USERD_get_matf_set_info Gets the material set indices and names
357 USERD_get_number_of_materials Gets the number of materials
358 USERD_get_matf_var_info Gets the material indices and descriptions
359 USERD_size_matf_data Gets the length of either the
360 material ids list,
361 mixed-material ids list, or
362 mixed-material values list
363 USERD_load_matf_data Gets the material ids list,
364 mixed-material ids list, or
365 mixed-material values list
367 USERD_bkup archive routine
369 USERD_exit_routine cleanup upon exit routine
371 USERD_get_uns_failed_params Gets thresholds/criteria for failure
373 USERD_rigidbody_existence Returns whether rigid body transformation
374 data exists for the model.
375 USERD_rigidbody_values Returns the euler and location values for a
376 given part
378 USERD_set_right_side Simply informs the reader when the time set
379 is for the right side of a time span during
380 variable interpolation between time steps.
382 USERD_get_structured_reader_cinching Tells if the reader will do structured
383 cinching
384 USERD_set_block_range_and_stride Sets the min, max, and stride of a block
385 if doing structured cinching
388 -------------------------
389 Order Routines are called
390 -------------------------
392 The various main operations are given basically in the order they will
393 be performed. Within each operation, the order the routines will be
394 called is given.
396 1. Setting name in the gui, and specifying one or two input fields
398 USERD_get_name_of_reader
399 USERD_get_reader_descrip (optional)
400 USERD_get_extra_gui_numbers (optional)
401 USERD_get_extra_gui_defaults (optional)
403 2. Getting the reader version (also distinguishes between API's)
405 USERD_get_reader_version
407 3. Setting filenames and getting timeset and time info
409 <USERD_set_extra_gui_data> (optional if reader has
410 USERD_get_extra_gui_defaults routine)
411 USERD_get_structured_reader_cinching
412 USERD_set_server_number
413 USERD_set_extra_gui_data (optional)
414 USERD_set_filenames
415 USERD_get_number_of_timesets
416 USERD_get_geom_timeset_number
418 for each timeset:
419 USERD_get_timeset_description
420 USERD_get_num_of_time_steps
421 USERD_get_sol_times
423 USERD_set_time_set_and_step
425 4. Gathering info for part builder
427 USERD_set_time_set_and_step
428 USERD_get_changing_geometry_status
429 USERD_get_node_label_status
430 USERD_get_element_label_status
431 USERD_get_number_of_files_in_dataset
432 USERD_get_dataset_query_file_info
433 USERD_get_descrip_lines (for geometry)
434 USERD_get_number_of_model_parts
435 USERD_get_gold_part_build_info
436 USERD_get_ghosts_in_model_flag
437 USERD_get_maxsize_info
438 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
439 USERD_get_model_extents OR (for model extents)
440 USERD_get_part_coords AND/OR
441 <USERD_set_block_range_and_stride> (if doing structured reader cinching
442 USERD_get_block_coords_by_component
444 5. Gathering Variable info
446 USERD_get_number_of_variables
447 USERD_get_gold_variable_info
449 6. Part building (per part created)
451 both unstructured and structured:
452 --------------------------------
453 USERD_set_time_set_and_step
455 if unstructured part:
456 --------------------
457 USERD_get_part_element_ids_by_type
458 USERD_get_part_elements_by_type
460 If any nsided elements:
462 USERD_get_nsided_conn
464 If any nfaced elements:
466 USERD_get_nfaced_nodes_per_face
467 USERD_get_nfaced_conn
469 USERD_get_part_coords
470 USERD_get_part_node_ids
472 else if structured part:
473 -----------------------
474 USERD_get_block_iblanking
475 <USERD_set_block_range_and_stride> (if doing structured reader cinching
476 USERD_get_block_coords_by_component
477 USERD_get_block_ghost_flags (If ghost cells in part)
478 USERD_get_part_node_ids (If node ids given)
479 USERD_get_part_element_ids_by_type (If element ids given)
481 both again:
482 ----------
483 USERD_get_border_availability (If border representation
484 USERD_get_border_elements_by_type is selected)
486 USERD_stop_part_building (only once when part builder
487 dialog is closed)
489 7. Loading Variables
491 constants:
492 ---------
493 USERD_set_time_set_and_step
494 USERD_get_constant_val
496 scalars/vectors/tensors:
497 ------------------------
498 USERD_get_descrip_lines
499 USERD_set_time_set_and_step
500 <USERD_set_block_range_and_stride> (if doing structured reader cinching
501 USERD_get_var_by_component
503 8. Changing geometry
505 changing coords only (per part):
506 --------------------
507 USERD_set_time_set_and_step
508 USERD_get_descrip_lines
509 USERD_get_part_coords
510 <USERD_set_block_range_and_stride> (if doing structured reader cinching
511 USERD_get_block_coords_by_component
513 changing connectivity (per part):
514 ---------------------
515 USERD_set_time_set_and_step
516 USERD_get_descrip_lines
517 USERD_get_number_of_model_parts
518 USERD_get_gold_part_build_info
519 USERD_get_ghosts_in_model_flag
520 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
521 USERD_get_model_extents OR
522 USERD_get_part_coords AND/OR
523 <USERD_set_block_range_and_stride> (if doing structured reader cinching
524 USERD_get_block_coords_by_component
525 USERD_get_part_element_ids_by_type
526 USERD_get_part_elements_by_type
527 USERD_get_part_coords
528 USERD_get_part_node_ids
529 USERD_get_block_iblanking
530 <USERD_set_block_range_and_stride> (if doing structured reader cinching
531 USERD_get_block_coords_by_component
532 USERD_get_block_ghost_flags (If ghost cells in part)
533 USERD_get_part_node_ids (If node ids given)
534 USERD_get_part_element_ids_by_type (If element ids given)
536 USERD_get_border_availability (If border representation
537 USERD_get_border_elements_by_type is selected)
540 9. Node or Element queries over time
542 USERD_get_var_value_at_specific
544 10. To see if materials in the model
546 USERD_get_number_of_material_sets
547 USERD_get_matf_set_info
549 If any material sets in the model (calls these once per material set):
550 USERD_get_number_of_materials
551 USERD_get_matf_var_info
553 For each elment type of each part containing material ids, calls:
554 USERD_size_matf_data
555 USERD_load_matf_data
557 If there are any elements with mixed materials, when a domain or
558 interface is created, calls these again per part:
560 USERD_size_matf_data
561 USERD_load_matf_data
563 11. To modify the variable extraction parameters and have the variables
564 update accordingly.
566 USERD_get_var_extract_gui_numbers
567 USERD_get_var_extract_gui_defaults
568 USERD_set_var_extract_gui_data
572 -----------------------
573 Detailed Specifications
574 -----------------------
576 Include files:
577 --------------
578 The following header file is required in any file containing these library
579 routines.
581 #include "global_extern.h"
583 And it references:
585 #include "global_extern_proto.h"
589 *******************************************************************************
590 ****************************** Special Note ***********************************
591 *******************************************************************************
593 Make sure you use the proper define in the global_extern.h header file, namely:
594 #define USERD_API_204
596 Also, Make sure the api version in the USERD_get_reader_version routine is set
597 to "2.04" or larger.
599 Make sure your reader has access to the global_extern_proto.h This is a new
600 file which is accessed from the new global_extern.h
602 *******************************************************************************
603 *******************************************************************************
606 Basis of arrays:
607 ---------------
608 Unless explicitly stated otherwise, all arrays are zero based - in true C
609 fashion.
612 Global variables:
613 ----------------
614 You will generally need to have a few global variables which are shared by
615 the various library routines. The detailed specifications below have assumed
616 the following are available. (Their names describe their purpose, and they
617 will be used in helping describe the details of the routines below).
619 static int Numparts_available = 0;
620 static int Num_unstructured_parts = 0;
621 static int Num_structured_blocks = 0;
623 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
625 static int Num_timesets = 1;
626 static int Current_timeset = 1;
627 static int Geom_timeset_number = 1;
629 static int Num_time_steps[Z_MAXSETS] = 1;
630 static int Current_time_step = 0;
631 static int Num_variables = 0;
632 static int Num_dataset_files = 0;
634 static int Server_Number = 1; Which server of
635 static int Tot_Servers = 1; the total number of servers
639 _________________________________________
640 -----------------------------------------
641 Library Routines (in alphabetical order):
642 _________________________________________
643 -----------------------------------------
645 --------------------------------------------------------------------
646 USERD_bkup
648 Description:
649 -----------
650 This routine is called during the EnSight archive process. You can
651 use it to save or restore info relating to your user defined reader.
653 Specification:
654 -------------
655 int USERD_bkup(FILE *archive_file,
656 int backup_type)
658 Returns:
659 -------
660 Z_OK if successful
661 Z_ERR if not successful
663 Arguments:
664 ---------
665 (IN) archive_file = The archive file pointer
667 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
668 Z_REST_ARCHIVE for restoring archive
670 Notes:
671 -----
672 * Since EnSight's archive file is saved in binary form, you should
673 also do any writing to it or reading from it in binary.
675 * You should archive any variables, which will be needed for
676 future operations, that will not be read or computed again
677 before they will be needed. These are typically global
678 variables.
680 * Make sure that the number of bytes that you write on a save and
681 the number of bytes that you read on a restore are identical!!
683 * If any of the variables you save are allocated arrays, you must
684 do the allocations before restoring into them.
686 --------------------------------------------------------------------
687 USERD_exit_routine
689 Description:
690 -----------
691 This routine is called as EnSight is exiting. It can be used to clean
692 up anything needed - such as removing temporary files, etc. - or can simply
693 be a dummy.
695 Specification:
696 -------------
697 void USERD_exit_routine( void )
699 Arguments:
700 ---------
701 none
703 --------------------------------------------------------------------
704 USERD_get_block_coords_by_component
706 Description:
707 -----------
708 Get the coordinates of a given structured block, a component at a time.
710 Specification:
711 -------------
712 int USERD_get_block_coords_by_component(int block_number,
713 int which_component,
714 float *coord_array)
716 Returns:
717 -------
718 Z_OK if successful
719 Z_ERR if not successful
721 Arguments:
722 ---------
723 (IN) block_number = The block part number
724 (1-based index of part table, namely:
726 1 ... Numparts_available.
728 It is NOT the part_id that
729 is loaded in USERD_get_gold_part_build_info)
731 (IN) which_component = Z_COMPX if x component wanted
732 = Z_COMPY if y component wanted
733 = Z_COMPZ if z component wanted
735 (OUT) coord_array = 1D array containing x,y, or z
736 coordinate component of each node
738 (Array will have been allocated
739 i*j*k for the block long)
741 Notes:
742 -----
743 * Not called unless Num_structured_blocks is > 0
745 * Will be based on Current_time_step
749 --------------------------------------------------------------------
750 USERD_get_block_iblanking
752 Description:
753 -----------
754 Get the iblanking value at each node of a block (if the block is
755 iblanked).
757 Specification:
758 -------------
759 int USERD_get_block_iblanking(int block_number,
760 int *iblank_array)
762 Returns:
763 -------
764 Z_OK if successful
765 Z_ERR if not successful
767 Arguments:
768 ---------
769 (IN) block_number = The block part number
770 (1-based index of part table, namely:
772 1 ... Numparts_available.
774 It is NOT the part_id that
775 is loaded in USERD_get_gold_part_build_info)
777 (OUT) iblank_array = 1D array containing iblank value
778 for each node.
780 (Array will have been allocated
781 i*j*k for the block long)
783 possible values are: Z_EXT = exterior
784 Z_INT = interior
785 Z_BND = boundary
786 Z_INTBND = internal boundary
787 Z_SYM = symmetry plane
789 Notes:
790 -----
791 * Not called unless Num_structured_blocks is > 0 and you have
792 some iblanked blocks
794 * Will be based on Current_time_step
798 ----------------------------------------------------------------------
799 USERD_get_block_ghost_flags
801 Description:
802 -----------
803 Get the ghost_flags value at each element of a block containing ghost cells.
805 Specification:
806 -------------
807 int USERD_get_block_ghost_flags(int block_number,
808 int *ghost_flags)
809 Returns:
810 -------
811 Z_OK if successful
812 Z_ERR if not successful
814 Arguments:
815 ---------
816 (IN) block_number = The block number
817 (1-based index of part table, namely:
819 1 ... Numparts_available.
821 It is NOT the part_id that
822 is loaded in USERD_get_gold_part_build_info)
824 (OUT) ghost_flags = 1D array containing ghost flag value
825 for each block cell.
827 (Array will have been allocated
828 (i-1)*(j-1)*(k-1) for the block long)
830 possible values are: 0 = non-ghost cell (normal cell)
831 >0 = ghost cell
833 Notes:
834 -----
835 * This routine is new in the 2.01 API
837 * This will be based on Current_time_step
839 * Only called for structured "block" parts that have some ghost cells
840 as indicated by the USERD_get_ghost_in_block_flag. The model must
841 of course also have been indicated to have some ghost cells in the
842 USERD_get_ghost_in_model_flag routine.
844 * It is sufficient to set the value to be 1 to flag as a ghost cell,
845 but the value can be any non-zero value, so you could use it to
846 indicate which block or which server (for Server-of-server use) the
847 cell is actually in.
851 --------------------------------------------------------------------
852 USERD_get_border_availability
854 Description:
855 -----------
856 Finds out if border elements are provided by the reader for the
857 desired part, or will need to be computed internally by EnSight.
859 Specification:
860 -------------
861 int USERD_get_border_availability(int part_number,
862 int number_of_elements[Z_MAXTYPE])
864 Returns:
865 -------
866 Z_OK if border elements will be provided by the reader.
867 (number_of_elements array will be loaded and
868 USERD_get_border_elements_by_type will be called)
870 Z_ERR if border elements are not available - thus EnSight must compute.
871 (USERD_get_border_elements_by_type will not be called)
874 Arguments:
875 ---------
876 (IN) part_number = The part number
877 (1-based index of part table, namely:
879 1 ... Numparts_available.
881 It is NOT the part_id that
882 is loaded in USERD_get_gold_part_build_info)
884 (OUT) number_of_elements = 2D array containing number of
885 each type of border element in
886 the part.
887 ------------
888 Possible types are:
890 Z_POINT = point
891 Z_BAR02 = 2-noded bar
892 Z_BAR03 = 3-noded bar
893 Z_TRI03 = 3-noded triangle
894 Z_TRI06 = 6-noded triangle
895 Z_QUA04 = 4-noded quadrilateral
896 Z_QUA08 = 8-noded quadrilateral
898 Notes:
899 -----
900 * Only called if border representation is used.
902 * Will be based on Current_time_step
906 --------------------------------------------------------------------
907 USERD_get_border_elements_by_type
909 Description:
910 -----------
911 Provides border element connectivity and parent information.
913 Specification:
914 -------------
915 int USERD_get_border_elements_by_type(int part_number,
916 int element_type,
917 int **conn_array,
918 short *parent_element_type,
919 int *parent_element_num)
921 Returns:
922 -------
923 Z_OK if successful
924 Z_ERR if not successful
926 Arguments:
927 ---------
928 (IN) part_number = The part number
929 (1-based index of part table, namely:
931 1 ... Numparts_available.
933 It is NOT the part_id that
934 is loaded in USERD_get_gold_part_build_info)
936 (IN) element_type = One of the following (See global_extern.h)
937 Z_POINT node point element
938 Z_BAR02 2 node bar
939 Z_BAR03 3 node bar
940 Z_TRI03 3 node triangle
941 Z_TRI06 6 node triangle
942 Z_QUA04 4 node quad
943 Z_QUA08 8 node quad
945 (OUT) conn_array = 2D array containing connectivity
946 of each border element of the type.
948 (Array will have been allocated
949 num_of_elements of the type by
950 connectivity length of the type)
952 ex) If number_of_elements[Z_TRI03] = 25
953 number_of_elements[Z_QUA04] = 100
954 number_of_elements[Z_QUA08] = 30
955 as obtained in:
956 USERD_get_border_availability
958 Then the allocated dimensions available
959 for this routine will be:
960 conn_array[25][3] when called with Z_TRI03
962 conn_array[100][4] when called with Z_QUA04
964 conn_array[30][8] when called with Z_QUA08
966 (OUT) parent_element_type = 1D array containing element type of the
967 parent element (the one that the border
968 element is a face/edge of).
970 (Array will have been allocated
971 num_of_elements of the type long)
973 (OUT) parent_element_num = 1D array containing element number of the
974 parent element (the one that the border
975 element is a face/edge of).
977 (Array will have been allocated
978 num_of_elements of the type long)
981 Notes:
982 -----
983 * Not called unless USERD_get_border_availability returned Z_OK
985 * Will be based on Current_time_step
989 --------------------------------------------------------------------
990 USERD_get_changing_geometry_status
992 Description:
993 -----------
994 Gets the changing geometry status for the model
996 Specification:
997 -------------
998 int USERD_get_changing_geometry_status( void )
1000 Returns:
1001 -------
1002 Z_STATIC if geometry does not change
1003 Z_CHANGE_COORDS if changing coordinates only
1004 Z_CHANGE_CONN if changing connectivity
1006 Arguments:
1007 ---------
1008 none
1010 Notes:
1011 -----
1012 * EnSight does not support changing number of parts. But the
1013 coords and/or the connectivity of the parts can change. Note that
1014 a part is allowed to be empty (number of nodes and elements equal
1015 to zero).
1018 --------------------------------------------------------------------
1019 USERD_get_constant_val
1021 Description:
1022 -----------
1023 Get the value of a constant at a time step
1025 Specification:
1026 -------------
1027 float USERD_get_constant_value(int which_var,
1028 int imag_data)
1030 Returns:
1031 -------
1032 Value of the requested constant variable
1034 Arguments:
1035 ---------
1036 (IN) which_var = The variable number
1038 (IN) imag_data = TRUE if want imaginary data value.
1039 FALSE if want real data value.
1041 Notes:
1042 -----
1043 * Will be based on Current_time_step
1047 --------------------------------------------------------------------
1048 USERD_get_dataset_query_file_info
1050 Description:
1051 -----------
1052 Get the information about files in the dataset. Used for the
1053 dataset query option within EnSight.
1055 Specification:
1056 -------------
1057 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
1059 Returns:
1060 -------
1061 Z_OK if successful
1062 Z_ERR if not successful
1064 Arguments:
1065 ---------
1066 (OUT) qfiles = Structure containing information about each file
1067 of the dataset. The Z_QFILES structure is defined
1068 in the global_extern.h file
1070 (The structure will have been allocated
1071 Num_dataset_files long, with 10 description
1072 lines per file).
1074 qfiles[].name = The name of the file
1075 (Z_MAXFILENP is the dimensioned length
1076 of the name)
1078 qfiles[].sizeb = The number of bytes in the file
1079 (Typically obtained with a call to the
1080 "stat" system routine) (Is a long)
1082 qfiles[].timemod = The time the file was last modified
1083 (Z_MAXTIMLEN is the dimensioned length
1084 of this string)
1085 (Typically obtained with a call to the
1086 "stat" system routine)
1088 qfiles[].num_d_lines = The number of description lines you
1089 are providing from the file. Max = 10
1091 qfiles[].f_desc[] = The description line(s) per file,
1092 qfiles[].num_d_lines of them
1093 (Z_MAXFILENP is the allocated length of
1094 each line)
1096 Notes:
1097 -----
1098 * If Num_dataset_files is 0, this routine will not be called.
1099 (See USERD_get_number_of_files_in_dataset)
1102 --------------------------------------------------------------------
1103 USERD_get_descrip_lines
1105 Description:
1106 -----------
1107 Get two description lines associated with geometry per time step,
1108 or one description line associated with a variable per time step.
1110 Specification:
1111 -------------
1112 int USERD_get_descrip_lines(int which_type,
1113 int which_var,
1114 int imag_data,
1115 char line1[Z_BUFL],
1116 char line2[Z_BUFL])
1118 Returns:
1119 -------
1120 Z_OK if successful
1121 Z_ERR if not successful
1123 Arguments:
1124 ---------
1125 (IN) which_type = Z_GEOM for geometry (2 lines)
1126 = Z_VARI for variable (1 line)
1128 (IN) which_var = If it is a variable, which one.
1129 Ignored if geometry type.
1131 (IN) imag_data = TRUE if want imaginary data file.
1132 FALSE if want real data file.
1134 (OUT) line1 = The 1st geometry description line,
1135 or the variable description line.
1137 (OUT) line2 = The 2nd geometry description line
1138 Not used if variable type.
1140 Notes:
1141 -----
1142 * Will be based on Current_time_step
1144 * These are the lines EnSight can echo to the screen in
1145 annotation mode.
1149 --------------------------------------------------------------------
1150 USERD_get_element_label_status
1152 Description:
1153 -----------
1154 Answers the question as to whether element labels will be provided.
1156 Specification:
1157 -------------
1158 int USERD_get_element_label_status( void )
1160 Returns:
1161 -------
1162 TRUE if element labels will be provided
1163 FALSE if element labels will NOT be provided
1165 Arguments:
1166 ---------
1167 none
1169 Notes:
1170 -----
1171 * element lables are needed in order to do any element querying, or
1172 element labeling on-screen within EnSight.
1174 * Prior to API 2.01:
1175 -----------------
1176 For unstructured parts, you can read them from your file if
1177 available, or can assign them, etc. They need to be unique
1178 per part, and are often unique per model.
1180 API 1.0:
1181 USERD_get_element_ids_for_part is used to obtain the ids,
1182 on a part by part basis, if TRUE status is returned here.
1184 API 2.0:
1185 USERD_get_part_element_ids_by_type is used to obtain the ids,
1186 on a per part, per type basis, if TRUE status is returned here.
1188 For structured parts, EnSight will assign ids if you return a
1189 status of TRUE here. You cannot assign them youself!!
1191 * Starting at API 2.01:
1192 --------------------
1193 For both unstructured and structured parts, you can read them
1194 from your file if available, or can assign them, etc. They need
1195 to be unique per part, and are often unique per model (especially
1196 if you are dealing with a decomposed dataset).
1198 USERD_get_part_element_ids_by_type is used to obtain the ids,
1199 on an element type by part basis, if TRUE status is returned here.
1201 * Will call USERD_get_part_element_ids_by_type for each type of
1202 of each part if this routine returns TRUE.
1203 --------------------------------------------------------------------
1204 USERD_get_geom_timeset_number -
1206 Description:
1207 -----------
1208 Gets the timeset number to be used for geometry
1210 Specification:
1211 -------------
1212 int USERD_get_geom_timeset_number( void )
1214 Returns:
1215 -------
1216 Geom_timeset_number = The timeset number that will be used for geometry.
1217 For example, if USERD_get_number_of timesets
1218 returns 2, the valid timeset numbers would be
1219 1 or 2.
1221 Arguments:
1222 ---------
1223 none
1225 Notes:
1226 -----
1227 * If your model is static, which you indicated by returning a zero
1228 in USERD_get_number_of_timesets, you can return a zero here as well.
1232 --------------------------------------------------------------------
1233 USERD_get_gold_part_build_info
1235 Description:
1236 -----------
1237 Gets the info needed for the part building process.
1239 Specification:
1240 -------------
1241 int USERD_get_gold_part_build_info(int *part_id,
1242 int *part_types,
1243 char *part_description[Z_BUFL],
1244 int *number_of_nodes,
1245 int *number_of_elements[Z_MAXTYPE],
1246 int *ijk_dimensions[9],
1247 int *iblanking_options[6])
1249 Returns:
1250 -------
1251 Z_OK if successful
1252 Z_ERR if not successful
1254 Arguments:
1255 ---------
1256 (OUT) part_id = Array containing the external part
1257 ids for each of the model parts.
1259 IMPORTANT:
1260 Parts numbers must be >= 1, because
1261 of the way they are used in the GUI
1263 *******************************************
1264 The ids provided here are the numbers by
1265 which the parts will be referred to in the
1266 GUI (if possible). They are basically
1267 labels as far as you are concerned.
1269 Note: The part numbers you pass to routines
1270 which receive a part_number or block_number
1271 or which_part as an argument are the 1-based
1272 table index of the parts!
1274 example: If Numparts_available = 3
1276 Table index part_id
1277 ----------- -------
1278 1 13
1279 2 57
1280 3 125
1282 ^ ^
1283 | |
1284 | These are placed in:
1285 | part_id[0] = 13
1286 | part_id[1] = 57
1287 | part_id[2] = 125
1288 | for GUI labeling purposes.
1289 |
1290 These implied table indices are the part_number,
1291 block_number, or which_part numbers that you would
1292 pass to routines like:
1294 USERD_get_part_coords(int part_number,...
1295 USERD_get_part_node_ids(int part_number,...
1296 USERD_get_part_elements_by_type(int part_number,...
1297 USERD_get_part_element_ids_by_type(int part_number,...
1298 USERD_get_block_coords_by_component(int block_number,...
1299 USERD_get_block_iblanking(int block_number,...
1300 USERD_get_block_ghost_flags(int block_number,...
1301 USERD_get_ghosts_in_block_flag(int block_number)
1302 USERD_get_border_availability(int part_number,...
1303 USERD_get_border_elements_by_type(int part_number,...
1304 USERD_get_var_by_component(int which_variable,
1305 int which_part,...
1306 USERD_get_var_value_at_specific(int which_var,
1307 int which_node_or_elem,
1308 int which_part,...
1309 ********************************************
1311 (Array will have been allocated
1312 Numparts_available long)
1314 (OUT) part_types = Array containing one of the
1315 following for each model part:
1317 Z_UNSTRUCTURED or
1318 Z_STRUCTURED or
1319 Z_IBLANKED
1321 (Array will have been allocated
1322 Numparts_available long)
1324 (OUT) part_description = Array containing a description
1325 for each of the model parts
1327 (Array will have been allocated
1328 Numparts_available by Z_BUFL
1329 long)
1331 (OUT) number_of_nodes = Number of unstructured nodes in the part
1333 (Array will have been allocated
1334 Numparts_available long)
1336 (OUT) number_of_elements = 2D array containing number of
1337 each type of element for each
1338 unstructured model part.
1339 ------------
1340 Possible types are:
1342 Z_POINT = point
1343 Z_BAR02 = 2-noded bar
1344 Z_BAR03 = 3-noded bar
1345 Z_TRI03 = 3-noded triangle
1346 Z_TRI06 = 6-noded triangle
1347 Z_QUA04 = 4-noded quadrilateral
1348 Z_QUA08 = 8-noded quadrilateral
1349 Z_TET04 = 4-noded tetrahedron
1350 Z_TET10 = 10-noded tetrahedron
1351 Z_PYR05 = 5-noded pyramid
1352 Z_PYR13 = 13-noded pyramid
1353 Z_PEN06 = 6-noded pentahedron
1354 Z_PEN15 = 15-noded pentahedron
1355 Z_HEX08 = 8-noded hexahedron
1356 Z_HEX20 = 20-noded hexahedron
1358 Z_G_POINT = ghost node point element
1359 Z_G_BAR02 = 2 node ghost bar
1360 Z_G_BAR03 = 3 node ghost bar
1361 Z_G_TRI03 = 3 node ghost triangle
1362 Z_G_TRI06 = 6 node ghost triangle
1363 Z_G_QUA04 = 4 node ghost quad
1364 Z_G_QUA08 = 8 node ghost quad
1365 Z_G_TET04 = 4 node ghost tetrahedron
1366 Z_G_TET10 = 10 node ghost tetrahedron
1367 Z_G_PYR05 = 5 node ghost pyramid
1368 Z_G_PYR13 = 13 node ghost pyramid
1369 Z_G_PEN06 = 6 node ghost pentahedron
1370 Z_G_PEN15 = 15 node ghost pentahedron
1371 Z_G_HEX08 = 8 node ghost hexahedron
1372 Z_G_HEX20 = 20 node ghost hexahedron
1374 (Ignored unless Z_UNSTRUCTURED type)
1376 (Array will have been allocated
1377 Numparts_available by
1378 Z_MAXTYPE long)
1380 (OUT) ijk_dimensions = 2D array containing ijk dimension info
1381 for structured blocks
1383 For Z_UNSTRUCTURED - is ignored
1385 For Z_STRUCTURED or Z_IBLANKED
1387 Prior to version 2.03:
1388 ----------------------
1389 (Array will have been allocated
1390 Numparts_available by 3 long)
1392 ijk_dimensions[][0] = I dimension
1393 ijk_dimensions[][1] = J dimension
1394 ijk_dimensions[][2] = K dimension
1397 Starting at version 2.03:
1398 ------------------------
1399 (Array will have been allocated
1400 Numparts_available by 9 long)
1402 There are two ways to do this:
1403 ------------------------------
1404 1. The simple one, without ranges.
1406 This is good for all structured models
1407 that will NOT be used in EnSight's
1408 Server of Servers
1410 Simply provide the ijk dimensions in the
1411 first three slots and place a -1 in
1412 the 4th slot. (The remaining slots will
1413 be ignored).
1415 Thus,
1416 ijk_dimensions[][0] = I dimension of block
1417 ijk_dimensions[][1] = J dimension of block
1418 ijk_dimensions[][2] = K dimension of block
1419 ijk_dimensions[][3] = -1
1421 (J planes)
1422 4 *-------*-------*
1423 | | | ijk_dimension[0][0] = 3
1424 | | | ijk_dimension[0][1] = 4
1425 | | | ijk_dimension[0][2] = 1
1426 3 *-------*-------*
1427 | | | ijk_dimension[0][4] = -1
1428 | | |
1429 | | |
1430 2 *-------*-------*
1431 | | |
1432 | | |
1433 | | |
1434 1 *-------*-------*
1435 1 2 3 (I planes)
1439 2. Using ranges.
1441 This one can be used anytime, but MUST
1442 be used if EnSight's Server of Servers
1443 is to be used!
1445 The first 3 slots contain the ijk dimension
1446 of the complete block (of which this may be
1447 a portion). The last 6 slots contain the
1448 ijk min and max ranges within the complete.
1450 Thus,
1451 ijk_dimensions[][0] = I dim of complete block
1452 ijk_dimensions[][1] = J dim of complete block
1453 ijk_dimensions[][2] = K dim of complete block
1455 ijk_dimensions[][3] = Imin of portion (1-based)
1456 ijk_dimensions[][4] = Imax of portion (1-based)
1457 ijk_dimensions[][5] = Jmin of portion (1-based)
1458 ijk_dimensions[][6] = Jmax of portion (1-based)
1459 ijk_dimensions[][7] = Kmin of portion (1-based)
1460 ijk_dimensions[][8] = Kmax of portion (1-based)
1463 example1: (Model has one part, a simple 2D block,
1464 and want whole thing)
1466 (J planes)
1467 4 *-------*-------*
1468 | | | ijk_dimension[0][0] = 3
1469 | | | ijk_dimension[0][1] = 4
1470 | | | ijk_dimension[0][2] = 1
1471 3 *-------*-------*
1472 | | | ijk_dimension[0][3] = 1
1473 | | | ijk_dimension[0][4] = 3
1474 | | | ijk_dimension[0][5] = 1
1475 2 *-------*-------* ijk_dimension[0][6] = 4
1476 | | | ijk_dimension[0][7] = 1
1477 | | | ijk_dimension[0][8] = 1
1478 | | |
1479 1 *-------*-------*
1480 1 2 3 (I planes)
1483 example2: (Want to have the block represented
1484 in two portions - 2 parts)
1486 (J planes) top portion
1487 4 *-------*-------*
1488 | | | ijk_dimension[0][0] = 3
1489 | | | ijk_dimension[0][1] = 4
1490 | | | ijk_dimension[0][2] = 1
1491 3 *-------*-------*
1492 . . . ijk_dimension[0][3] = 1
1493 . . . ijk_dimension[0][4] = 3
1494 . . . ijk_dimension[0][5] = 3
1495 2 ................. ijk_dimension[0][6] = 4
1496 . . . ijk_dimension[0][7] = 1
1497 . . . ijk_dimension[0][8] = 1
1498 . . .
1499 1 .................
1500 1 2 3 (I planes)
1503 (J planes) bottom portion
1504 4 .................
1505 . . . ijk_dimension[1][0] = 3
1506 . . . ijk_dimension[2][1] = 4
1507 . . . ijk_dimension[3][2] = 1
1508 3 *-------*-------*
1509 | | | ijk_dimension[1][3] = 1
1510 | | | ijk_dimension[1][4] = 3
1511 | | | ijk_dimension[1][5] = 1
1512 2 *-------*-------* ijk_dimension[1][6] = 3
1513 | | | ijk_dimension[1][7] = 1
1514 | | | ijk_dimension[1][8] = 1
1515 | | |
1516 1 *-------*-------*
1517 1 2 3 (I planes)
1520 And note that if you were partioning this block for
1521 EnSight's Server of Servers, you would only have one part,
1522 instead of two. Each SOS server would return its appropriate
1523 ranges in the last 6 slots. The first 3 slots would remain constant.
1526 (OUT) iblanking_options = 2D array containing iblanking
1527 options possible for each
1528 structured model part.
1529 ----------
1530 (Ignored unless Z_IBLANKED type)
1532 (Array will have been allocated
1533 Numparts_available by 6 long)
1535 iblanking_options[][Z_EXT] = TRUE if external (outside)
1536 [][Z_INT] = TRUE if internal (inside)
1537 [][Z_BND] = TRUE if boundary
1538 [][Z_INTBND] = TRUE if internal boundary
1539 [][Z_SYM] = TRUE if symmetry surface
1542 Notes:
1543 -----
1544 * If you haven't built a table of pointers to the different parts,
1545 you might want to do so here as you gather the needed info.
1547 * Will be based on Current_time_step
1550 --------------------------------------------------------------------
1551 USERD_get_gold_variable_info
1553 Description:
1554 -----------
1555 Get the variable descriptions, types and filenames
1557 Specification:
1558 -------------
1559 int USERD_get_gold_variable_info(char **var_description,
1560 char **var_filename,
1561 int *var_type,
1562 int *var_classify,
1563 int *var_complex,
1564 char **var_ifilename,
1565 float *var_freq,
1566 int *var_contran,
1567 int *var_timeset)
1569 Returns:
1570 -------
1571 Z_OK if successful
1572 Z_ERR if not successful
1574 Arguments:
1575 ---------
1576 (OUT) var_description = Variable descriptions
1578 (Array will have been allocated
1579 Num_variables by Z_BUFL long)
1581 variable description restrictions:
1582 ----------------------------------
1583 1. Only first 19 characters used in EnSight.
1584 2. Leading and trailing whitespace will be removed by EnSight.
1585 3. Illegal characters will be replaced by underscores.
1586 4. Thay may not start with a numeric digit.
1587 4. No two variables may have the same description.
1590 (OUT) var_filename = Variable real filenames
1592 (Array will have been allocated
1593 Num_variables by Z_BUFL long)
1595 (OUT) var_type = Variable type
1597 (Array will have been allocated
1598 Num_variables long)
1600 types are: Z_CONSTANT
1601 Z_SCALAR
1602 Z_VECTOR
1603 Z_TENSOR
1604 Z_TENSOR9
1606 (OUT) var_classify = Variable classification
1608 (Array will have been allocated
1609 Num_variables long)
1611 types are: Z_PER_NODE
1612 Z_PER_ELEM
1614 (OUT) var_complex = TRUE if complex, FALSE otherwise
1616 (Array will have been allocated
1617 Num_variables long)
1619 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1621 (Array will have been allocated
1622 Num_variables by Z_BUFL long)
1624 (OUT) var_freq = complex frequency (if complex)
1626 (Array will have been allocated
1627 Num_variables long)
1629 (OUT) var_contran = TRUE if constant changes per time step
1630 FALSE if constant truly same at all time steps
1632 (Array will have been allocated
1633 Num_variables long)
1635 (OUT) var_timeset = Timeset the variable will use (1 based).
1636 (For static models, set it to 1)
1638 (Array will have been allocated
1639 Num_variables long)
1641 For example: If USERD_get_number_of_timesets
1642 returns 2, the valid
1643 timeset_number's would be 1 or 2
1646 Notes:
1647 -----
1648 * The implied variable numbers apply, but be aware that the
1649 arrays are zero based.
1650 So for variable 1, will need to provide var_description[0]
1651 var_filename[0]
1652 var_type[0]
1653 var_classify[0]
1654 var_complex[0]
1655 var_ifilename[0]
1656 var_freq[0]
1657 var_contran[0]
1658 var_timeset[0]
1661 for variable 2, will need to provide var_description[1]
1662 var_filename[1]
1663 var_type[1]
1664 var_classify[1]
1665 var_complex[1]
1666 var_ifilename[1]
1667 var_freq[1]
1668 var_contran[1]
1669 var_timeset[1]
1670 etc.
1675 --------------------------------------------------------------------
1676 USERD_get_ghosts_in_block_flag
1678 Description:
1679 -----------
1680 Gets whether ghost cells present in block or not
1682 Specification:
1683 -------------
1684 int USERD_get_ghosts_in_block_flag(int block_number)
1686 Returns:
1687 -------
1688 TRUE if any ghost cells in this structured part
1689 FALSE if no ghost cells in this structured part
1691 Arguments:
1692 ---------
1693 (IN) block_number = The block part number
1694 (1-based index of part table, namely:
1696 1 ... Numparts_available.
1698 It is NOT the part_id that
1699 is loaded in USERD_get_gold_part_build_info)
1701 Notes:
1702 -----
1703 * This routine is new in the 2.01 API
1704 * This will be based on Current_time_step
1706 * Intended for structured parts only, value will be ignored for
1707 unstructured parts
1711 --------------------------------------------------------------------
1712 USERD_get_ghosts_in_model_flag
1714 Description:
1715 -----------
1716 Answers the question as to whether any ghost cells in the model.
1718 Specification:
1719 -------------
1720 int USERD_get_ghosts_in_model_flag( void )
1722 Returns:
1723 -------
1724 TRUE if any ghost cells in the model
1725 FALSE if no ghost cells in the model
1727 Arguments:
1728 ---------
1730 Notes:
1731 -----
1732 * This routine is new in the 2.01 API
1734 -------------------------------------------------------------------------
1735 USERD_get_matf_set_info
1737 Description:
1738 -----------
1739 Get the material set ids and names
1741 Specification:
1742 -------------
1743 int USERD_get_matf_set_info(int *mat_set_ids,
1744 char **mat_set_name)
1746 Returns:
1747 -------
1748 Z_OK if successful
1749 Z_ERR if not successful
1751 Arguments:
1752 ---------
1753 (OUT) mat_set_ids = 1D material set ids array
1755 (Array will have been allocated
1756 Num_material_sets long)
1758 (OUT) mat_set_name = 2D material set name array
1760 (Array will have been allocated
1761 Num_material_sets by Z_BUFL long)
1763 Notes:
1764 -----
1765 * Will not be called if Num_material_sets is zero
1766 * See USERD_get_number_of_material_sets header for explanatory example
1769 --------------------------------------------------------------------
1770 USERD_get_matf_var_info
1772 Description:
1773 -----------
1774 Gets the material ids and descriptions for the material set
1776 Specification:
1777 -------------
1778 int USERD_get_matf_var_info(int set_index,
1779 int *mat_ids,
1780 char **mat_desc)
1782 Returns:
1783 -------
1784 Z_OK if successful
1785 Z_ERR if not successful
1787 Arguments:
1788 ---------
1789 (IN) set_index = the material set index (zero based)
1791 (OUT) mat_ids[set_index] = 1D integer array containing the material
1792 ids to associated with each material
1794 (Array will have been allocated
1795 Num_materials[set_index] long)
1797 (OUT) mat_desc[set_index] = 2D char array containing the material
1798 descriptions to associated with each material
1800 (Array will have been allocated
1801 Num_materials[set_index] by Z_BUFL long)
1803 Notes:
1804 -----
1805 * See USERD_get_number_of_material_sets header for explanatory example
1806 * Will not be called if Num_material_sets is zero, or
1807 Num_materials[set_index] is zero
1812 --------------------------------------------------------------------
1813 USERD_get_maxsize_info
1815 Description:
1816 -----------
1817 Gets maximum part sizes for efficient memory allocation.
1819 Transient models (especially those that increase in size) can cause
1820 reallocations, at time step changes, to keep chewing up more and
1821 more memory. The way to avoid this is to know what the maximum
1822 size of such memory will be, and allocate for this maximum initially.
1824 Accordingly, if you choose to provide this information (it is optional),
1825 EnSight will take advantage of it.
1828 Specification:
1829 -------------
1830 int USERD_get_maxsize_info(int *max_number_of_nodes,
1831 int *max_number_of_elements[Z_MAXTYPE],
1832 int *max_ijk_dimensions[3])
1834 Returns:
1835 -------
1836 Z_OK if supplying maximum data
1837 Z_ERR if not supplying maximum data, or some error occurred
1838 while trying to obtain it.
1840 Arguments:
1841 ---------
1842 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1843 in the part (over all time).
1845 (Array will have been allocated
1846 Numparts_available long)
1848 (OUT) max_number_of_elements = 2D array containing maximum number of
1849 each type of element for each
1850 unstructured model part (over all time).
1851 ------------
1852 Possible types are:
1854 Z_POINT = point
1855 Z_BAR02 = 2-noded bar
1856 Z_BAR03 = 3-noded bar
1857 Z_TRI03 = 3-noded triangle
1858 Z_TRI06 = 6-noded triangle
1859 Z_QUA04 = 4-noded quadrilateral
1860 Z_QUA08 = 8-noded quadrilateral
1861 Z_TET04 = 4-noded tetrahedron
1862 Z_TET10 = 10-noded tetrahedron
1863 Z_PYR05 = 5-noded pyramid
1864 Z_PYR13 = 13-noded pyramid
1865 Z_PEN06 = 6-noded pentahedron
1866 Z_PEN15 = 15-noded pentahedron
1867 Z_HEX08 = 8-noded hexahedron
1868 Z_HEX20 = 20-noded hexahedron
1870 Z_G_POINT = ghost node point element
1871 Z_G_BAR02 = 2 node ghost bar
1872 Z_G_BAR03 = 3 node ghost bar
1873 Z_G_TRI03 = 3 node ghost triangle
1874 Z_G_TRI06 = 6 node ghost triangle
1875 Z_G_QUA04 = 4 node ghost quad
1876 Z_G_QUA08 = 8 node ghost quad
1877 Z_G_TET04 = 4 node ghost tetrahedron
1878 Z_G_TET10 = 10 node ghost tetrahedron
1879 Z_G_PYR05 = 5 node ghost pyramid
1880 Z_G_PYR13 = 13 node ghost pyramid
1881 Z_G_PEN06 = 6 node ghost pentahedron
1882 Z_G_PEN15 = 15 node ghost pentahedron
1883 Z_G_HEX08 = 8 node ghost hexahedron
1884 Z_G_HEX20 = 20 node ghost hexahedron
1886 (Ignored unless Z_UNSTRUCTURED type)
1888 (Array will have been allocated
1889 Numparts_available by
1890 Z_MAXTYPE long)
1892 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1893 for each structured model part (over all time).
1894 ----------
1895 (Ignored if Z_UNSTRUCTURED type)
1897 (Array will have been allocated
1898 Numparts_available by 3 long)
1900 max_ijk_dimensions[][0] = maximum I dimension
1901 max_ijk_dimensions[][1] = maximum J dimension
1902 max_ijk_dimensions[][2] = maximum K dimension
1904 Notes:
1905 -----
1906 * You need to have first called USERD_get_number_of_model_parts and
1907 USERD_get_gold_part_build_info, so Numparts_available is known and
1908 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1909 or Z_IBLANKED) of each part.
1911 * This will NOT be based on Current_time_step - it is to be the maximum
1912 values over all time!!
1914 * This information is optional. If you return Z_ERR, Ensight will still
1915 process things fine, reallocating as needed, etc. However, for
1916 large transient models you will likely use considerably more memory
1917 and take more processing time for the memory reallocations. So, if it
1918 is possible to provide this information "up front", it is recommended
1919 to do so.
1922 --------------------------------------------------------------------
1923 USERD_get_model_extents
1925 Description:
1926 -----------
1927 Gets the model bounding box extents. If this routine supplys them
1928 EnSight will not have to spend time doing so. If this routine
1929 returns Z_ERR, EnSight will have to take the time to touch all the
1930 nodes and gather the extent info.
1932 Specification:
1933 -------------
1934 int USERD_get_model_extents(float extents[6])
1936 Returns:
1937 -------
1938 Z_OK if successful
1939 Z_ERR if not successful (whereupon EnSight will determine by reading
1940 all coords of all parts)
1942 Arguments:
1943 ---------
1944 (OUT) extents[0] = min x
1945 [1] = max x
1946 [2] = min y
1947 [3] = max y
1948 [4] = min z
1949 [5] = max z
1951 Notes:
1952 -----
1953 * This will be based on Current_time_step
1956 --------------------------------------------------------------------
1957 USERD_get_name_of_reader
1959 Description:
1960 -----------
1961 Gets the name of your user defined reader. The user interface will
1962 ask for this and include it in the available reader list.
1964 Specification:
1965 -------------
1966 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1967 int *two_fields)
1969 Returns:
1970 -------
1971 Z_OK if successful
1972 Z_ERR if not successful
1974 Arguments:
1975 ---------
1976 (OUT) reader_name = the name of the your reader or data format.
1977 (max length is Z_MAX_USERD_NAME, which is 20)
1979 (OUT) two_fields = FALSE if only one data field is
1980 required.
1981 TRUE if two data fields required
1983 -1 if one field (Geom) required
1984 and one field (Param) is optional
1985 Param field can contain any text
1986 for example a file name, modifiers,
1987 etc. that can be used to modify the
1988 reader's behavior.
1991 Notes:
1992 -----
1993 * Always called. Please be sure to provide a name for your custom
1994 reader format.
1996 --------------------------------------------------------------------
1997 USERD_get_nfaced_conn
1999 Description:
2000 -----------
2001 Gets the array containing the connectivity of nsided faces of nfaced elements
2003 Specification:
2004 -------------int
2005 int USERD_get_nfaced_conn(int part_number,
2006 int *nfaced_conn_array)
2008 Returns:
2009 -------
2010 Z_OK if successful
2011 Z_ERR if not successful
2013 Arguments:
2014 ---------
2015 (IN) part_number = the part number
2017 (OUT) nfaced_conn_array = 1D array of nsided face connectivies of nfaced
2018 elements
2020 (int array will have been allocated long enough to
2021 hold all the nsided face connectivities. Which is
2022 the sum of all the nodes per face values in the
2023 nfaced_npf_array of USERD_get_nfaced_nodes_per_face)
2025 Notes:
2026 -----
2027 * Will not be called unless there are some nfaced elements in the part
2029 * Providing nfaced information to Ensight:
2031 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2032 polyhedral elements in the part.
2034 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2035 the number of faces per nfaced element. (as if connectivity
2036 length of an nfaced element is one)
2038 3. In this routine, provide the streamed number of nodes per face
2039 for each of the faces of the nfaced elements.
2042 Simple example: 11 10 12
2043 +--------+-----+
2044 2 nfaced elements: /| |\ /|
2045 (1 7-faced / | | \ / |
2046 1 5-sided) / | | +9 |
2047 / | | /| |
2048 /7 | 8 / | |
2049 +-----------+/ | | |
2050 | |5 | |4 | |6
2051 | +-----|--+--|--+
2052 | / | \ | /
2053 | / | \|/3
2054 | / | +
2055 | / | /
2056 |/1 |2 /
2057 +-----------+/
2059 1. In USERD_get_gold_part_build_info:
2060 number_of_elements[Z_NFACED] = 2
2061 .
2062 /|\
2063 |
2064 2. In USERD_get_part_elements_by_type:
2065 length of conn_array will be: 2 x 1
2066 for element_type of Z_NFACED:
2067 conn_array[0][0] = 7 (for the 7-faced element)
2068 conn_array[1][0] = 5 (for the 5-faced element)
2070 ==
2071 Sum 12 <---------+
2072 |
2073 3. In USERD_get_faced_nodes_per_face: |
2074 length of nfaced_npf_array will be: 12
2076 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2077 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2078 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2079 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2080 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2081 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2082 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2084 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2085 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2086 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2087 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2088 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2090 ==
2091 Sum 48 <-------------+
2092 |
2093 4. In this function: |
2094 length of the nfaced_conn_array will be: 48
2096 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2097 nsided_conn_array[1] = 8
2098 nsided_conn_array[2] = 9
2099 nsided_conn_array[3] = 10
2100 nsided_conn_array[4] = 11
2102 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2103 nsided_conn_array[6] = 5
2104 nsided_conn_array[7] = 4
2105 nsided_conn_array[8] = 3
2106 nsided_conn_array[9] = 2
2108 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2109 nsided_conn_array[11] = 2
2110 nsided_conn_array[12] = 8
2111 nsided_conn_array[13] = 7
2113 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2114 nsided_conn_array[15] = 1
2115 nsided_conn_array[16] = 7
2116 nsided_conn_array[17] = 11
2118 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2119 nsided_conn_array[19] = 5
2120 nsided_conn_array[20] = 11
2121 nsided_conn_array[21] = 10
2123 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2124 nsided_conn_array[23] = 3
2125 nsided_conn_array[24] = 9
2126 nsided_conn_array[25] = 8
2128 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2129 nsided_conn_array[27] = 4
2130 nsided_conn_array[28] = 10
2131 nsided_conn_array[29] = 9
2133 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2134 nsided_conn_array[32] = 12
2135 nsided_conn_array[32] = 10
2137 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2138 nsided_conn_array[34] = 4
2139 nsided_conn_array[35] = 6
2141 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2142 nsided_conn_array[37] = 4
2143 nsided_conn_array[38] = 10
2144 nsided_conn_array[39] = 12
2146 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2147 nsided_conn_array[41] = 6
2148 nsided_conn_array[42] = 12
2149 nsided_conn_array[43] = 9
2151 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2152 nsided_conn_array[45] = 3
2153 nsided_conn_array[46] = 9
2154 nsided_conn_array[47] = 10
2158 --------------------------------------------------------------------
2159 USERD_get_nfaced_nodes_per_face -
2161 Description:
2162 -----------
2163 Gets the array containing the number of nodes per face for each face
2164 of the nfaced elements.
2166 Specification:
2167 -------------
2168 int USERD_get_nfaced_nodes_per_face(int part_number,
2169 int *nfaced_npf_array)
2171 Returns:
2172 -------
2173 Z_OK if successful
2174 Z_ERR if not successful
2176 Arguments:
2177 ---------
2178 (IN) part_number = the part number
2180 (OUT) nfaced_npf_array = 1D array of nodes per face for all faces of
2181 nfaced elements
2183 (int array will have been allocated long enough
2184 to hold all the nodes_per_face values. Which is
2185 the sum of all the number of faces per element
2186 values in the conn_array of
2187 USERD_get_part_elements_by_type)
2189 Notes:
2190 -----
2191 * Will not be called unless there are some nfaced elements in the
2192 the part
2194 * Providing nfaced information to Ensight:
2196 1. In USERD_get_gold_part_build_info, provide the number of nfaced
2197 polyhedral elements in the part.
2199 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2200 the number of faces per nfaced element. (as if connectivity
2201 length of an nfaced element is one)
2203 3. In this routine, provide the streamed number of nodes per face
2204 for each of the faces of the nfaced elements.
2207 Simple example: 11 10 12
2208 +--------+-----+
2209 2 nfaced elements: /| |\ /|
2210 (1 7-faced / | | \ / |
2211 1 5-sided) / | | +9 |
2212 / | | /| |
2213 /7 | 8 / | |
2214 +-----------+/ | | |
2215 | |5 | |4 | |6
2216 | +-----|--+--|--+
2217 | / | \ | /
2218 | / | \|/3
2219 | / | +
2220 | / | /
2221 |/1 |2 /
2222 +-----------+/
2224 1. In USERD_get_gold_part_build_info:
2225 number_of_elements[Z_NFACED] = 2
2226 .
2227 /|\
2228 |
2229 2. In USERD_get_part_elements_by_type:
2230 length of conn_array will be: 2 x 1
2231 for element_type of Z_NFACED:
2232 conn_array[0][0] = 7 (for the 7-faced element)
2233 conn_array[1][0] = 5 (for the 5-faced element)
2235 ==
2236 Sum 12 <---------+
2237 |
2238 3. In this routine: |
2239 length of nfaced_npf_array will be: 12
2241 nfaced_npf_array[0] = 5 (5-noded top face of 7-faced element)
2242 nfaced_npf_array[1] = 5 (5-noded bot face of 7-faced element)
2243 nfaced_npf_array[2] = 4 (4-noded front face of 7-faced element)
2244 nfaced_npf_array[3] = 4 (4-noded left face of 7-faced element)
2245 nfaced_npf_array[4] = 4 (4-noded back face of 7-faced element)
2246 nfaced_npf_array[5] = 4 (4-noded right front face of 7-faced element)
2247 nfaced_npf_array[6] = 4 (4-noded right back face of 7-faced element)
2249 nfaced_npf_array[7] = 3 (3-noded top face of 5-faced element)
2250 nfaced_npf_array[8] = 3 (3-noded bot face of 5-faced element)
2251 nfaced_npf_array[9] = 4 (4-noded back face of 5-faced element)
2252 nfaced_npf_array[10] = 4 (4-noded right face of 5-faced element)
2253 nfaced_npf_array[11] = 4 (4-noded left front face of 5-faced element)
2255 ==
2256 Sum 48 <-------------+
2257 |
2258 4. In USERD_get_nfaced_conn: |
2259 length of the nfaced_conn_array will be: 48
2261 nsided_conn_array[0] = 7 (conn of 5-noded top face of 7-faced elem)
2262 nsided_conn_array[1] = 8
2263 nsided_conn_array[2] = 9
2264 nsided_conn_array[3] = 10
2265 nsided_conn_array[4] = 11
2267 nsided_conn_array[5] = 1 (conn of 5-noded bot face of 7-faced elem)
2268 nsided_conn_array[6] = 5
2269 nsided_conn_array[7] = 4
2270 nsided_conn_array[8] = 3
2271 nsided_conn_array[9] = 2
2273 nsided_conn_array[10] = 1 (conn of 4-noded front face of 7-faced elem)
2274 nsided_conn_array[11] = 2
2275 nsided_conn_array[12] = 8
2276 nsided_conn_array[13] = 7
2278 nsided_conn_array[14] = 5 (conn of 4-noded left face of 7-faced elem)
2279 nsided_conn_array[15] = 1
2280 nsided_conn_array[16] = 7
2281 nsided_conn_array[17] = 11
2283 nsided_conn_array[18] = 4 (conn of 4-noded back face of 7-faced elem)
2284 nsided_conn_array[19] = 5
2285 nsided_conn_array[20] = 11
2286 nsided_conn_array[21] = 10
2288 nsided_conn_array[22] = 2 (conn of 4-noded right front face of 7-faced)
2289 nsided_conn_array[23] = 3
2290 nsided_conn_array[24] = 9
2291 nsided_conn_array[25] = 8
2293 nsided_conn_array[26] = 3 (conn of 4-noded right back face of 7-faced)
2294 nsided_conn_array[27] = 4
2295 nsided_conn_array[28] = 10
2296 nsided_conn_array[29] = 9
2298 nsided_conn_array[30] = 9 (conn of 3-noded top face of 5-faced elem)
2299 nsided_conn_array[32] = 12
2300 nsided_conn_array[32] = 10
2302 nsided_conn_array[33] = 3 (conn of 3-noded bot face of 5-faced elem)
2303 nsided_conn_array[34] = 4
2304 nsided_conn_array[35] = 6
2306 nsided_conn_array[36] = 6 (conn of 4-noded back face of 5-faced elem)
2307 nsided_conn_array[37] = 4
2308 nsided_conn_array[38] = 10
2309 nsided_conn_array[39] = 12
2311 nsided_conn_array[40] = 3 (conn of 4-noded right face of 5-faced elem)
2312 nsided_conn_array[41] = 6
2313 nsided_conn_array[42] = 12
2314 nsided_conn_array[43] = 9
2316 nsided_conn_array[44] = 4 (conn of 4-noded left front face of 5-faced)
2317 nsided_conn_array[45] = 3
2318 nsided_conn_array[46] = 9
2319 nsided_conn_array[47] = 10
2324 --------------------------------------------------------------------
2325 USERD_get_node_label_status
2327 Description:
2328 -----------
2329 Answers the question as to whether node labels will be provided.
2331 Specification:
2332 -------------
2333 int USERD_get_node_label_status( void )
2335 Returns:
2336 -------
2337 TRUE if node labels will be provided
2338 FALSE if node labels will NOT be provided
2340 Arguments:
2341 ---------
2342 none
2344 Notes:
2345 -----
2346 * Node ids are needed in order to do any node querying, or node
2347 labeling on-screen within EnSight.
2349 * Prior to API 2.01:
2350 -----------------
2351 For unstructured parts, you can read them from your file if
2352 available, or can assign them, etc. They need to be unique
2353 per part, and are often unique per model. They must also be
2354 positive numbers greater than zero.
2356 USERD_get_part_node_ids is used to obtain the ids, if the
2357 status returned here is TRUE.
2359 (Unlike API 1.0, where the connectivity of elements had to be
2360 according to the node ids - API 2.0's element connectivities
2361 are not affected either way by the status here.)
2363 For structured parts, EnSight will assign ids if you return a
2364 status of TRUE here. You cannot assign them yourself!!
2366 * Starting at API 2.01:
2367 --------------------
2368 For both unstructured and structured parts, you can read them
2369 from your file if available, or can assign them, etc. They need
2370 to be unique per part, and are often unique per model. They must
2371 also be positive numbers greater than zero.
2373 USERD_get_part_node_ids is used to obtain the ids, if the
2374 status returned here is TRUE.
2376 * Will call USERD_get_part_node_ids for each part if this routine
2377 returns TRUE.
2379 --------------------------------------------------------------------
2380 USERD_get_nsided_conn -
2382 Description:
2383 -----------
2384 Gets the array containing the connectivity of nsided elements
2386 Specification:
2387 -------------
2388 int USERD_get_nsided_conn(int part_number,
2389 int *nsided_conn_array)
2391 Returns:
2392 -------
2393 Z_OK if successful
2394 Z_ERR if not successful
2396 Arguments:
2397 ---------
2398 (IN) part_number = the part number
2400 (OUT) nsided_conn_array = 1D array of nsided connectivies
2402 (int array will have been allocated long enough
2403 to hold all the nsided connectivities. Which is
2404 the sum of all the nodes_per_element values in
2405 the conn_array of USERD_get_part_elements_by_type)
2408 Notes:
2409 -----
2410 * Will not be called unless there are some nsided elements in the the part.
2412 * Providing nsided information to Ensight:
2414 1. In USERD_get_gold_part_build_info, provide the number of nsided
2415 elements in the part.
2417 2. In USERD_get_part_elements_by_type, provide (in the conn_array),
2418 the number of nodes per nsided element. (as if connectivity
2419 length of an nsided element is one)
2421 3. In this routine, provide the streamed connectivities for each of the
2422 nsided elements.
2425 Simple example: 5 6
2426 +--------+
2427 3 nsided elements: /| \
2428 (1 4-sided / | \
2429 1 3-sided / | \
2430 1 7-sided) / | \ 7
2431 /3 |4 +
2432 +-----+ |
2433 | | |
2434 | | |8
2435 | | +
2436 | | /
2437 | | /
2438 | | /
2439 |1 |2 /9
2440 +-----+--------+
2442 1. In USERD_get_gold_part_build_info:
2443 number_of_elements[Z_NSIDED] = 3
2444 .
2445 /|\
2446 |
2447 2. In USERD_get_part_elements_by_type:
2448 length of conn_array will be: 3 x 1
2450 for element_type of Z_NSIDED:
2451 conn_array[0][0] = 4 (for the 4-sided element)
2452 conn_array[1][0] = 3 (for the 3-sided element)
2453 conn_array[2][0] = 7 (for the 7-sided element)
2455 Sum ===
2456 14 <---------+
2457 |
2458 3. In this routine: |
2459 length of nsided_conn_array will be: 14
2461 nsided_conn_array[0] = 1 (connectivity of 4-sided element)
2462 nsided_conn_array[1] = 2
2463 nsided_conn_array[2] = 4
2464 nsided_conn_array[3] = 3
2466 nsided_conn_array[4] = 3 (connectivity of 3-sided element)
2467 nsided_conn_array[5] = 4
2468 nsided_conn_array[6] = 5
2470 nsided_conn_array[7] = 2 (connectivity of 7-sided element)
2471 nsided_conn_array[8] = 9
2472 nsided_conn_array[9] = 8
2473 nsided_conn_array[10] = 7
2474 nsided_conn_array[11] = 6
2475 nsided_conn_array[12] = 5
2476 nsided_conn_array[13] = 4
2481 --------------------------------------------------------------------
2482 USERD_get_num_of_time_steps
2484 Description:
2485 -----------
2486 Gets the number of time steps of data available for desired timeset.
2488 Specification:
2489 -------------
2490 int USERD_get_num_of_time_steps( int timeset_number )
2492 Returns:
2493 -------
2494 Number of time steps in timeset (>0 if okay, <=0 if problems).
2496 Arguments:
2497 ---------
2498 (IN) timeset number = the timeset number
2500 For example: If USERD_get_number_of_timesets
2501 returns 2, the valid
2502 timeset_number's would be 1 and 2
2504 Notes:
2505 -----
2506 * This should be >= 1 1 indicates a static model
2507 >1 indicates a transient model
2509 * Num_time_steps[timeset_number] would be set here
2513 --------------------------------------------------------------------
2514 USERD_get_number_of_files_in_dataset
2516 Description:
2517 -----------
2518 Get the total number of files in the dataset. Used for the
2519 dataset query option within EnSight.
2521 Specification:
2522 -------------
2523 int USERD_get_number_of_files_in_dataset( void )
2525 Returns:
2526 -------
2527 The total number of files in the dataset.
2529 Arguments:
2530 ---------
2531 none
2533 Notes:
2534 -----
2535 * You can be as complete as you want about this. If you don't
2536 care about the dataset query option, return a value of 0
2537 If you only want certain files, you can just include them. But,
2538 you will need to supply the info in USERD_get_dataset_query_file_info
2539 for each file you include here.
2541 * Num_dataset_files would be set here
2544 --------------------------------------------------------------------
2545 USERD_get_number_of_material_sets -
2547 Description:
2548 -----------
2549 Get the number of material sets in the model
2551 Specification:
2552 -------------
2553 int USERD_get_number_of_material_sets( void )
2556 Returns:
2557 -------
2558 Num_material_sets = number of material sets
2559 (Zero would indicate that you have no materials
2560 to deal with in the model)
2562 or
2564 -1 if an error condition
2566 Arguments:
2567 ---------
2568 none
2570 Notes:
2571 -----
2572 * You may want to keep this as a global for use in other routines.
2574 ###############################################################
2575 NOTE: For EnSight 7.6, only one material set is supported
2576 within EnSight.
2577 Thus the only valid returns here are:
2578 0 (no materials)
2579 1 (for the one material set allowed)
2580 or -1 (if an error)
2582 If the casefile has more than this, this reader will
2583 read them, but EnSight will issue an error message and
2584 choke on them!
2585 ###############################################################
2587 ================================================================
2588 A very simple explanatory example, to use as a reference for the
2589 materials routines:
2591 Given a 2D mesh composed of 9 quad (Z_QUA04) elements, with two materials.
2592 Most of the model is material 1, but the top left corner is material 9 -
2593 basically as shown:
2596 *--------*--------*--------*
2597 | | / | |
2598 | Mat 9 / | |
2599 | | / | |
2600 | |/ | |
2601 | e7 / e8 | e9 |
2602 | /| | |
2603 | / | | |
2604 | / | | |
2605 *----/---*--------*--------*
2606 | / | | |
2607 | / | | |
2608 | / | Mat 1 |
2609 |/ | | |
2610 | e4 | e5 | e6 |
2611 | | | |
2612 | | | |
2613 | | | |
2614 *--------*--------*--------*
2615 | | | |
2616 | | | |
2617 | | | |
2618 | | | |
2619 | e1 | e2 | e3 |
2620 | | | |
2621 | | | |
2622 | | | |
2623 *--------*--------*--------*
2626 Thus, in this routine, set:
2627 Num_material_sets = 1
2629 In USERD_get_matf_set_info, set:
2630 mat_set_ids[0] = 1
2631 mat_set_name[0] = "Material Set 1" (or whatever name desired)
2633 In USERD_get_number_of_materials, input would be set_index = 0, and
2634 would need to set:
2635 Num_materials[0] = 2
2637 For simplicity, the ids and descriptions that would be returned in
2638 USERD_get_matf_var_info could be:
2639 mat_ids[0] = 1
2640 mat_ids[1] = 9
2641 mat_desc[0] = "mat 1" (or whatever desired)
2642 mat_desc[2] = "mat 9"
2644 The per element material ids list would need to be:
2646 material ids:
2647 -------------
2648 ids_list[0] = 1 (material id 1, for elem e1)
2649 ids_list[1] = 1 ( " e2)
2650 ids_list[2] = 1 ( " e3)
2651 ids_list[3] = -1 (negative of index into mixed-material id list, for elem e4)
2652 ids_list[5] = 1 (material id 1, for elem e5)
2653 ids_list[5] = 1 ( " e6)
2654 ids_list[5] = -5 (negative of index into mixed-material id list, for elem e7)
2655 ids_list[5] = -9 ( " e8)
2656 ids_list[5] = 1 (material id 1, for elem e9)
2658 Finally we need the mixed material ids list and the mixed materials values list,
2659 which would need to be:
2661 mixed-material ids:
2662 -------------------
2663 ==> 1 ids_list[0] = 2 (the -1 in the material variable points here,
2664 2 indicates that two materials are present)
2665 2 ids_list[1] = 1 (1st material is 1)
2666 3 ids_list[2] = 9 (2nd material is 9)
2667 4 ids_list[3] = -1 (negative of index into mixed-material val_list)
2668 ==> 5 ids_list[4] = 2 (the -5 in the material variable points here,
2669 2 indicates that two materials are present)
2670 6 ids_list[5] = 1 (1st material is 1)
2671 7 ids_list[6] = 9 (2nd material is 9)
2672 8 ids_list[7] = -3 (negative of index into mixed-material val_list)
2673 ==> 9 ids_list[8] = 2 etc.
2674 10 ids_list[9] = 1
2675 11 ids_list[10] = 9
2676 12 ids_list[11] = -5
2678 mixed-material values:
2679 ----------------------
2680 ==> 1 val_list[0] = 0.875 (the -1 in the mixed-material ids_list points here,
2681 and this is the value for material 1)
2682 2 val_list[1] = 0.125 (the value for material 9)
2683 ==> 3 val_list[2] = 0.125 (the -3 in the mixed-materials ids_list points here)
2684 4 val_list[3] = 0.875
2685 ==> 5 val_list[4] = 0.875 (the -5 in the mixed-materials ids_list points here)
2686 6 val_list[5] = 0.125
2688 So, USERD_size_matf_data would need to return
2689 matf_size = 8, when called with set_id = 1
2690 part_id = 1
2691 wtyp = Z_QUA04
2692 mat_type = Z_MAT_INDEX
2694 matf_size = 12, when called with set_id = 1
2695 part_id = 1
2696 mat_type = Z_MIX_INDEX
2698 = 6, when called with set_id = 1
2699 part_id = 1
2700 mat_type = Z_MIX_VALUE
2702 And, USERD_load_matf_data would need to return:
2703 the int array ids_list as shown above when called with:
2704 set_id = 1
2705 part_id = 1
2706 wtyp = Z_QUA04
2707 mat_type = Z_MAT_INDEX (indicating id list).
2709 the int array ids_list as shown above when called with:
2710 set_id = 1
2711 part_id = 1
2712 mat_type = Z_MIX_INDEX (indicating id list).
2714 the float array val_list as shown above when called with:
2715 set_id = 1
2716 part_id = 1
2717 mat_type = Z_MIX_VALUE (indicating val list).
2720 -------------------------------------------------------------------------
2721 USERD_get_number_of_materials
2723 Description:
2724 -----------
2725 Gets the number of materials in the material set
2727 Specification:
2728 -------------
2729 int USERD_get_number_of_materials( int set_index )
2731 Returns:
2732 -------
2733 Num_materials[set_index] = Number of materials in the set
2734 0 indicates no materials information present
2735 -1 indicates an error
2736 Arguments:
2737 ---------
2738 (IN) set_index = the material set index (zero based)
2740 Notes:
2741 -----
2742 * See USERD_get_number_of_material_sets header for explanatory example
2743 * Will not be called if Num_material_sets is zero
2744 * You may want to keep this as a global for use in other routines.
2748 --------------------------------------------------------------------
2749 USERD_get_number_of_model_parts
2751 Description:
2752 -----------
2753 Gets the total number of unstructured and structured parts
2754 in the model, for which you can supply information.
2756 Specification:
2757 -------------
2758 int USERD_get_number_of_model_parts( void )
2760 Returns:
2761 -------
2762 Number of parts (>0 if okay, <=0 if problems).
2764 Arguments:
2765 ---------
2766 none
2768 Notes:
2769 -----
2770 * If going to have to read down through the parts in order to
2771 know how many, you may want to build a table of pointers to
2772 the various parts, so you can easily get to particular parts in
2773 later processes. If you can simply read the number of parts
2774 at the head of the file, then you would probably not build the
2775 table at this time.
2777 * This routine would set Numparts_available, which is equal to
2778 Num_unstructured_parts + Num_structured_blocks.
2782 --------------------------------------------------------------------
2783 USERD_get_number_of_timesets
2785 Description:
2786 -----------
2787 Gets the number of timesets used in the model.
2789 Specification:
2790 -------------
2791 int USERD_get_number_of_timesets( void )
2793 Returns:
2794 -------
2795 Number of timesets in the model
2797 Arguments:
2798 ---------
2799 none
2801 Notes:
2802 -----
2803 * Num_timesets would be set here
2805 * If you have a static model, both geometry and variables, you should
2806 return a value of zero.
2808 * If you have a transient model, then you should return one or more.
2810 For example:
2812 Geometry Variables No. of timesets
2813 --------- ------------------------------ ---------------
2814 static static 0
2815 static transient, all using same timeset 1
2817 transient transient, all using same timeset as geom 1
2819 static transient, using 3 different timesets 3
2821 transient transient, using 3 different timesets and
2822 none of them the same as the
2823 geometry timeset 4
2824 etc.
2826 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
2827 the timeset number to use
2828 for geometry in:
2829 USERD_get_geom_timeset_number
2831 Variables can use the same timeset as the geometry, or can use
2832 other timesets. More than one variable can use the same timeset.
2834 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
2835 variable 1 provided at these same five steps
2836 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
2838 This routine should return a value of 2, because only
2839 two different timesets are needed. Timeset 1 would be for the
2840 geometry and variable 1 (they both use it). Timeset 2 would
2841 be for variable 2, which needs its own in this case.
2847 --------------------------------------------------------------------
2848 USERD_get_number_of_variables
2850 Description:
2851 -----------
2852 Get the number of variables for which you will be providing info.
2854 Specification:
2855 -------------
2856 int USERD_get_number_of_variables( void )
2858 Returns:
2859 -------
2860 Number of variables (includes constant, scalar, vector and tensor types)
2861 (>=0 if okay, <0 if problem)
2863 Arguments:
2864 ---------
2865 none
2867 Notes:
2868 -----
2869 *****************************************************************
2870 * Variable numbers, by which references will be made, are implied
2871 here. If you say there are 3 variables, the variable numbers
2872 will be 1, 2, and 3.
2873 *****************************************************************
2875 * Num_variables would be set here
2879 --------------------------------------------------------------------
2880 USERD_get_part_coords
2882 Description:
2883 -----------
2884 Gets the coordinates for an unstructured part.
2886 Specification:
2887 -------------
2888 int USERD_get_part_coords(int part_number, float **coord_array)
2890 Returns:
2891 -------
2892 Z_OK if successful
2893 Z_ERR if not successful
2895 Arguments:
2896 ---------
2897 (IN) part_number = The part number
2898 (1-based index of part table, namely:
2900 1 ... Numparts_available.
2902 It is NOT the part_id that
2903 is loaded in USERD_get_gold_part_build_info)
2905 (OUT) coord_array = 2D float array which contains,
2906 x,y,z coordinates of each node
2907 in the part.
2909 (IMPORTANT: The second dimension of this aray is 1-based!!!)
2911 (Array will have been allocated
2912 3 by (number_of_nodes + 1) for the part
2913 long - see USERD_get_gold_part_build_info)
2916 ex) If number_of_nodes = 100
2917 as obtained in:
2918 USERD_get_gold_part_build_info
2920 Then the allocated dimensions of the
2921 pointer sent to this routine will be:
2922 coord_array[3][101]
2924 Ignore the coord_array[0][0]
2925 coord_array[1][0]
2926 coord_array[2][0] locations and start
2927 the node coordinates at:
2928 coord_array[0][1]
2929 coord_array[1][1]
2930 coord_array[2][1]
2932 coord_array[0][2]
2933 coord_array[1][2]
2934 coord_array[2][2]
2936 etc.
2938 Notes:
2939 -----
2940 * Not called unless Num_unstructured_parts is > 0
2942 * Will be based on Current_time_step
2945 --------------------------------------------------------------------
2946 USERD_get_part_element_ids_by_type
2948 Description:
2949 -----------
2950 Gets the ids for the elements of a particular type for an unstructured
2951 or structured part.
2953 Specification:
2954 -------------
2955 int USERD_get_part_element_ids_by_type(int part_number,
2956 int element_type,
2957 int *elemid_array)
2959 Returns:
2960 -------
2961 Z_OK if successful
2962 Z_ERR if not successful
2964 Arguments:
2965 ---------
2966 (IN) part_number = The part number
2967 (1-based index of part table, namely:
2969 1 ... Numparts_available.
2971 It is NOT the part_id that
2972 is loaded in USERD_get_gold_part_build_info)
2974 (IN) element_type = One of the following (See global_extern.h)
2975 Z_POINT node point element
2976 Z_BAR02 2 node bar
2977 Z_BAR03 3 node bar
2978 Z_TRI03 3 node triangle
2979 Z_TRI06 6 node triangle
2980 Z_QUA04 4 node quad
2981 Z_QUA08 8 node quad
2982 Z_TET04 4 node tetrahedron
2983 Z_TET10 10 node tetrahedron
2984 Z_PYR05 5 node pyramid
2985 Z_PYR13 13 node pyramid
2986 Z_PEN06 6 node pentahedron
2987 Z_PEN15 15 node pentahedron
2988 Z_HEX08 8 node hexahedron
2989 Z_HEX20 20 node hexahedron
2991 Z_G_POINT ghost node point element
2992 Z_G_BAR02 2 node ghost bar
2993 Z_G_BAR03 3 node ghost bar
2994 Z_G_TRI03 3 node ghost triangle
2995 Z_G_TRI06 6 node ghost triangle
2996 Z_G_QUA04 4 node ghost quad
2997 Z_G_QUA08 8 node ghost quad
2998 Z_G_TET04 4 node ghost tetrahedron
2999 Z_G_TET10 10 node ghost tetrahedron
3000 Z_G_PYR05 5 node ghost pyramid
3001 Z_G_PYR13 13 node ghost pyramid
3002 Z_G_PEN06 6 node ghost pentahedron
3003 Z_G_PEN15 15 node ghost pentahedron
3004 Z_G_HEX08 8 node ghost hexahedron
3005 Z_G_HEX20 20 node ghost hexahedron
3007 (OUT) elemid_array = 1D array containing id of each
3008 element of the type.
3010 (Array will have been allocated
3011 number_of_elements of the type long)
3013 ex) If number_of_elements[Z_TRI03] = 25
3014 number_of_elements[Z_QUA04] = 100
3015 number_of_elements[Z_HEX08] = 30
3016 as obtained in:
3017 USERD_get_gold_part_build_info
3019 Then the allocated dimensions available
3020 for this routine will be:
3021 conn_array[25] when called with Z_TRI03
3023 conn_array[100] when called with Z_QUA04
3025 conn_array[30] when called with Z_HEX08
3027 Notes:
3028 -----
3029 * Not called unless element label status is set to TRUE in
3030 USERD_get_element_label_status
3032 * Will be based on Current_time_step
3036 --------------------------------------------------------------------
3037 USERD_get_part_elements_by_type
3039 Description:
3040 -----------
3041 Gets the connectivities for the elements of a particular type in an
3042 unstructured part
3044 Specification:
3045 -------------
3046 int USERD_get_part_elements_by_type(int part_number,
3047 int element_type,
3048 int **conn_array)
3050 Returns:
3051 -------
3052 Z_OK if successful
3053 Z_ERR if not successful
3055 Arguments:
3056 ---------
3057 (IN) part_number = The part number
3058 (1-based index of part table, namely:
3060 1 ... Numparts_available.
3062 It is NOT the part_id that
3063 is loaded in USERD_get_gold_part_build_info)
3065 (IN) element_type = One of the following (See global_extern.h)
3066 Z_POINT node point element
3067 Z_BAR02 2 node bar
3068 Z_BAR03 3 node bar
3069 Z_TRI03 3 node triangle
3070 Z_TRI06 6 node triangle
3071 Z_QUA04 4 node quad
3072 Z_QUA08 8 node quad
3073 Z_TET04 4 node tetrahedron
3074 Z_TET10 10 node tetrahedron
3075 Z_PYR05 5 node pyramid
3076 Z_PYR13 13 node pyramid
3077 Z_PEN06 6 node pentahedron
3078 Z_PEN15 15 node pentahedron
3079 Z_HEX08 8 node hexahedron
3080 Z_HEX20 20 node hexahedron
3082 Z_G_POINT ghost node point element
3083 Z_G_BAR02 2 node ghost bar
3084 Z_G_BAR03 3 node ghost bar
3085 Z_G_TRI03 3 node ghost triangle
3086 Z_G_TRI06 6 node ghost triangle
3087 Z_G_QUA04 4 node ghost quad
3088 Z_G_QUA08 8 node ghost quad
3089 Z_G_TET04 4 node ghost tetrahedron
3090 Z_G_TET10 10 node ghost tetrahedron
3091 Z_G_PYR05 5 node ghost pyramid
3092 Z_G_PYR13 13 node ghost pyramid
3093 Z_G_PEN06 6 node ghost pentahedron
3094 Z_G_PEN15 15 node ghost pentahedron
3095 Z_G_HEX08 8 node ghost hexahedron
3096 Z_G_HEX20 20 node ghost hexahedron
3099 (OUT) conn_array = 2D array containing connectivity
3100 of each element of the type.
3102 (Array will have been allocated
3103 num_of_elements of the type by
3104 connectivity length of the type)
3106 ex) If number_of_elements[Z_TRI03] = 25
3107 number_of_elements[Z_QUA04] = 100
3108 number_of_elements[Z_HEX08] = 30
3109 as obtained in:
3110 USERD_get_gold_part_build_info
3112 Then the allocated dimensions available
3113 for this routine will be:
3114 conn_array[25][3] when called with Z_TRI03
3116 conn_array[100][4] when called with Z_QUA04
3118 conn_array[30][8] when called with Z_HEX08
3120 Notes:
3121 -----
3122 * Not called unless Num_unstructured_parts is > 0
3124 * Will be based on Current_time_step
3127 --------------------------------------------------------------------
3128 USERD_get_part_node_ids
3130 Description:
3131 -----------
3132 Gets the node ids of an unstructured or structured part.
3134 Specification:
3135 -------------
3136 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
3138 Returns:
3139 -------
3140 Z_OK if successful
3141 Z_ERR if not successful
3143 Arguments:
3144 ---------
3145 (IN) part_number = The part number
3146 (1-based index of part table, namely:
3148 1 ... Numparts_available.
3150 It is NOT the part_id that
3151 is loaded in USERD_get_gold_part_build_info)
3153 (OUT) nodeid_array = 1D array containing node ids of
3154 each node in the part.
3156 (IMPORTANT: This array is 1-based!!!)
3158 (Array will have been allocated
3159 (number_of_nodes + 1) for the part long
3160 see USERD_get_gold_part_build_info)
3162 ex) If number_of_nodes = 100
3163 as obtained in:
3164 USERD_get_gold_part_build_info
3166 Then the allocated dimensions of the
3167 pointer sent to this routine will be:
3168 nodeid_array[101]
3170 Ignore the nodeid_array[0] location and start
3171 the node ids at:
3172 nodeid_array[1]
3174 nodeid_array[2]
3176 etc.
3178 Notes:
3179 -----
3180 * Not called unless node label status is TRUE, as returned from
3181 USERD_get_node_label_status
3183 * Will be based on Current_time_step
3185 * The ids are purely labels, used when displaying or querying node ids.
3186 However, any node id < 0 will never be displayed
3189 --------------------------------------------------------------------
3190 USERD_get_reader_descrip
3192 Description:
3193 -----------
3194 Gets the description of the reader, so gui can give more info
3196 Specification:
3197 -------------
3198 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
3200 Returns:
3201 -------
3202 Z_OK if successful
3203 Z_ERR if not successful
3205 Arguments:
3206 ---------
3207 (OUT) descrip = the description of the reader (max length is MAXFILENP,
3208 which is 255)
3210 Notes:
3211 -----
3212 * OPTIONAL ROUTINE! You can have it or not.
3216 --------------------------------------------------------------------
3217 USERD_get_reader_version
3219 Description:
3220 -----------
3221 Gets the version number of the user defined reader
3223 Specification:
3224 -------------
3225 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
3227 Returns:
3228 -------
3229 Z_OK if successful
3230 Z_ERR if not successful (and will assume is version 1.0)
3232 Arguments:
3233 ---------
3234 (OUT) version_number = the version number of the reader
3235 (max length is Z_MAX_USERD_NAME, which
3236 is 20)
3238 Notes:
3239 -----
3240 * This needs to be "2.000" or greater. Otherwise EnSight will assume
3241 this reader is API 1.0
3243 * should set it to "2.010" for this version of the API
3248 --------------------------------------------------------------------
3249 USERD_get_sol_times
3251 Description:
3252 -----------
3253 Get the solution times associated with each time step for
3254 desired timeset.
3256 Specification:
3257 -------------
3258 int USERD_get_sol_times(int timeset_number,
3259 float *solution_times)
3261 Returns:
3262 -------
3263 Z_OK if successful
3264 Z_ERR if not successful
3266 Arguments:
3267 ---------
3268 (IN) timeset_number = the timeset number
3270 For example: If USERD_get_number_of_timesets
3271 returns 2, the valid
3272 timeset_number's would be 1 and 2
3274 (OUT) solution_times = 1D array of solution times per time step
3276 (Array will have been allocated
3277 Num_time_steps[timeset_number] long)
3279 Notes:
3280 -----
3281 * The solution times must be non-negative and increasing.
3285 --------------------------------------------------------------------
3286 USERD_get_timeset_description -
3288 Description:
3289 -----------
3290 Get the description to associate with the desired timeset.
3292 Specification:
3293 -------------
3294 int USERD_get_timeset_description(int timeset_number,
3295 char timeset_description[Z_BUFL])
3297 Returns:
3298 -------
3299 Z_OK if successful
3300 Z_ERR if not successful
3302 Arguments:
3303 ---------
3304 (IN) timeset_number = the timeset number
3306 For example: If USERD_get_number_of_timesets
3307 returns 2, the valid
3308 timeset_number's would be 1 and 2
3310 (OUT) timeset_description = timeset description string
3313 Notes:
3314 -----
3315 * A string of NULLs is valid for timeset_description
3320 --------------------------------------------------------------------
3321 USERD_get_var_by_component
3323 Description:
3324 -----------
3325 Gets the values of a variable component. Both unstructured and structured
3326 parts use this routine.
3328 if Z_PER_NODE:
3329 Get the component value at each node for a given variable in the part.
3331 or if Z_PER_ELEM:
3332 Get the component value at each element of a specific part and type
3333 for a given variable.
3335 Specification:
3336 -------------
3337 int USERD_get_var_by_component(int which_variable,
3338 int which_part,
3339 int var_type,
3340 int which_type,
3341 int imag_data,
3342 int component,
3343 float *var_array)
3345 Returns:
3346 -------
3347 Z_OK if successful
3348 Z_ERR if not successful
3350 or: Z_UNDEF, in which case you need not load any values into var_array
3353 Arguments:
3354 ---------
3355 (IN) which_variable = The variable number
3357 (IN) which_part Since EnSight Version 7.4
3358 -------------------------
3359 = The part number
3361 (1-based index of part table, namely:
3363 1 ... Numparts_available.
3365 It is NOT the part_id that
3366 is loaded in USERD_get_gold_part_build_info)
3368 Prior to EnSight Version 7.4
3369 ----------------------------
3370 = The part id This is the part_id label loaded
3371 in USERD_get_gold_part_build_info.
3372 It is NOT the part table index.
3374 (IN) var_type = Z_SCALAR
3375 Z_VECTOR
3376 Z_TENSOR (symmetric tensor)
3377 Z_TENSOR9 (asymmetric tensor)
3379 (IN) which_type
3381 if Z_PER_NODE: Not used
3383 if Z_PER_ELEM: = The element type
3384 Z_POINT node point element
3385 Z_BAR02 2 node bar
3386 Z_BAR03 3 node bar
3387 Z_TRI03 3 node triangle
3388 Z_TRI06 6 node triangle
3389 Z_QUA04 4 node quad
3390 Z_QUA08 8 node quad
3391 Z_TET04 4 node tetrahedron
3392 Z_TET10 10 node tetrahedron
3393 Z_PYR05 5 node pyramid
3394 Z_PYR13 13 node pyramid
3395 Z_PEN06 6 node pentahedron
3396 Z_PEN15 15 node pentahedron
3397 Z_HEX08 8 node hexahedron
3398 Z_HEX20 20 node hexahedron
3400 Z_G_POINT ghost node point element
3401 Z_G_BAR02 2 node ghost bar
3402 Z_G_BAR03 3 node ghost bar
3403 Z_G_TRI03 3 node ghost triangle
3404 Z_G_TRI06 6 node ghost triangle
3405 Z_G_QUA04 4 node ghost quad
3406 Z_G_QUA08 8 node ghost quad
3407 Z_G_TET04 4 node ghost tetrahedron
3408 Z_G_TET10 10 node ghost tetrahedron
3409 Z_G_PYR05 5 node ghost pyramid
3410 Z_G_PYR13 13 node ghost pyramid
3411 Z_G_PEN06 6 node ghost pentahedron
3412 Z_G_PEN15 15 node ghost pentahedron
3413 Z_G_HEX08 8 node ghost hexahedron
3414 Z_G_HEX20 20 node ghost hexahedron
3416 (IN) imag_data = TRUE if imag component
3417 FALSE if real component
3419 (IN) component = The component: (0 if Z_SCALAR)
3420 (0 - 2 if Z_VECTOR)
3421 (0 - 5 if Z_TENSOR)
3422 (0 - 8 if Z_TENSOR9)
3424 * 6 Symmetric Indicies, 0:5 *
3425 * ---------------------------- *
3426 * | 11 12 13 | | 0 3 4 | *
3427 * | | | | *
3428 * T = | 22 23 | = | 1 5 | *
3429 * | | | | *
3430 * | 33 | | 2 | *
3433 * 9 General Indicies, 0:8 *
3434 * ---------------------------- *
3435 * | 11 12 13 | | 0 3 4 | *
3436 * | | | | *
3437 * T = | 21 22 23 | = | 6 1 5 | *
3438 * | | | | *
3439 * | 31 32 33 | | 7 8 2 | *
3441 (OUT) var_array
3443 -----------------------------------------------------------------------
3444 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
3445 -----------------------------------------------------------------------
3447 if Z_PER_NODE: = 1D array containing variable component value
3448 for each node.
3450 (Array will have been allocated
3451 (number_of_nodes + 1) long)
3453 Info stored in this fashion:
3454 var_array[0] = not used
3455 var_array[1] = var component for node 1 of part
3456 var_array[2] = var_component for node 2 of part
3457 var_array[3] = var_component for node 3 of part
3458 etc.
3460 if Z_PER_ELEM: = 1D array containing variable component
3461 value for each element of a particular
3462 part and type.
3464 (Array will have been allocated
3465 (number_of_elements[which_part][which_type] + 1)
3466 long. See USERD_get_gold_part_build_info)
3468 Info stored in this fashion:
3469 var_array[1] = var component for elem 1 (of part and type)
3470 var_array[2] = var component for elem 2 (of part and type)
3471 var_array[3] = var component for elem 3 (of part and type)
3472 etc.
3474 Notes:
3475 -----
3476 * Not called unless Num_variables is > 0
3478 * The per_node or per_elem classification must be obtainable from the
3479 variable number (a var_classify array needs to be retained)
3481 * Will be based on Current_time_step
3483 * If the variable is not defined for this part, simply return with a
3484 value of Z_UNDEF. EnSight will treat the variable as undefined for
3485 this part.
3488 --------------------------------------------------------------------
3489 USERD_get_var_value_at_specific
3491 Description:
3492 -----------
3493 if Z_PER_NODE:
3494 Get the value of a particular variable at a particular node in a
3495 particular part at a particular time.
3497 or if Z_PER_ELEM:
3498 Get the value of a particular variable at a particular element of
3499 a particular type in a particular part at a particular time.
3502 Specification:
3503 -------------
3504 int USERD_get_var_value_at_specific(int which_var,
3505 int which_node_or_elem,
3506 int which_part,
3507 int which_elem_type,
3508 int time_step,
3509 float values[3],
3510 int imag_data)
3512 Returns:
3513 -------
3514 Z_OK if successful
3515 Z_ERR if not successful
3517 Arguments:
3518 ---------
3519 (IN) which_var = The variable number
3521 (IN) which_node_or_elem
3523 If Z_PER_NODE:
3524 = The node number. This is not the id, but is
3525 the index of the global node
3526 list (1 based), or the block's
3527 node list (1 based).
3529 Thus, coord_array[1]
3530 coord_array[2]
3531 coord_array[3]
3532 . |
3533 . |which_node_or_elem index
3534 . ----
3537 If Z_PER_ELEM:
3538 = The element number. This is not the id, but is
3539 the element number index
3540 of the number_of_element array
3541 (see USERD_get_gold_part_build_info),
3542 or the block's element list (1 based).
3544 Thus, for which_part:
3545 conn_array[which_elem_type][0]
3546 conn_array[which_elem_type][1]
3547 conn_array[which_elem_type][2]
3548 . |
3549 . which_node_or_elem index
3550 . ----
3553 (IN) which_part Since EnSight Version 7.4
3554 -------------------------
3555 = The part number
3557 (1-based index of part table, namely:
3559 1 ... Numparts_available.
3561 It is NOT the part_id that
3562 is loaded in USERD_get_gold_part_build_info)
3564 Prior to EnSight Version 7.4
3565 ----------------------------
3566 = The part id This is the part_id label loaded
3567 in USERD_get_gold_part_build_info.
3568 It is NOT the part table index.
3571 (IN) which_elem_type
3573 If Z_PER_NODE, or block part:
3574 = Not used
3576 If Z_PER_ELEM:
3577 = The element type. This is the element type index
3578 of the number_of_element array
3579 (see USERD_get_gold_part_build_info)
3581 (IN) time_step = The time step
3583 (IN) imag_data = TRUE if want imaginary value.
3584 FALSE if want real value.
3586 (OUT) values = scalar or vector component value(s)
3587 values[0] = scalar or vector[0]
3588 values[1] = vector[1]
3589 values[2] = vector[2]
3592 Notes:
3593 -----
3594 * This routine is used in node querys over time (or element querys over
3595 time for Z_PER_ELEM variables). If these operations are not critical
3596 to you, this can be a dummy routine.
3598 * The per_node or per_elem classification must be obtainable from the
3599 variable number (a var_classify array needs to be retained)
3601 * The time step given is for the proper variable timeset.
3604 ----------------------------------------------------------------------
3605 USERD_load_matf_data
3607 Description:
3608 -----------
3609 Get the material id list, mixed-material id list, or
3610 mixed-material values list for the given material set and part (and
3611 element type if material id list)
3613 Specification:
3614 -------------
3615 int USERD_load_matf_data( int set_index,
3616 int part_id,
3617 int wtyp,
3618 int mat_type,
3619 int *ids_list,
3620 float *val_list)
3623 Returns:
3624 -------
3625 Z_OK if successful
3626 Z_ERR if not successful
3628 Arguments:
3629 ---------
3630 (IN) set_index = the material set index (zero based)
3632 (IN) part_id = the part number desired
3634 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3636 Z_POINT node point element
3637 Z_BAR02 2 node bar
3638 Z_BAR03 3 node bar
3639 Z_TRI03 3 node triangle
3640 Z_TRI06 6 node triangle
3641 Z_QUA04 4 node quad
3642 Z_QUA08 8 node quad
3643 Z_TET04 4 node tetrahedron
3644 Z_TET10 10 node tetrahedron
3645 Z_PYR05 5 node pyramid
3646 Z_PYR13 13 node pyramid
3647 Z_PEN06 6 node pentahedron
3648 Z_PEN15 15 node pentahedron
3649 Z_HEX08 8 node hexahedron
3650 Z_HEX20 20 node hexahedron
3651 Z_NSIDED nsided polygon
3652 Z_NFACED nfaced polyhedron
3654 Z_G_POINT ghost node point element
3655 Z_G_BAR02 2 node ghost bar
3656 Z_G_BAR03 3 node ghost bar
3657 Z_G_TRI03 3 node ghost triangle
3658 Z_G_TRI06 6 node ghost triangle
3659 Z_G_QUA04 4 node ghost quad
3660 Z_G_QUA08 8 node ghost quad
3661 Z_G_TET04 4 node ghost tetrahedron
3662 Z_G_TET10 10 node ghost tetrahedron
3663 Z_G_PYR05 5 node ghost pyramid
3664 Z_G_PYR13 13 node ghost pyramid
3665 Z_G_PEN06 6 node ghost pentahedron
3666 Z_G_PEN15 15 node ghost pentahedron
3667 Z_G_HEX08 8 node ghost hexahedron
3668 Z_G_HEX20 20 node ghost hexahedron
3669 Z_G_NSIDED ghost nsided polygon
3670 Z_G_NFACED ghost nfaced polyhedron
3672 (IN) mat_type = Z_MAT_INDEX for material ids list
3673 Z_MIX_INDEX for mixed-material ids list
3674 Z_MIX_VALUE for mixed-material values list
3676 (OUT) ids_list = If mat_type is Z_MAT_INDEX:
3677 ---------------------------
3678 1D material id list
3679 (Int array will have been allocated
3680 the appropriate size, as returned in
3681 USERD_size_matf_data for mat_type Z_MAT_INDEX)
3683 If mat_type is Z_MIX_INDEX:
3684 ---------------------------
3685 1D mixed-material id list
3686 (Int array will have been allocated
3687 the appropriate size, as returned in
3688 USERD_size_matf_data for mat_type Z_MIX_INDEX)
3690 (OUT) val_list = 1D mixed-materials values list
3691 (only used if mat_type is Z_MIX_VALUE)
3693 (Float array will have been allocated
3694 the appropriate size, as returned in
3695 USERD_size_matf_data for mat_type Z_MIX_VALUE)
3697 Notes:
3698 -----
3699 * See USERD_get_number_of_material_sets header for explanatory example
3700 * Will not be called if Num_material_sets is zero,
3701 or Num_materials[set_index] is zero,
3702 or the appropriate size from USERD_size_matf_data is zero
3706 --------------------------------------------------------------------
3707 USERD_set_filenames
3709 Description:
3710 -----------
3711 Receives the geometry and result filenames entered in the data
3712 dialog. The user written code will have to store and use these
3713 as needed. The user written code must manage its own files!!
3715 Specification:
3716 -------------
3717 int USERD_set_filenames(char filename_1[],
3718 char filename_2[],
3719 char the_path[],
3720 int swapbytes)
3722 Returns:
3723 -------
3724 Z_OK if successful
3725 Z_ERR if not successful
3727 Arguments:
3728 ---------
3729 (IN) filename_1 = the filename entered into the geometry
3730 field of the data dialog.
3732 (IN) param_2 = The usage of this string depends on
3733 'two_fields' in USERD_get_name_of_reader.
3735 If two_fields is FALSE then it's empty.
3737 If two_fields is TRUE, this is the
3738 manditory results file entered
3739 into the result field of the data dialog.
3741 If two_fields is -1, then this contains
3742 optional text (filenames, modifiers, etc.)
3743 that can be parsed and used to modify
3744 reader
3746 (IN) the_path = the path info from the data dialog.
3747 Note: filename_1 and filename_2 have already
3748 had the path prepended to them. This
3749 is provided in case it is needed for
3750 filenames contained in one of the files
3752 (IN) swapbytes = TRUE if should swap bytes when reading data.
3753 = FALSE normally.
3755 Notes:
3756 -----
3757 * Since you must manage everything from the input that is entered in
3758 these data dialog fields, this is an important routine!
3760 * It may be that you will need to have an executive type file that contains
3761 info and other filenames within it, like EnSight6's case file.
3764 --------------------------------------------------------------------
3765 USERD_set_server_number
3767 Description:
3768 -----------
3769 Receives the server number of how many total servers.
3771 Specification:
3772 -------------
3773 int USERD_set_server_number(int cur_serv,
3774 int tot_servs)
3776 Returns:
3777 -------
3778 nothing
3780 Arguments:
3781 ---------
3782 (IN) cur_serv = the current server.
3784 (IN) tot_servs = the total number of servers.
3786 Notes:
3787 -----
3788 * Only useful if your user defined reader is being used with EnSight's
3789 Server-of-Server capability. And even then, it may or may not be
3790 something that you can take advantage of. If your data is already
3791 partitioned in some manner, such that you can access the proper
3792 portions using this information.
3794 For all non-SOS uses, this will simply be 1 of 1
3798 --------------------------------------------------------------------
3799 USERD_set_time_set_and_step
3801 Description:
3802 -----------
3803 Set the current time step in the desired timeset. All functions that
3804 need time, and that do not explicitly pass it in, will use the timeset
3805 and step set by this routine, if needed.
3807 Specification:
3808 -------------
3809 void USERD_set_time_set_and_step(int timeset_number,
3810 int time_step)
3812 Returns:
3813 -------
3814 nothing
3816 Arguments:
3817 ---------
3818 (IN) timeset_number = the timeset number (1 based).
3820 For example: If USERD_get_number_of_timesets
3821 returns 2, the valid timeset_number's
3822 would be 1 and 2.
3824 (IN) time_step = The current time step to set
3826 Notes:
3827 -----
3828 * Current_time_step and Current_timeset would be set here
3831 --------------------------------------------------------------------
3832 USERD_size_matf_data
3834 Description:
3835 -----------
3836 Get the length of the material id list, mixed-material id list, or
3837 mixed-material values list for the given material set and part (and
3838 element type if material id list)
3840 Specification:
3841 -------------
3842 int USERD_size_matf_data( int set_index,
3843 int part_id,
3844 int wtyp,
3845 int mat_type,
3846 int *matf_size)
3849 Returns:
3850 -------
3851 Z_OK if successful
3852 Z_ERR if not successful
3854 Arguments:
3855 ---------
3856 (IN) set_index = the material set index (zero based)
3858 (IN) part_id = the part number desired
3860 (IN) wtyp = the element type (used for Z_MAT_INDEX only)
3862 Z_POINT node point element
3863 Z_BAR02 2 node bar
3864 Z_BAR03 3 node bar
3865 Z_TRI03 3 node triangle
3866 Z_TRI06 6 node triangle
3867 Z_QUA04 4 node quad
3868 Z_QUA08 8 node quad
3869 Z_TET04 4 node tetrahedron
3870 Z_TET10 10 node tetrahedron
3871 Z_PYR05 5 node pyramid
3872 Z_PYR13 13 node pyramid
3873 Z_PEN06 6 node pentahedron
3874 Z_PEN15 15 node pentahedron
3875 Z_HEX08 8 node hexahedron
3876 Z_HEX20 20 node hexahedron
3877 Z_NSIDED nsided polygon
3878 Z_NFACED nfaced polyhedron
3880 Z_G_POINT ghost node point element
3881 Z_G_BAR02 2 node ghost bar
3882 Z_G_BAR03 3 node ghost bar
3883 Z_G_TRI03 3 node ghost triangle
3884 Z_G_TRI06 6 node ghost triangle
3885 Z_G_QUA04 4 node ghost quad
3886 Z_G_QUA08 8 node ghost quad
3887 Z_G_TET04 4 node ghost tetrahedron
3888 Z_G_TET10 10 node ghost tetrahedron
3889 Z_G_PYR05 5 node ghost pyramid
3890 Z_G_PYR13 13 node ghost pyramid
3891 Z_G_PEN06 6 node ghost pentahedron
3892 Z_G_PEN15 15 node ghost pentahedron
3893 Z_G_HEX08 8 node ghost hexahedron
3894 Z_G_HEX20 20 node ghost hexahedron
3895 Z_G_NSIDED ghost nsided polygon
3896 Z_G_NFACED ghost nfaced polyhedron
3898 (IN) mat_type = Z_MAT_INDEX for material ids list
3899 Z_MIX_INDEX for mixed-material ids list
3900 Z_MIX_VALUE for mixed-material values list
3902 (OUT) matf_size = the length of the material id list, or
3903 mixed-material id list, or
3904 mixed-material values list
3905 for the given material set and part number
3906 (and element type if Z_MAT_INDEX)
3908 Notes:
3909 -----
3910 * See USERD_get_number_of_material_sets header for explanatory example
3911 * Will not be called if Num_material_sets is zero, or
3912 Num_materials[set_index] is zero
3917 --------------------------------------------------------------------
3918 USERD_stop_part_building
3920 Description:
3921 -----------
3922 This routine called when the part building dialog is closed. It is
3923 provided in case you desire to release memory, etc. that was only needed
3924 during the part building process.
3926 Specification:
3927 -------------
3928 void USERD_stop_part_building( void )
3930 Returns:
3931 -------
3932 nothing
3934 Arguments:
3935 ---------
3936 none
3938 Notes:
3939 -----
3941 --------------------------------------------------------------------
3942 USERD_rigidbody_existence
3944 Description:
3945 -----------
3946 Gets the existence of rigid body values or not in the model
3948 Specification:
3949 -------------
3950 int USERD_rigidbody_existence( void )
3952 Returns:
3953 -------
3954 Z_OK if rigid body values exist for the model
3955 Z_UNDEF if no rigid body values exist
3956 Z_ERR if an error
3958 Arguments:
3959 ---------
3960 none
3962 Notes:
3963 -----
3964 * This will be based on Current_time_step
3967 --------------------------------------------------------------------
3968 USERD_rigidbody_values
3970 Description:
3971 -----------
3972 Gets the rigid body values for each part
3974 Specification:
3975 -------------
3976 int USERD_rigidbody_values(int part_number,
3977 float values[7])
3979 Returns:
3980 -------
3981 Z_OK if rigid body values exist for the model
3982 Z_UNDEF if no rigid body values exist
3983 Z_ERR if an error
3985 Arguments:
3986 ---------
3987 (IN) part_number = The part number
3989 (1-based index of part table, namely:
3991 1 ... Numparts_available.
3993 It is NOT the part_id that
3994 is loaded in USERD_get_gold_part_build_info)
3996 (OUT) values values[0] = IX (x location)
3997 values[1] = IY (y location)
3998 values[2] = IZ (z location)
3999 values[3] = E0 (e0 euler value)
4000 values[4] = E1 (e1 euler value)
4001 values[5] = E2 (e2 euler value)
4002 values[6] = E3 (e3 euler value)
4005 Notes:
4006 -----
4007 * This will be based on Current_time_step
4008 * It will not be called unless USERD_rigidbody_existence indicates
4009 that there are some values in the model by returning Z_OK.
4012 --------------------------------------------------------------------
4013 USERD_set_right_side
4015 Description:
4016 -----------
4017 Informs the reader that the time currently set is the right side of a time
4018 span used for variable interpolation between time steps
4020 Specification:
4021 -------------
4022 void USERD_set_right_side( void )
4024 Returns:
4025 -------
4027 Arguments:
4028 ---------
4029 none
4031 Notes:
4032 -----
4033 * Applies to Current_time_step
4039 ------------------------------------------------------------------
4040 ENHANCED GUI ROUTINES
4042 --------------------------------------------------------------------
4043 USERD_get_extra_gui_numbers
4045 Description:
4046 -----------
4047 The Enhanced GUI routines are added to allow
4048 the user to customize a portion of the Data
4049 Reader dialog to pass in options to their
4050 user defined reader.
4052 Specification:
4053 -------------
4054 void USERD__get_extra_gui_numbers(int *num_Toggles,
4055 int *num_pulldowns,
4056 int *num_fields)
4058 Returns:
4059 -------
4061 Arguments:
4062 ---------
4063 (OUT) num_Toggles = number of toggles that will be provided
4065 num_pulldowns = number of pulldowns that will be provided
4067 num_fields = number of fields that will be provided
4069 Notes:
4070 -----
4071 There are three routines that work together:
4072 USERD_get_extra_gui_numbers
4073 USERD_get_extra_gui_defaults
4074 USERD_set_extra_gui_data
4076 The existence of these routine indicates that
4077 you wish to add customize entries to the
4078 Data Reader dialog.
4080 If you don't want the extra GUI features,
4081 simply delete these routines, or change their
4082 names to something such as
4083 USERD_DISABLED_get_extra_gui_defaults
4085 The presence of these routines
4086 will ensure that EnSight will call them and
4087 use their data to modify the extraction parameters set
4088 with some or all of the following:
4089 toggles, pulldown menu and fields.
4091 The user can then interact with the enhanced
4092 GUI and then send their choices to
4093 USERD_set_extra_gui_data
4095 Therefore if USERD_get_extra_gui_numbers
4096 exists then the other two must exist.
4098 If none exist, then the GUI will be unchanged.
4100 Toggle data will return an integer
4101 TRUE if checked
4102 FALSE if unchecked
4104 Pulldown menu will return an integer representing
4105 the menu item selected
4107 Field will return a string Z_LEN_GUI_FIELD_STR long.
4109 If all the enhanced GUI features are enabled it
4110 might look something like this
4112 ===================================================
4113 [] Title 1 [X] Title 3
4114 [X]Title 2 [X] Title 4
4116 Pulldown Menu ->
4117 Menu Choice 1
4118 Menu Choice 2
4119 Menu Choice 3
4121 Data Field Title 1 ____________________________
4123 Data Field Title 2 ____________________________
4124 =====================================================
4126 This routine defines the numbers of toggles, pulldowns & fields
4128 The following are defined in the global_extern.h
4129 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4130 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4131 Z_LEN_GUI_FIELD_STR max length of field string
4132 Z_LEN_GUI_TITLE_STR max length of title string
4134 The library is loaded, this routine is
4135 called, then the library is unloaded.
4137 Do not define globals in this routine
4138 as when the library is unloaded, you'll
4139 lose them.
4142 --------------------------------------------------------------------
4143 USERD_get_extra_gui_defaults
4145 Description:
4146 -----------
4147 This routine defines the Titles, status,
4148 List choices, strings, etc that are fed
4149 up to the GUI.
4151 Specification:
4152 -------------
4153 int USERD_get_extra_gui_defaults(char **toggle_Title,
4154 int *toggle_default_status,
4155 char **pulldown_Title,
4156 int *pulldown_number_in_list,
4157 int *pulldown_default_selection,
4158 char ***pulldown_item_strings,
4159 char **field_Title,
4160 char **field_user_string)
4162 Returns:
4163 -------
4164 Z_OK if successful
4165 Z_ERR if not successful
4167 Arguments:
4168 ---------
4169 (OUT) toggle_Title = title for each toggle
4170 array dimension is [num_toggles] by
4171 [Z_LEN_GUI_TITLE_STR] long
4173 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4174 array dimension is [num_toggles] long
4176 pulldown_Title = title for each pulldown
4177 array dimension is [num_pulldowns] by
4178 [Z_LEN_GUI_TITLE_STR] long
4180 pulldown_number_in_list = number of items in each pulldown
4181 array dimension is [num_pulldowns] long
4183 pulldown_default_selection = pulldown item selection for each pulldown
4184 array dimension is [num_pulldowns] long
4186 pulldown_item_strings = pulldown item strings
4187 array is [num_pulldowns] by
4188 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4189 [Z_LEN_GUI_PULL_STR] long
4191 field_Title = title for each field
4192 array dimension is [num_fields] by
4193 [Z_LEN_GUI_TITLE_STR] long
4195 field_user_string = content of the field
4196 array dimension is [num_fields] by
4197 [Z_LEN_GUI_TITLE_STR] long
4201 Notes:
4202 -----
4203 * The library is loaded, this routine is called, then the library is unloaded.
4205 * Do not define globals in this routine as when the library is unloaded, you'll
4206 lose them.
4210 --------------------------------------------------------------------
4211 USERD_set_extra_gui_data
4213 Description:
4214 -----------
4215 This routine sets the new values for the toggles, pulldowns, and fields.
4217 Specification:
4218 -------------
4219 void USERD_set_extra_gui_data(
4220 int *toggle, /* [num_toggle] */
4221 int *pulldown, /* [num_pulldown] */
4222 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4224 Returns:
4225 -------
4227 Arguments:
4228 ---------
4229 (IN) toggle = setting for each toggle. TRUE or FALSE
4230 array dimension is [num_toggles] long
4232 pulldown = item chosen in each pulldown. (0 based)
4233 array dimension is [num_pulldowns] long
4235 field_text = content of the field
4236 array dimension is [num_fields] by
4237 [Z_LEN_GUI_TITLE_STR] long
4240 Notes:
4241 -----
4242 * This routine is called when the library is permanently
4243 loaded to the EnSight session, so define your globals
4244 in this and later routines.
4246 * It's up to you to change your reader behavior according to
4247 user entries!
4251 --------------------------------------------------------------------
4252 USERD_get_var_extract_gui_numbers
4254 Description:
4255 -----------
4256 The Var_Extract_GUI routines are added to allow
4257 the user to customize a extraction parameters
4258 for variables "after" the file has been read.
4259 These things can be modified and the variables will
4260 be update/refreshed according to the new parameters set
4262 Specification:
4263 -------------
4264 void USERD_get_var_extract_gui_numbers(int *num_Toggles,
4265 int *num_pulldowns,
4266 int *num_fields)
4269 Returns:
4270 -------
4272 Arguments:
4273 ---------
4274 (OUT) num_Toggles = number of toggles that will be provided
4276 num_pulldowns = number of pulldowns that will be provided
4278 num_fields = number of fields that will be provided
4280 Notes:
4281 -----
4282 There are three routines that work together:
4283 USERD_get_var_extract_gui_numbers
4284 USERD_get_var_extract_gui_defaults (this one)
4285 USERD_set_var_extract_gui_data
4287 The existence of these routine indicates that
4288 you wish to have the Var Extract Parameters dialog.
4290 If you don't want the extra GUI features,
4291 simply delete these routines, or change their
4292 names to something such as
4293 USERD_DISABLED_get_var_extract_gui_defaults
4295 The presence of these routines
4296 will ensure that EnSight will call them and
4297 use their data to modify the extraction parameters set
4298 with some or all of the following:
4299 toggles, pulldown menu and fields.
4301 The user can then interact with the enhanced
4302 GUI and then send their choices to
4303 USERD_set_extra_gui_data
4305 Therefore if USERD_get_var_extract_gui_numbers
4306 exists then the other two must exist.
4308 If none exist, then the GUI will be unchanged.
4310 Toggle data will return an integer
4311 TRUE if checked
4312 FALSE if unchecked
4314 Pulldown menu will return an integer representing
4315 the menu item selected
4317 Field will return a string Z_LEN_GUI_FIELD_STR long.
4319 If all the enhanced GUI features are enabled it
4320 might look something like this
4322 ===================================================
4323 [] Title 1 [X] Title 3
4324 [X]Title 2 [X] Title 4
4326 Pulldown Menu ->
4327 Menu Choice 1
4328 Menu Choice 2
4329 Menu Choice 3
4331 Data Field Title 1 ____________________________
4333 Data Field Title 2 ____________________________
4334 =====================================================
4336 This routine defines the numbers of toggles, pulldowns & fields
4338 The following are defined in the global_extern.h
4339 Z_MAX_NUM_GUI_PULL_ITEMS max num GUI pulldowns
4340 Z_LEN_GUI_PULL_STR max length of GUI pulldown string
4341 Z_LEN_GUI_FIELD_STR max length of field string
4342 Z_LEN_GUI_TITLE_STR max length of title string
4344 The library is loaded, this routine is
4345 called, then the library is unloaded.
4347 Do not define globals in this routine
4348 as when the library is unloaded, you'll
4349 lose them.
4352 --------------------------------------------------------------------
4353 USERD_get_var_extract_gui_defaults
4355 Description:
4356 -----------
4357 This routine defines the Titles, status,
4358 List choices, strings, etc that are fed
4359 up to the GUI.
4361 Specification:
4362 -------------
4363 int USERD_get_var_extract_gui_defaults(char **toggle_Title,
4364 int *toggle_default_status,
4365 char **pulldown_Title,
4366 int *pulldown_number_in_list,
4367 int *pulldown_default_selection,
4368 char ***pulldown_item_strings,
4369 char **field_Title,
4370 char **field_user_string)
4372 Returns:
4373 -------
4374 Z_OK if successful
4375 Z_ERR if not successful
4377 Arguments:
4378 ---------
4379 (OUT) toggle_Title = title for each toggle
4380 array dimension is [num_toggles] by
4381 [Z_LEN_GUI_TITLE_STR] long
4383 toggle_default_status = Setting for each toggle (TRUE or FALSE)
4384 array dimension is [num_toggles] long
4386 pulldown_Title = title for each pulldown
4387 array dimension is [num_pulldowns] by
4388 [Z_LEN_GUI_TITLE_STR] long
4390 pulldown_number_in_list = number of items in each pulldown
4391 array dimension is [num_pulldowns] long
4393 pulldown_default_selection = pulldown item selection for each pulldown
4394 array dimension is [num_pulldowns] long
4396 pulldown_item_strings = pulldown item strings
4397 array is [num_pulldowns] by
4398 [Z_MAX_NUM_GUI_PULL_ITEMS] by
4399 [Z_LEN_GUI_PULL_STR] long
4401 field_Title = title for each field
4402 array dimension is [num_fields] by
4403 [Z_LEN_GUI_TITLE_STR] long
4405 field_user_string = content of the field
4406 array dimension is [num_fields] by
4407 [Z_LEN_GUI_TITLE_STR] long
4411 Notes:
4412 -----
4413 * The library is loaded, this routine is called, then the library is unloaded.
4415 * Do not define globals in this routine as when the library is unloaded, you'll
4416 lose them.
4420 --------------------------------------------------------------------
4421 USERD_set_var_extract_gui_data
4423 Description:
4424 -----------
4425 This routine sets the new values for the toggles, pulldowns, and fields.
4427 Specification:
4428 -------------
4429 void USERD_set_var_extract_gui_data(
4430 int *toggle, /* [num_toggle] */
4431 int *pulldown, /* [num_pulldown] */
4432 char **field_text /* [num_fields][Z_LEN_GUI_FIELD_STR]*/)
4434 Returns:
4435 -------
4437 Arguments:
4438 ---------
4439 (IN) toggle = setting for each toggle. TRUE or FALSE
4440 array dimension is [num_toggles] long
4442 pulldown = item chosen in each pulldown. (0 based)
4443 array dimension is [num_pulldowns] long
4445 field_text = content of the field
4446 array dimension is [num_fields] by
4447 [Z_LEN_GUI_TITLE_STR] long
4450 Notes:
4451 -----
4452 * This routine is called when the library is permanently
4453 loaded to the EnSight session, so define your globals
4454 in this and later routines.
4456 * It's up to you to change your reader behavior according to
4457 user entries!
4463 -----------------------------------------------------------------------------------
4464 /* ----------------------------------------------------------
4465 * New in EnSight 8 is the capability to remove (fail) elements
4466 * based on variable threshold values. Basically the variable
4467 * name, a couple of thresholds, a couple of values and a logic
4468 * criteria are read in from this routine. Every element that
4469 * satisfies the failure criteria is removed and not used in
4470 * EnSight calculations.
4471 *
4472 * Example Failure criteria
4473 * Let fail_var_name = "fail_flag"
4474 * threshold_val1 = 0
4475 * threshold_operator1 = Z_EQUAL_TO
4476 * logic_criteria2 not used
4477 * threshold_val2 not used
4478 * threshold_operator2 not used
4479 * For each value of "fail_flag" at each element,
4480 * if fail flag == threshold_val1 (0.0) then element fails
4481 * Return (Z_ERR) if this is not used.
4482 * Return (Z_OK) if failed element feature should be used
4483 *
4484 * threshold_operator1 & 2 can be one of the following
4485 * Z_ELE_FAILED_NONE, - disables checking
4486 * Z_ELE_FAILED_GREATER, - greater than
4487 * Z_ELE_FAILED_LESS, - less than
4488 * Z_ELE_FAILED_EQUAL, - equal
4489 * Z_ELE_FAILED_NOT_EQUAL, - not equal
4490 * Z_ELE_FAILED_MANY - not used
4491 *
4492 * logic_criteria2
4493 * Z_ELE_FAILED_LOGIC_NONE,
4494 * Z_ELE_FAILED_LOGIC_AND,
4495 * Z_ELE_FAILED_LOGIC_OR,
4496 * Z_ELE_FAILED_LOGIC_MANY
4497 *
4498 * ---------------------------------------------------------- */
4499 int USERD_get_uns_failed_params(
4500 char *fail_var_name, /* variable name to be used in failure
4501 must be scalar, per elem */
4502 float *threshold_val1, /* number to compare for failure */
4503 float *threshold_val2, /* number to compare for failure */
4504 int *threshold_operator1, /* Z_GREATER_THAN, Z_LESS_THAN,
4505 Z_EQUAL_TO */
4506 int *threshold_operator2, /* Z_GREATER_THAN, Z_LESS_THAN,
4507 Z_EQUAL_TO */
4508 int *logic_criteria2
4511 /*--------------------------------------------------------------------
4512 * USERD_get_structured_reader_cinching -
4513 *--------------------------------------------------------------------
4514 *
4515 * Gets whether this reader will do structured cinching for block data
4516 * This means that it will handle the min, max, and step values for a
4517 * given block and return the coordinate components or variable components
4518 * in their "cinched" state when partial extraction or striding is used.
4519 * This is as opposed to returning the entire component (ignoring min, max
4520 * and stride) and letting Ensight pick out the values actually used.
4521 *
4522 * returns: Z_OK if the reader will handle the
4523 * min, max, and stride and return
4524 * the cinched values only.
4525 *
4526 * Z_UNDEF or Z_ERR if will return entire component
4527 * and rely on EnSight to cinch.
4528 *
4529 * Notes:
4530 * Unless you can actually pull out the desired min, max, and stride
4531 * without using a full component of memory, don't enable this feature.
4532 *--------------------------------------------------------------------*/
4533 int
4534 USERD_get_structured_reader_cinching( void )
4538 /*--------------------------------------------------------------------
4539 * USERD_set_block_range_and_stride -
4540 *--------------------------------------------------------------------
4541 *
4542 * Sets the min, max, and step values in each of the i, j, and k, directions
4543 * for the given part.
4544 *
4545 * (IN) part_number = The part number
4546 *
4547 * (1-based index of part table, namely:
4548 *
4549 * 1 ... Numparts_available.
4550 *
4551 * It is NOT the part_id that
4552 * is loaded in
4553 * USERD_get_gold_part_build_info)
4554 *
4555 * (IN) mini = min i plane desired (zero based)
4556 * maxi = max i plane desired (zero based)
4557 * stepi = i stride
4558 * minj = min j plane desired (zero based)
4559 * maxj = max j plane desired (zero based)
4560 * stepj = j stride
4561 * mink = min k plane desired (zero based)
4562 * maxk = max k plane desired (zero based)
4563 * stepk = k stride
4564 *
4565 *
4566 * returns: Z_OK if no problems
4567 * Z_ERR if an error
4568 *
4569 * Notes:
4570 * * It will not be called unless USERD_get_structured_reader_cinching
4571 * indicates that this reader does structured cinching by returning
4572 * a Z_OK.
4573 *
4574 * * It will actually be called before each geom component and before
4575 * each part variable - so if you are storing things locally, you should
4576 * make this routine be able to quickly check whether anything needs
4577 * updated or not.
4578 *
4579 * * If the stride (step) does not hit right on the max, the last element
4580 * in each direction will be shortened appropriately.
4581 * For example, if a block had 0 to 12 in the i direction,
4582 * and the user specified min = 1
4583 * max = 8
4584 * step = 3
4585 *
4586 * 0 1 2 3 4 5 6 7 8 9 10 11 12
4587 * | | | | | | | | | | | | |
4588 *
4589 * | | | |
4590 *
4591 * Namely, the coarser cell boundaries in this direction would be at 1, 4,
4592 7, and 8
4593 *
4594 *--------------------------------------------------------------------*/
4595 int
4596 USERD_set_block_range_and_stride(int part_number,
4597 int mini, int maxi, int stepi,
4598 int minj, int maxj, int stepj,
4599 int mink, int maxk, int stepk)
4603 ---- end of document ----