[OpenFOAM-2.0.x.git] / applications / utilities / postProcessing / graphics / ensightFoamReader / README_USERD_2.01
| blob | e76880e74e5ce0919e964662a9c5aed2a83bd499 |
1 README_USERD_2.01
2 =================
3 --------------------------------------
4 EnSight User Defined Reader Capability ===> (API 2.01)
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.*.
17 ***>> API 2.01 adds the capabilty of handling ghost cells.
20 API 2.01 (defined in this README_USERD_2.01 document)
21 ========
22 This new API has been defined to be more efficient and includes access to new
23 capabilities of EnSight 7.4. It lends itself closely to the EnSight "gold"
24 type format.
26 Some of its advantages are::
28 * Most intermediate temporary arrays have been eliminated, such that the user
29 defined routines write directly into internal part structures. This is a
30 considerable improvement in memory use, and improves speed as well since
31 far less memory need be allocated, initialized, etc.
33 * Parts are self contained. Coordinates, connectivity and all variables are
34 provided on a part basis. This eliminates the need for several global to
35 local coordinate mapping operations and the need for node id connectivity
36 hashing. This can greatly improve the speed at which models are loaded.
38 * Model extents can be provided directly, such that EnSight need not read
39 all the coordinate data at load time.
41 * Tensor variables are supported
43 * Complex variables are supported
45 * A routine is provided as EnSight exits, so cleanup operations such as
46 removing temporary files can be easily accomplished.
48 * Geometry and variables can be provided on different time lines (timesets).
50 * If your data format already provides boundary shell information, you can
51 use it instead of the "border" representation that EnSight would compute.
53 * Ghost cells are supported, for both unstructured and structured models.
56 ****************************************************************************
57 Note: A default dummy_gold reader and an Ensight Gold example of this new 2.01
58 user defined reader API has been included with your EnSight release.
59 Also, the SILO and ExodusII_gold reader included in the release
60 utilizes the 2.01 API.
61 ****************************************************************************
64 The process for producing a user defined reader is:
65 ---------------------------------------------------
66 1. Write code for all pertinent routines in the library (Unless someone else
67 has done this for you).
69 This is of course where the work is done by the user. The word
70 "pertinent" is used because depending on the nature of the data, some
71 of the routines in the library may be dummy routines.
73 The source code for a dummy_gold library and for various other
74 working or sample libraries is copied from the installation CD during
75 installation. These will be located in directories under:
77 $CEI_HOME/ensight76/user_defined_src/readers
79 examples:
80 --------
81 Basic dummy_gold routines provide skeleton for a new reader
82 $CEI_HOME/ensight76/user_defined_src/readers/dummy_gold
84 Sample library which reads unstructured binary EnSight Gold data
85 $CEI_HOME/ensight76/user_defined_src/readers/ensight_gold
87 You may find it useful to place your library source in this area as
88 well, but are not limited to this location.
90 * ===> The descriptions of each library routine and the order that the
91 routines are called, which is provided in this file, along with
92 the example libraries, should make it possible for you to produce
93 code for your own data reader.
96 2. Produce the dynamic shared library.
98 This is a compiling and loading process which varies according to
99 the type of machine you are on. In the user-defined-reader source
100 tree we have tried to isolate the machine dependent parts of the
101 build process using a set of files in the 'config' directory. In this
102 directory there is a configuration file for each platform on which
103 EnSight is supported. Before you can compile the installed readers
104 you should run the script called 'init' in the config directory.
106 i.e. (for UNIX)
107 cd config
108 ./init sgi_6.5_n64
109 cd ..
110 make
112 If you are compiling for Windows NT, there are two options. If you
113 have the Cygwin GNU utilities installed, you can use GNU make as for
114 Unix. Otherwise, there is a script called makeall.cmd which will
115 build all of the readers using nmake. The Makefiles in each reader
116 directory will work using either make or nmake.
118 i.e. (WIN32 Cygwin) (using nmake)
119 cd config cd config
120 sh init win32 cp win32 config
121 cd .. cd ..
122 mkdir lib
123 make makeall.cmd
125 If you have platform-specific portions of code in your reader, the
126 build system defines a set of flags which can be used within
127 #ifdef ... #endif regions in your source, as shown in the table
128 below.
130 Because the readers are now dynamically opened by EnSight, you may
131 have to include dependent libraries on your link-line to avoid having
132 unresolved symbols. If you are having problems with a reader, start
133 ensight as "ensight7 -readerdbg" and you will get feedback on any
134 problems encountered in loading a reader. If there are unresolved
135 symbols, you need to find the library which contains the missing
136 symbols and link it into your reader by adding it to the example
137 link commands below.
139 If you choose to use a different build environment for your reader,
140 you should take care to use compatible compilation flags to ensure
141 compatibilty with the EnSight executables, most notably on the SGI
142 and HP-UX 11.0 platforms, which should use the following flags:
144 sgi_6.2_o32: -mips2
145 sgi_6.2_n64: -mips4 -64
146 sgi_6.5_n32: -mips3
147 sgi_6.5_n64: -mips4 -64
148 hp_11.0_32: +DA2.0
149 hp_11.0_64: +DA2.0W
151 ______________________________________________________________________
152 | MACHINE | OS flag | SHARED LIBRARY NAME PRODUCED |
153 | TYPE |------------------------------------------------------------|
154 | | LD COMMAND USED IN MAKEFILE |
155 ======================================================================
156 ______________________________________________________________________
157 | sgi | -DSGI | libuserd-X.so |
158 | |------------------------------------------------------------|
159 | | ld -shared -all -o libuserd-X.so libuserd-X.o |
160 ----------------------------------------------------------------------
161 ______________________________________________________________________
162 | hp | -DHP | libuserd-X.sl |
163 | |------------------------------------------------------------|
164 | | ld -b -o libuserd-X.sl libuserd-X.o |
165 ----------------------------------------------------------------------
166 ______________________________________________________________________
167 | sun | -DSUN | libuserd-X.so |
168 | |------------------------------------------------------------|
169 | | ld -G -o libuserd-X.so libuserd-X.o |
170 ----------------------------------------------------------------------
171 ______________________________________________________________________
172 | dec | -DDEC | libuserd-X.so |
173 | |------------------------------------------------------------|
174 | | ld -shared -all -o libuserd-X.so libuserd-X.o -lc |
175 ----------------------------------------------------------------------
176 ______________________________________________________________________
177 | linux | -DLINUX | libuserd-X.so |
178 | |------------------------------------------------------------|
179 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
180 ----------------------------------------------------------------------
181 ______________________________________________________________________
182 | alpha | -DALINUX | libuserd-X.so |
183 | linux |------------------------------------------------------------|
184 | | ld -shared -o libuserd-X.so libuserd-X.o -lc |
185 ----------------------------------------------------------------------
186 ______________________________________________________________________
187 | ibm | -DIBM | libuserd-X.so |
188 | |------------------------------------------------------------|
189 | | ld -G -o libuserd-X.so libuserd-X.o -bnoentry -bexpall -lc |
190 ----------------------------------------------------------------------
192 Once you have created your library, you should place it in a directory
193 of your choice or in the standard reader location:
195 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
197 For example, if you created a reader for "mydata", you should create
198 the reader libuserd-mydata.so and place the file in your own reader
199 directory (see section 3 below) or in the standard location:
201 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers/libuserd-mydata.so
204 3. By default EnSight will load all readers found in the directory:
206 $CEI_HOME/ensight76/machines/$CEI_ARCH/lib_readers
208 Files with names "libuserd-X.so" (where X is a name unique to the reader)
209 are assumed to be user-defined readers.
211 There are two methods which can be used to supplement the default
212 behavior.
214 (1) A feature which is useful for site-level or user-level configuration
215 is the optional environment variable $ENSIGHT7_READER. This
216 variable directs EnSight to load all readers in the specified reader
217 directory (you should probably specify a full path) before loading
218 the built-in readers. If the same reader exists in both directories
219 (as determined by the name returned by USERD_get_name_of_reader(),
220 NOT by the filename), the locally configured reader will take
221 precedence.
223 (2) A useful feature for end-users is the use of the libuserd-devel
224 reader. EnSight will search for a reader named libuserd-devel.so
225 (.sl for HP or .dll for NT). This reader can exist anywhere in the
226 library path (see below) of the user. This is useful for an
227 individual actively developing a reader because the existence of a
228 libuserd-devel library will take precedence over any other library
229 which returns the same name from USERD_get_name_of_reader().
231 As an example, a site may install commonly used readers in a common
232 location, and users can set the ENSIGHT7_READER variable to access them:
234 setenv ENSIGHT7_READER /usr/local/lib/e7readers
236 A user working on a new reader may compile the reader and place it in
237 a directory specified by the library path:
239 cp libuserd-myreader.so ~/lib/libuserd-devel.so
240 setenv <librarypath> ~/lib:$<librarypath>
242 The user is responsible for correctly configuring the library path
243 variable in order to make use of the libuserd-devel feature. The
244 library environment variables used are:
246 Machine type Environment variable to set
247 ------------ ---------------------------
248 sgi LD_LIBRARY_PATH
249 dec LD_LIBRARY_PATH
250 sun LD_LIBRARY_PATH
251 linux LD_LIBRARY_PATH
252 alpha linux LD_LIBRARY_PATH
253 hp SHLIB_PATH
254 ibm LIBPATH
256 As always, EnSight support is available if you need it.
258 -------------------------------
259 Quick Index of Library Routines
260 -------------------------------
262 Generally Needed for UNSTRUCTURED data
263 --------------------------------------
264 USERD_get_part_coords part's node coordinates
265 USERD_get_part_node_ids part's node ids
266 USERD_get_part_elements_by_type part's element connectivites
267 USERD_get_part_element_ids_by_type part's element ids
270 Generally Needed for BLOCK data
271 --------------------------------------
272 USERD_get_block_coords_by_component block coordinates
273 USERD_get_block_iblanking block iblanking values
274 USERD_get_ghosts_in_block_flag block ghost cell existence?
275 USERD_get_block_ghost_flags block ghost cell flags
277 These routines, which formerly were only for unstructured data, will now
278 also be called for structured data if you specify that ids will be given
279 in the USERD_get_node_label_status and USERD_get_element_label_status rotuines
280 ------------------------------------------------------------------------------
281 USERD_get_part_node_ids part's node ids
282 USERD_get_part_element_ids_by_type part's element ids
285 Generally needed for either or both kinds of data
286 -------------------------------------------------
287 USERD_get_name_of_reader name of reader for GUI
288 USERD_get_reader_version provide reader version number
289 USERD_get_reader_descrip provide GUI more description(optional)
291 USERD_set_filenames filenames entered in GUI
292 USERD_set_server_number server which of how many
294 USERD_get_number_of_timesets number of timesets
295 USERD_get_timeset_description description of timeset
296 USERD_get_geom_timeset_number timeset # to use for geom
298 USERD_get_num_of_time_steps number of time steps
299 USERD_get_sol_times solution time values
300 USERD_set_time_set_and_step current timeset and time step
303 USERD_get_changing_geometry_status changing geometry?
304 USERD_get_node_label_status node labels?
305 USERD_get_element_label_status element labels?
306 USERD_get_model_extents provide model bounding extents
307 USERD_get_number_of_files_in_dataset number of files in model
308 USERD_get_dataset_query_file_info info about each model file
309 USERD_get_descrip_lines file associated description lines
310 USERD_get_number_of_model_parts number of model parts
311 USERD_get_part_build_info part/block type/descrip etc.
312 USERD_get_maxsize_info part/block allocation maximums
313 USERD_get_ghosts_in_model_flag model contains ghost cells?
315 USERD_get_border_availability part border provided?
316 USERD_get_border_elements_by_type part border conn and parent info
318 USERD_get_number_of_variables number of variables
319 USERD_get_gold_variable_info variable type/descrip etc.
320 USERD_get_var_by_component part or block variable values
321 USERD_get_constant_val constant variable's value
322 USERD_get_var_value_at_specific node's or element's variable
323 value over time
324 USERD_stop_part_building cleanup after part build routine
326 USERD_bkup archive routine
328 USERD_exit_routine cleanup upon exit routine
331 -------------------------
332 Order Routines are called
333 -------------------------
335 The various main operations are given basically in the order they will
336 be performed. Within each operation, the order the routines will be
337 called is given.
339 1. Setting name in the gui, and specifying one or two input fields
341 USERD_get_name_of_reader
342 USERD_get_reader_descrip (optional)
344 2. Getting the reader version (also distinguishes between API's)
346 USERD_get_reader_version
348 3. Setting filenames and getting timeset and time info
350 USERD_set_server_number
351 USERD_set_filenames
352 USERD_get_number_of_timesets
353 USERD_get_geom_timeset_number
355 for each timeset:
356 USERD_get_timeset_description
357 USERD_get_num_of_time_steps
358 USERD_get_sol_times
360 USERD_set_time_set_and_step
362 4. Gathering info for part builder
364 USERD_set_time_set_and_step
365 USERD_get_changing_geometry_status
366 USERD_get_node_label_status
367 USERD_get_element_label_status
368 USERD_get_number_of_files_in_dataset
369 USERD_get_dataset_query_file_info
370 USERD_get_descrip_lines (for geometry)
371 USERD_get_number_of_model_parts
372 USERD_get_gold_part_build_info
373 USERD_get_ghosts_in_model_flag
374 USERD_get_maxsize_info
375 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
376 USERD_get_model_extents OR (for model extents)
377 USERD_get_part_coords AND/OR
378 USERD_get_block_coords_by_component
380 5. Gathering Variable info
382 USERD_get_number_of_variables
383 USERD_get_gold_variable_info
385 6. Part building (per part created)
387 both unstructured and structured:
388 --------------------------------
389 USERD_set_time_set_and_step
391 if unstructured part:
392 --------------------
393 USERD_get_part_element_ids_by_type
394 USERD_get_part_elements_by_type
395 USERD_get_part_coords
396 USERD_get_part_node_ids
398 else if structured part:
399 -----------------------
400 USERD_get_block_iblanking
401 USERD_get_block_coords_by_component
402 USERD_get_block_ghost_flags (If ghost cells in part)
403 USERD_get_part_node_ids (If node ids given)
404 USERD_get_part_element_ids_by_type (If element ids given)
406 both again:
407 ----------
408 USERD_get_border_availability (If border representation
409 USERD_get_border_elements_by_type is selected)
411 USERD_stop_part_building (only once when part builder
412 dialog is closed)
414 7. Loading Variables
416 constants:
417 ---------
418 USERD_set_time_set_and_step
419 USERD_get_constant_val
421 scalars/vectors/tensors:
422 ------------------------
423 USERD_get_descrip_lines
424 USERD_set_time_set_and_step
425 USERD_get_var_by_component
427 8. Changing geometry
429 changing coords only (per part):
430 --------------------
431 USERD_set_time_set_and_step
432 USERD_get_descrip_lines
433 USERD_get_part_coords
434 USERD_get_block_coords_by_component
436 changing connectivity (per part):
437 ---------------------
438 USERD_set_time_set_and_step
439 USERD_get_descrip_lines
440 USERD_get_number_of_model_parts
441 USERD_get_gold_part_build_info
442 USERD_get_ghosts_in_model_flag
443 USERD_get_get_ghosts_in_block_flag (if any ghost cells in model)
444 USERD_get_model_extents OR
445 USERD_get_part_coords AND/OR
446 USERD_get_block_coords_by_component
447 USERD_get_part_element_ids_by_type
448 USERD_get_part_elements_by_type
449 USERD_get_part_coords
450 USERD_get_part_node_ids
451 USERD_get_block_iblanking
452 USERD_get_block_coords_by_component
453 USERD_get_block_ghost_flags (If ghost cells in part)
454 USERD_get_part_node_ids (If node ids given)
455 USERD_get_part_element_ids_by_type (If element ids given)
457 USERD_get_border_availability (If border representation
458 USERD_get_border_elements_by_type is selected)
461 9. Node or Element queries over time
463 USERD_get_var_value_at_specific
466 -----------------------
467 Detailed Specifications
468 -----------------------
470 Include files:
471 --------------
472 The following header file is required in any file containing these library
473 routines.
475 #include "global_extern.h"
479 *******************************************************************************
480 ****************************** Special Note ***********************************
481 *******************************************************************************
483 You must use the global_extern.h file associated with the proper release of
484 EnSight when you build readers. Namely, this header file can change per EnSight
485 release. For example, readers compiled for EnSight 7.3 will not run properly in
486 EnSight 7.4 and vica versa because there was a critical change in the
487 global_extern.h file between these two versions. In most cases the only thing
488 needed to produce a workable reader is to remake it with the proper header file.
490 *******************************************************************************
491 *******************************************************************************
494 Basis of arrays:
495 ---------------
496 Unless explicitly stated otherwise, all arrays are zero based - in true C
497 fashion.
500 Global variables:
501 ----------------
502 You will generally need to have a few global variables which are shared by
503 the various library routines. The detailed specifications below have assumed
504 the following are available. (Their names describe their purpose, and they
505 will be used in helping describe the details of the routines below).
507 static int Numparts_available = 0;
508 static int Num_unstructured_parts = 0;
509 static int Num_structured_blocks = 0;
511 /* Note: Numparts_available = Num_unstructured_parts + Num_structured_blocks */
513 static int Num_timesets = 1;
514 static int Current_timeset = 1;
515 static int Geom_timeset_number = 1;
517 static int Num_time_steps[Z_MAXSETS] = 1;
518 static int Current_time_step = 0;
519 static int Num_variables = 0;
520 static int Num_dataset_files = 0;
522 static int Server_Number = 1; Which server of
523 static int Tot_Servers = 1; the total number of servers
527 _________________________________________
528 -----------------------------------------
529 Library Routines (in alphabetical order):
530 _________________________________________
531 -----------------------------------------
533 --------------------------------------------------------------------
534 USERD_bkup
536 Description:
537 -----------
538 This routine is called during the EnSight archive process. You can
539 use it to save or restore info relating to your user defined reader.
541 Specification:
542 -------------
543 int USERD_bkup(FILE *archive_file,
544 int backup_type)
546 Returns:
547 -------
548 Z_OK if successful
549 Z_ERR if not successful
551 Arguments:
552 ---------
553 (IN) archive_file = The archive file pointer
555 (IN) backup_type = Z_SAVE_ARCHIVE for saving archive
556 Z_REST_ARCHIVE for restoring archive
558 Notes:
559 -----
560 * Since EnSight's archive file is saved in binary form, you should
561 also do any writing to it or reading from it in binary.
563 * You should archive any variables, which will be needed for
564 future operations, that will not be read or computed again
565 before they will be needed. These are typically global
566 variables.
568 * Make sure that the number of bytes that you write on a save and
569 the number of bytes that you read on a restore are identical!!
571 * If any of the variables you save are allocated arrays, you must
572 do the allocations before restoring into them.
574 --------------------------------------------------------------------
575 USERD_exit_routine
577 Description:
578 -----------
579 This routine is called as EnSight is exiting. It can be used to clean
580 up anything needed - such as removing temporary files, etc. - or can simply
581 be a dummy.
583 Specification:
584 -------------
585 void USERD_exit_routine( void )
587 Arguments:
588 ---------
589 none
591 --------------------------------------------------------------------
592 USERD_get_block_coords_by_component
594 Description:
595 -----------
596 Get the coordinates of a given structured block, a component at a time.
598 Specification:
599 -------------
600 int USERD_get_block_coords_by_component(int block_number,
601 int which_component,
602 float *coord_array)
604 Returns:
605 -------
606 Z_OK if successful
607 Z_ERR if not successful
609 Arguments:
610 ---------
611 (IN) block_number = The block part number
612 (1-based index of part table, namely:
614 1 ... Numparts_available.
616 It is NOT the part_id that
617 is loaded in USERD_get_gold_part_build_info)
619 (IN) which_component = Z_COMPX if x component wanted
620 = Z_COMPY if y component wanted
621 = Z_COMPZ if z component wanted
623 (OUT) coord_array = 1D array containing x,y, or z
624 coordinate component of each node
626 (Array will have been allocated
627 i*j*k for the block long)
629 Notes:
630 -----
631 * Not called unless Num_structured_blocks is > 0
633 * Will be based on Current_time_step
637 --------------------------------------------------------------------
638 USERD_get_block_iblanking
640 Description:
641 -----------
642 Get the iblanking value at each node of a block (if the block is
643 iblanked).
645 Specification:
646 -------------
647 int USERD_get_block_iblanking(int block_number,
648 int *iblank_array)
650 Returns:
651 -------
652 Z_OK if successful
653 Z_ERR if not successful
655 Arguments:
656 ---------
657 (IN) block_number = The block part number
658 (1-based index of part table, namely:
660 1 ... Numparts_available.
662 It is NOT the part_id that
663 is loaded in USERD_get_gold_part_build_info)
665 (OUT) iblank_array = 1D array containing iblank value
666 for each node.
668 (Array will have been allocated
669 i*j*k for the block long)
671 possible values are: Z_EXT = exterior
672 Z_INT = interior
673 Z_BND = boundary
674 Z_INTBND = internal boundary
675 Z_SYM = symmetry plane
677 Notes:
678 -----
679 * Not called unless Num_structured_blocks is > 0 and you have
680 some iblanked blocks
682 * Will be based on Current_time_step
686 ----------------------------------------------------------------------
687 USERD_get_block_ghost_flags
689 Description:
690 -----------
691 Get the ghost_flags value at each element of a block containing ghost cells.
693 Specification:
694 -------------
695 int USERD_get_block_ghost_flags(int block_number,
696 int *ghost_flags)
697 Returns:
698 -------
699 Z_OK if successful
700 Z_ERR if not successful
702 Arguments:
703 ---------
704 (IN) block_number = The block number
705 (1-based index of part table, namely:
707 1 ... Numparts_available.
709 It is NOT the part_id that
710 is loaded in USERD_get_gold_part_build_info)
712 (OUT) ghost_flags = 1D array containing ghost flag value
713 for each block cell.
715 (Array will have been allocated
716 (i-1)*(j-1)*(k-1) for the block long)
718 possible values are: 0 = non-ghost cell (normal cell)
719 >0 = ghost cell
721 Notes:
722 -----
723 * This routine is new in the 2.01 API
725 * This will be based on Current_time_step
727 * Only called for structured "block" parts that have some ghost cells
728 as indicated by the USERD_get_ghost_in_block_flag. The model must
729 of course also have been indicated to have some ghost cells in the
730 USERD_get_ghost_in_model_flag routine.
732 * It is sufficient to set the value to be 1 to flag as a ghost cell,
733 but the value can be any non-zero value, so you could use it to
734 indicate which block or which server (for Server-of-server use) the
735 cell is actually in.
739 --------------------------------------------------------------------
740 USERD_get_border_availability
742 Description:
743 -----------
744 Finds out if border elements are provided by the reader for the
745 desired part, or will need to be computed internally by EnSight.
747 Specification:
748 -------------
749 int USERD_get_border_availability(int part_number,
750 int number_of_elements[Z_MAXTYPE])
752 Returns:
753 -------
754 Z_OK if border elements will be provided by the reader.
755 (number_of_elements array will be loaded and
756 USERD_get_border_elements_by_type will be called)
758 Z_ERR if border elements are not available - thus EnSight must compute.
759 (USERD_get_border_elements_by_type will not be called)
762 Arguments:
763 ---------
764 (IN) part_number = The part number
765 (1-based index of part table, namely:
767 1 ... Numparts_available.
769 It is NOT the part_id that
770 is loaded in USERD_get_gold_part_build_info)
772 (OUT) number_of_elements = 2D array containing number of
773 each type of border element in
774 the part.
775 ------------
776 Possible types are:
778 Z_POINT = point
779 Z_BAR02 = 2-noded bar
780 Z_BAR03 = 3-noded bar
781 Z_TRI03 = 3-noded triangle
782 Z_TRI06 = 6-noded triangle
783 Z_QUA04 = 4-noded quadrilateral
784 Z_QUA08 = 8-noded quadrilateral
786 Notes:
787 -----
788 * Only called if border representation is used.
790 * Will be based on Current_time_step
794 --------------------------------------------------------------------
795 USERD_get_border_elements_by_type
797 Description:
798 -----------
799 Provides border element connectivity and parent information.
801 Specification:
802 -------------
803 int USERD_get_border_elements_by_type(int part_number,
804 int element_type,
805 int **conn_array,
806 short *parent_element_type,
807 int *parent_element_num)
809 Returns:
810 -------
811 Z_OK if successful
812 Z_ERR if not successful
814 Arguments:
815 ---------
816 (IN) part_number = The part 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 (IN) element_type = One of the following (See global_extern.h)
825 Z_POINT node point element
826 Z_BAR02 2 node bar
827 Z_BAR03 3 node bar
828 Z_TRI03 3 node triangle
829 Z_TRI06 6 node triangle
830 Z_QUA04 4 node quad
831 Z_QUA08 8 node quad
833 (OUT) conn_array = 2D array containing connectivity
834 of each border element of the type.
836 (Array will have been allocated
837 num_of_elements of the type by
838 connectivity length of the type)
840 ex) If number_of_elements[Z_TRI03] = 25
841 number_of_elements[Z_QUA04] = 100
842 number_of_elements[Z_QUA08] = 30
843 as obtained in:
844 USERD_get_border_availability
846 Then the allocated dimensions available
847 for this routine will be:
848 conn_array[25][3] when called with Z_TRI03
850 conn_array[100][4] when called with Z_QUA04
852 conn_array[30][8] when called with Z_QUA08
854 (OUT) parent_element_type = 1D array containing element type of the
855 parent element (the one that the border
856 element is a face/edge of).
858 (Array will have been allocated
859 num_of_elements of the type long)
861 (OUT) parent_element_num = 1D array containing element number of the
862 parent element (the one that the border
863 element is a face/edge of).
865 (Array will have been allocated
866 num_of_elements of the type long)
869 Notes:
870 -----
871 * Not called unless USERD_get_border_availability returned Z_OK
873 * Will be based on Current_time_step
877 --------------------------------------------------------------------
878 USERD_get_changing_geometry_status
880 Description:
881 -----------
882 Gets the changing geometry status for the model
884 Specification:
885 -------------
886 int USERD_get_changing_geometry_status( void )
888 Returns:
889 -------
890 Z_STATIC if geometry does not change
891 Z_CHANGE_COORDS if changing coordinates only
892 Z_CHANGE_CONN if changing connectivity
894 Arguments:
895 ---------
896 none
898 Notes:
899 -----
900 * EnSight does not support changing number of parts. But the
901 coords and/or the connectivity of the parts can change. Note that
902 a part is allowed to be empty (number of nodes and elements equal
903 to zero).
906 --------------------------------------------------------------------
907 USERD_get_constant_val
909 Description:
910 -----------
911 Get the value of a constant at a time step
913 Specification:
914 -------------
915 float USERD_get_constant_value(int which_var,
916 int imag_data)
918 Returns:
919 -------
920 Value of the requested constant variable
922 Arguments:
923 ---------
924 (IN) which_var = The variable number
926 (IN) imag_data = TRUE if want imaginary data value.
927 FALSE if want real data value.
929 Notes:
930 -----
931 * Will be based on Current_time_step
935 --------------------------------------------------------------------
936 USERD_get_dataset_query_file_info
938 Description:
939 -----------
940 Get the information about files in the dataset. Used for the
941 dataset query option within EnSight.
943 Specification:
944 -------------
945 int USERD_get_dataset_query_file_info(Z_QFILES *qfiles)
947 Returns:
948 -------
949 Z_OK if successful
950 Z_ERR if not successful
952 Arguments:
953 ---------
954 (OUT) qfiles = Structure containing information about each file
955 of the dataset. The Z_QFILES structure is defined
956 in the global_extern.h file
958 (The structure will have been allocated
959 Num_dataset_files long, with 10 description
960 lines per file).
962 qfiles[].name = The name of the file
963 (Z_MAXFILENP is the dimensioned length
964 of the name)
966 qfiles[].sizeb = The number of bytes in the file
967 (Typically obtained with a call to the
968 "stat" system routine) (Is a long)
970 qfiles[].timemod = The time the file was last modified
971 (Z_MAXTIMLEN is the dimensioned length
972 of this string)
973 (Typically obtained with a call to the
974 "stat" system routine)
976 qfiles[].num_d_lines = The number of description lines you
977 are providing from the file. Max = 10
979 qfiles[].f_desc[] = The description line(s) per file,
980 qfiles[].num_d_lines of them
981 (Z_MAXFILENP is the allocated length of
982 each line)
984 Notes:
985 -----
986 * If Num_dataset_files is 0, this routine will not be called.
987 (See USERD_get_number_of_files_in_dataset)
990 --------------------------------------------------------------------
991 USERD_get_descrip_lines
993 Description:
994 -----------
995 Get two description lines associated with geometry per time step,
996 or one description line associated with a variable per time step.
998 Specification:
999 -------------
1000 int USERD_get_descrip_lines(int which_type,
1001 int which_var,
1002 int imag_data,
1003 char line1[Z_BUFL],
1004 char line2[Z_BUFL])
1006 Returns:
1007 -------
1008 Z_OK if successful
1009 Z_ERR if not successful
1011 Arguments:
1012 ---------
1013 (IN) which_type = Z_GEOM for geometry (2 lines)
1014 = Z_VARI for variable (1 line)
1016 (IN) which_var = If it is a variable, which one.
1017 Ignored if geometry type.
1019 (IN) imag_data = TRUE if want imaginary data file.
1020 FALSE if want real data file.
1022 (OUT) line1 = The 1st geometry description line,
1023 or the variable description line.
1025 (OUT) line2 = The 2nd geometry description line
1026 Not used if variable type.
1028 Notes:
1029 -----
1030 * Will be based on Current_time_step
1032 * These are the lines EnSight can echo to the screen in
1033 annotation mode.
1037 --------------------------------------------------------------------
1038 USERD_get_element_label_status
1040 Description:
1041 -----------
1042 Answers the question as to whether element labels will be provided.
1044 Specification:
1045 -------------
1046 int USERD_get_element_label_status( void )
1048 Returns:
1049 -------
1050 TRUE if element labels will be provided
1051 FALSE if element labels will NOT be provided
1053 Arguments:
1054 ---------
1055 none
1057 Notes:
1058 -----
1059 * element lables are needed in order to do any element querying, or
1060 element labeling on-screen within EnSight.
1062 * Prior to API 2.01:
1063 -----------------
1064 For unstructured parts, you can read them from your file if
1065 available, or can assign them, etc. They need to be unique
1066 per part, and are often unique per model.
1068 API 1.0:
1069 USERD_get_element_ids_for_part is used to obtain the ids,
1070 on a part by part basis, if TRUE status is returned here.
1072 API 2.0:
1073 USERD_get_part_element_ids_by_type is used to obtain the ids,
1074 on a per part, per type basis, if TRUE status is returned here.
1076 For structured parts, EnSight will assign ids if you return a
1077 status of TRUE here. You cannot assign them youself!!
1079 * Starting at API 2.01:
1080 --------------------
1081 For both unstructured and structured parts, you can read them
1082 from your file if available, or can assign them, etc. They need
1083 to be unique per part, and are often unique per model (especially
1084 if you are dealing with a decomposed dataset).
1086 USERD_get_part_element_ids_by_type is used to obtain the ids,
1087 on an element type by part basis, if TRUE status is returned here.
1089 * Will call USERD_get_part_element_ids_by_type for each type of
1090 of each part if this routine returns TRUE.
1091 --------------------------------------------------------------------
1092 USERD_get_geom_timeset_number -
1094 Description:
1095 -----------
1096 Gets the timeset number to be used for geometry
1098 Specification:
1099 -------------
1100 int USERD_get_geom_timeset_number( void )
1102 Returns:
1103 -------
1104 Geom_timeset_number = The timeset number that will be used for geometry.
1105 For example, if USERD_get_number_of timesets
1106 returns 2, the valid timeset numbers would be
1107 1 or 2.
1109 Arguments:
1110 ---------
1111 none
1113 Notes:
1114 -----
1115 * If your model is static, which you indicated by returning a zero
1116 in USERD_get_number_of_timesets, you can return a zero here as well.
1120 --------------------------------------------------------------------
1121 USERD_get_gold_part_build_info
1123 Description:
1124 -----------
1125 Gets the info needed for the part building process.
1127 Specification:
1128 -------------
1129 int USERD_get_gold_part_build_info(int *part_id,
1130 int *part_types,
1131 char *part_description[Z_BUFL],
1132 int *number_of_nodes,
1133 int *number_of_elements[Z_MAXTYPE],
1134 int *ijk_dimensions[3],
1135 int *iblanking_options[6])
1137 Returns:
1138 -------
1139 Z_OK if successful
1140 Z_ERR if not successful
1142 Arguments:
1143 ---------
1144 (OUT) part_id = Array containing the external part
1145 ids for each of the model parts.
1147 IMPORTANT:
1148 Parts numbers must be >= 1, because
1149 of the way they are used in the GUI
1151 *******************************************
1152 The ids provided here are the numbers by
1153 which the parts will be referred to in the
1154 GUI (if possible). They are basically
1155 labels as far as you are concerned.
1157 Note: The part numbers you pass to routines
1158 which receive a part_number or block_number
1159 or which_part as an argument are the 1-based
1160 table index of the parts!
1162 example: If Numparts_available = 3
1164 Table index part_id
1165 ----------- -------
1166 1 13
1167 2 57
1168 3 125
1170 ^ ^
1171 | |
1172 | These are placed in:
1173 | part_id[0] = 13
1174 | part_id[1] = 57
1175 | part_id[2] = 125
1176 | for GUI labeling purposes.
1177 |
1178 These implied table indices are the part_number,
1179 block_number, or which_part numbers that you would
1180 pass to routines like:
1182 USERD_get_part_coords(int part_number,...
1183 USERD_get_part_node_ids(int part_number,...
1184 USERD_get_part_elements_by_type(int part_number,...
1185 USERD_get_part_element_ids_by_type(int part_number,...
1186 USERD_get_block_coords_by_component(int block_number,...
1187 USERD_get_block_iblanking(int block_number,...
1188 USERD_get_block_ghost_flags(int block_number,...
1189 USERD_get_ghosts_in_block_flag(int block_number)
1190 USERD_get_border_availability(int part_number,...
1191 USERD_get_border_elements_by_type(int part_number,...
1192 USERD_get_var_by_component(int which_variable,
1193 int which_part,...
1194 USERD_get_var_value_at_specific(int which_var,
1195 int which_node_or_elem,
1196 int which_part,...
1197 ********************************************
1199 (Array will have been allocated
1200 Numparts_available long)
1202 (OUT) part_types = Array containing one of the
1203 following for each model part:
1205 Z_UNSTRUCTURED or
1206 Z_STRUCTURED or
1207 Z_IBLANKED
1209 (Array will have been allocated
1210 Numparts_available long)
1212 (OUT) part_description = Array containing a description
1213 for each of the model parts
1215 (Array will have been allocated
1216 Numparts_available by Z_BUFL
1217 long)
1219 (OUT) number_of_nodes = Number of unstructured nodes in the part
1221 (Array will have been allocated
1222 Numparts_available long)
1224 (OUT) number_of_elements = 2D array containing number of
1225 each type of element for each
1226 unstructured model part.
1227 ------------
1228 Possible types are:
1230 Z_POINT = point
1231 Z_BAR02 = 2-noded bar
1232 Z_BAR03 = 3-noded bar
1233 Z_TRI03 = 3-noded triangle
1234 Z_TRI06 = 6-noded triangle
1235 Z_QUA04 = 4-noded quadrilateral
1236 Z_QUA08 = 8-noded quadrilateral
1237 Z_TET04 = 4-noded tetrahedron
1238 Z_TET10 = 10-noded tetrahedron
1239 Z_PYR05 = 5-noded pyramid
1240 Z_PYR13 = 13-noded pyramid
1241 Z_PEN06 = 6-noded pentahedron
1242 Z_PEN15 = 15-noded pentahedron
1243 Z_HEX08 = 8-noded hexahedron
1244 Z_HEX20 = 20-noded hexahedron
1246 Z_G_POINT = ghost node point element
1247 Z_G_BAR02 = 2 node ghost bar
1248 Z_G_BAR03 = 3 node ghost bar
1249 Z_G_TRI03 = 3 node ghost triangle
1250 Z_G_TRI06 = 6 node ghost triangle
1251 Z_G_QUA04 = 4 node ghost quad
1252 Z_G_QUA08 = 8 node ghost quad
1253 Z_G_TET04 = 4 node ghost tetrahedron
1254 Z_G_TET10 = 10 node ghost tetrahedron
1255 Z_G_PYR05 = 5 node ghost pyramid
1256 Z_G_PYR13 = 13 node ghost pyramid
1257 Z_G_PEN06 = 6 node ghost pentahedron
1258 Z_G_PEN15 = 15 node ghost pentahedron
1259 Z_G_HEX08 = 8 node ghost hexahedron
1260 Z_G_HEX20 = 20 node ghost hexahedron
1262 (Ignored unless Z_UNSTRUCTURED type)
1264 (Array will have been allocated
1265 Numparts_available by
1266 Z_MAXTYPE long)
1268 (OUT) ijk_dimensions = 2D array containing ijk dimensions
1269 for each structured model part.
1270 ----------
1271 (Ignored if Z_UNSTRUCTURED type)
1273 (Array will have been allocated
1274 Numparts_available by 3 long)
1276 ijk_dimensions[][0] = I dimension
1277 ijk_dimensions[][1] = J dimension
1278 ijk_dimensions[][2] = K dimension
1280 (OUT) iblanking_options = 2D array containing iblanking
1281 options possible for each
1282 structured model part.
1283 ----------
1284 (Ignored unless Z_IBLANKED type)
1286 (Array will have been allocated
1287 Numparts_available by 6 long)
1289 iblanking_options[][Z_EXT] = TRUE if external (outside)
1290 [][Z_INT] = TRUE if internal (inside)
1291 [][Z_BND] = TRUE if boundary
1292 [][Z_INTBND] = TRUE if internal boundary
1293 [][Z_SYM] = TRUE if symmetry surface
1296 Notes:
1297 -----
1298 * If you haven't built a table of pointers to the different parts,
1299 you might want to do so here as you gather the needed info.
1301 * Will be based on Current_time_step
1304 --------------------------------------------------------------------
1305 USERD_get_gold_variable_info
1307 Description:
1308 -----------
1309 Get the variable descriptions, types and filenames
1311 Specification:
1312 -------------
1313 int USERD_get_gold_variable_info(char **var_description,
1314 char **var_filename,
1315 int *var_type,
1316 int *var_classify,
1317 int *var_complex,
1318 char **var_ifilename,
1319 float *var_freq,
1320 int *var_contran,
1321 int *var_timeset)
1323 Returns:
1324 -------
1325 Z_OK if successful
1326 Z_ERR if not successful
1328 Arguments:
1329 ---------
1330 (OUT) var_description = Variable descriptions
1332 (Array will have been allocated
1333 Num_variables by Z_BUFL long)
1335 variable description restrictions:
1336 ----------------------------------
1337 1. Only first 19 characters used in EnSight.
1338 2. Leading and trailing whitespace will be removed by EnSight.
1339 3. Illegal characters will be replaced by underscores.
1340 4. Thay may not start with a numeric digit.
1341 4. No two variables may have the same description.
1344 (OUT) var_filename = Variable real filenames
1346 (Array will have been allocated
1347 Num_variables by Z_BUFL long)
1349 (OUT) var_type = Variable type
1351 (Array will have been allocated
1352 Num_variables long)
1354 types are: Z_CONSTANT
1355 Z_SCALAR
1356 Z_VECTOR
1357 Z_TENSOR
1358 Z_TENSOR9
1360 (OUT) var_classify = Variable classification
1362 (Array will have been allocated
1363 Num_variables long)
1365 types are: Z_PER_NODE
1366 Z_PER_ELEM
1368 (OUT) var_complex = TRUE if complex, FALSE otherwise
1370 (Array will have been allocated
1371 Num_variables long)
1373 (OUT) var_ifilename = Variable imaginary filenames (if complex)
1375 (Array will have been allocated
1376 Num_variables by Z_BUFL long)
1378 (OUT) var_freq = complex frequency (if complex)
1380 (Array will have been allocated
1381 Num_variables long)
1383 (OUT) var_contran = TRUE if constant changes per time step
1384 FALSE if constant truly same at all time steps
1386 (Array will have been allocated
1387 Num_variables long)
1389 (OUT) var_timeset = Timeset the variable will use (1 based).
1390 (For static models, set it to 1)
1392 (Array will have been allocated
1393 Num_variables long)
1395 For example: If USERD_get_number_of_timesets
1396 returns 2, the valid
1397 timeset_number's would be 1 or 2
1400 Notes:
1401 -----
1402 * The implied variable numbers apply, but be aware that the
1403 arrays are zero based.
1404 So for variable 1, will need to provide var_description[0]
1405 var_filename[0]
1406 var_type[0]
1407 var_classify[0]
1408 var_complex[0]
1409 var_ifilename[0]
1410 var_freq[0]
1411 var_contran[0]
1412 var_timeset[0]
1415 for variable 2, will need to provide var_description[1]
1416 var_filename[1]
1417 var_type[1]
1418 var_classify[1]
1419 var_complex[1]
1420 var_ifilename[1]
1421 var_freq[1]
1422 var_contran[1]
1423 var_timeset[1]
1424 etc.
1429 --------------------------------------------------------------------
1430 USERD_get_ghosts_in_block_flag
1432 Description:
1433 -----------
1434 Gets whether ghost cells present in block or not
1436 Specification:
1437 -------------
1438 int USERD_get_ghosts_in_block_flag(int block_number)
1440 Returns:
1441 -------
1442 TRUE if any ghost cells in this structured part
1443 FALSE if no ghost cells in this structured part
1445 Arguments:
1446 ---------
1447 (IN) block_number = The block part number
1448 (1-based index of part table, namely:
1450 1 ... Numparts_available.
1452 It is NOT the part_id that
1453 is loaded in USERD_get_gold_part_build_info)
1455 Notes:
1456 -----
1457 * This routine is new in the 2.01 API
1458 * This will be based on Current_time_step
1460 * Intended for structured parts only, value will be ignored for
1461 unstructured parts
1466 --------------------------------------------------------------------
1467 USERD_get_maxsize_info
1469 Description:
1470 -----------
1471 Gets maximum part sizes for efficient memory allocation.
1473 Transient models (especially those that increase in size) can cause
1474 reallocations, at time step changes, to keep chewing up more and
1475 more memory. The way to avoid this is to know what the maximum
1476 size of such memory will be, and allocate for this maximum initially.
1478 Accordingly, if you choose to provide this information (it is optional),
1479 EnSight will take advantage of it.
1482 Specification:
1483 -------------
1484 int USERD_get_maxsize_info(int *max_number_of_nodes,
1485 int *max_number_of_elements[Z_MAXTYPE],
1486 int *max_ijk_dimensions[3])
1488 Returns:
1489 -------
1490 Z_OK if supplying maximum data
1491 Z_ERR if not supplying maximum data, or some error occurred
1492 while trying to obtain it.
1494 Arguments:
1495 ---------
1496 (OUT) max_number_of_nodes = Maximum number of unstructured nodes
1497 in the part (over all time).
1499 (Array will have been allocated
1500 Numparts_available long)
1502 (OUT) max_number_of_elements = 2D array containing maximum number of
1503 each type of element for each
1504 unstructured model part (over all time).
1505 ------------
1506 Possible types are:
1508 Z_POINT = point
1509 Z_BAR02 = 2-noded bar
1510 Z_BAR03 = 3-noded bar
1511 Z_TRI03 = 3-noded triangle
1512 Z_TRI06 = 6-noded triangle
1513 Z_QUA04 = 4-noded quadrilateral
1514 Z_QUA08 = 8-noded quadrilateral
1515 Z_TET04 = 4-noded tetrahedron
1516 Z_TET10 = 10-noded tetrahedron
1517 Z_PYR05 = 5-noded pyramid
1518 Z_PYR13 = 13-noded pyramid
1519 Z_PEN06 = 6-noded pentahedron
1520 Z_PEN15 = 15-noded pentahedron
1521 Z_HEX08 = 8-noded hexahedron
1522 Z_HEX20 = 20-noded hexahedron
1524 Z_G_POINT = ghost node point element
1525 Z_G_BAR02 = 2 node ghost bar
1526 Z_G_BAR03 = 3 node ghost bar
1527 Z_G_TRI03 = 3 node ghost triangle
1528 Z_G_TRI06 = 6 node ghost triangle
1529 Z_G_QUA04 = 4 node ghost quad
1530 Z_G_QUA08 = 8 node ghost quad
1531 Z_G_TET04 = 4 node ghost tetrahedron
1532 Z_G_TET10 = 10 node ghost tetrahedron
1533 Z_G_PYR05 = 5 node ghost pyramid
1534 Z_G_PYR13 = 13 node ghost pyramid
1535 Z_G_PEN06 = 6 node ghost pentahedron
1536 Z_G_PEN15 = 15 node ghost pentahedron
1537 Z_G_HEX08 = 8 node ghost hexahedron
1538 Z_G_HEX20 = 20 node ghost hexahedron
1540 (Ignored unless Z_UNSTRUCTURED type)
1542 (Array will have been allocated
1543 Numparts_available by
1544 Z_MAXTYPE long)
1546 (OUT) max_ijk_dimensions = 2D array containing maximum ijk dimensions
1547 for each structured model part (over all time).
1548 ----------
1549 (Ignored if Z_UNSTRUCTURED type)
1551 (Array will have been allocated
1552 Numparts_available by 3 long)
1554 max_ijk_dimensions[][0] = maximum I dimension
1555 max_ijk_dimensions[][1] = maximum J dimension
1556 max_ijk_dimensions[][2] = maximum K dimension
1558 Notes:
1559 -----
1560 * You need to have first called USERD_get_number_of_model_parts and
1561 USERD_get_gold_part_build_info, so Numparts_available is known and
1562 so EnSight will know what the type is (Z_UNSTRUCTURED, Z_STRUCTURED,
1563 or Z_IBLANKED) of each part.
1565 * This will NOT be based on Current_time_step - it is to be the maximum
1566 values over all time!!
1568 * This information is optional. If you return Z_ERR, Ensight will still
1569 process things fine, reallocating as needed, etc. However, for
1570 large transient models you will likely use considerably more memory
1571 and take more processing time for the memory reallocations. So, if it
1572 is possible to provide this information "up front", it is recommended
1573 to do so.
1576 --------------------------------------------------------------------
1577 USERD_get_ghosts_in_model_flag
1579 Description:
1580 -----------
1581 Answers the question as to whether any ghost cells in the model.
1583 Specification:
1584 -------------
1585 int USERD_get_ghosts_in_model_flag( void )
1587 Returns:
1588 -------
1589 TRUE if any ghost cells in the model
1590 FALSE if no ghost cells in the model
1592 Arguments:
1593 ---------
1595 Notes:
1596 -----
1597 * This routine is new in the 2.01 API
1601 --------------------------------------------------------------------
1602 USERD_get_model_extents
1604 Description:
1605 -----------
1606 Gets the model bounding box extents. If this routine supplys them
1607 EnSight will not have to spend time doing so. If this routine
1608 returns Z_ERR, EnSight will have to take the time to touch all the
1609 nodes and gather the extent info.
1611 Specification:
1612 -------------
1613 int USERD_get_model_extents(float extents[6])
1615 Returns:
1616 -------
1617 Z_OK if successful
1618 Z_ERR if not successful (whereupon EnSight will determine by reading
1619 all coords of all parts)
1621 Arguments:
1622 ---------
1623 (OUT) extents[0] = min x
1624 [1] = max x
1625 [2] = min y
1626 [3] = max y
1627 [4] = min z
1628 [5] = max z
1630 Notes:
1631 -----
1632 * This will be based on Current_time_step
1635 --------------------------------------------------------------------
1636 USERD_get_name_of_reader
1638 Description:
1639 -----------
1640 Gets the name of your user defined reader. The user interface will
1641 ask for this and include it in the available reader list.
1643 Specification:
1644 -------------
1645 int USERD_get_name_of_reader(char reader_name[Z_MAX_USERD_NAME],
1646 int *two_fields)
1648 Returns:
1649 -------
1650 Z_OK if successful
1651 Z_ERR if not successful
1653 Arguments:
1654 ---------
1655 (OUT) reader_name = the name of the your reader or data format.
1656 (max length is Z_MAX_USERD_NAME, which is 20)
1658 (OUT) *two_fields = FALSE if only one data field required
1659 in the data dialog of EnSight.
1660 TRUE if two data fields required.
1662 Notes:
1663 -----
1664 * Always called. Please be sure to provide a name for your custom
1665 reader format.
1669 --------------------------------------------------------------------
1670 USERD_get_node_label_status
1672 Description:
1673 -----------
1674 Answers the question as to whether node labels will be provided.
1676 Specification:
1677 -------------
1678 int USERD_get_node_label_status( void )
1680 Returns:
1681 -------
1682 TRUE if node labels will be provided
1683 FALSE if node labels will NOT be provided
1685 Arguments:
1686 ---------
1687 none
1689 Notes:
1690 -----
1691 * Node ids are needed in order to do any node querying, or node
1692 labeling on-screen within EnSight.
1694 * Prior to API 2.01:
1695 -----------------
1696 For unstructured parts, you can read them from your file if
1697 available, or can assign them, etc. They need to be unique
1698 per part, and are often unique per model. They must also be
1699 positive numbers greater than zero.
1701 USERD_get_part_node_ids is used to obtain the ids, if the
1702 status returned here is TRUE.
1704 (Unlike API 1.0, where the connectivity of elements had to be
1705 according to the node ids - API 2.0's element connectivities
1706 are not affected either way by the status here.)
1708 For structured parts, EnSight will assign ids if you return a
1709 status of TRUE here. You cannot assign them yourself!!
1711 * Starting at API 2.01:
1712 --------------------
1713 For both unstructured and structured parts, you can read them
1714 from your file if available, or can assign them, etc. They need
1715 to be unique per part, and are often unique per model. They must
1716 also be positive numbers greater than zero.
1718 USERD_get_part_node_ids is used to obtain the ids, if the
1719 status returned here is TRUE.
1721 * Will call USERD_get_part_node_ids for each part if this routine
1722 returns TRUE.
1726 --------------------------------------------------------------------
1727 USERD_get_num_of_time_steps
1729 Description:
1730 -----------
1731 Gets the number of time steps of data available for desired timeset.
1733 Specification:
1734 -------------
1735 int USERD_get_num_of_time_steps( int timeset_number )
1737 Returns:
1738 -------
1739 Number of time steps in timeset (>0 if okay, <=0 if problems).
1741 Arguments:
1742 ---------
1743 (IN) timeset number = the timeset number
1745 For example: If USERD_get_number_of_timesets
1746 returns 2, the valid
1747 timeset_number's would be 1 and 2
1749 Notes:
1750 -----
1751 * This should be >= 1 1 indicates a static model
1752 >1 indicates a transient model
1754 * Num_time_steps[timeset_number] would be set here
1758 --------------------------------------------------------------------
1759 USERD_get_number_of_files_in_dataset
1761 Description:
1762 -----------
1763 Get the total number of files in the dataset. Used for the
1764 dataset query option within EnSight.
1766 Specification:
1767 -------------
1768 int USERD_get_number_of_files_in_dataset( void )
1770 Returns:
1771 -------
1772 The total number of files in the dataset.
1774 Arguments:
1775 ---------
1776 none
1778 Notes:
1779 -----
1780 * You can be as complete as you want about this. If you don't
1781 care about the dataset query option, return a value of 0
1782 If you only want certain files, you can just include them. But,
1783 you will need to supply the info in USERD_get_dataset_query_file_info
1784 for each file you include here.
1786 * Num_dataset_files would be set here
1790 --------------------------------------------------------------------
1791 USERD_get_number_of_model_parts
1793 Description:
1794 -----------
1795 Gets the total number of unstructured and structured parts
1796 in the model, for which you can supply information.
1798 Specification:
1799 -------------
1800 int USERD_get_number_of_model_parts( void )
1802 Returns:
1803 -------
1804 Number of parts (>0 if okay, <=0 if problems).
1806 Arguments:
1807 ---------
1808 none
1810 Notes:
1811 -----
1812 * If going to have to read down through the parts in order to
1813 know how many, you may want to build a table of pointers to
1814 the various parts, so you can easily get to particular parts in
1815 later processes. If you can simply read the number of parts
1816 at the head of the file, then you would probably not build the
1817 table at this time.
1819 * This routine would set Numparts_available, which is equal to
1820 Num_unstructured_parts + Num_structured_blocks.
1824 --------------------------------------------------------------------
1825 USERD_get_number_of_timesets
1827 Description:
1828 -----------
1829 Gets the number of timesets used in the model.
1831 Specification:
1832 -------------
1833 int USERD_get_number_of_timesets( void )
1835 Returns:
1836 -------
1837 Number of timesets in the model
1839 Arguments:
1840 ---------
1841 none
1843 Notes:
1844 -----
1845 * Num_timesets would be set here
1847 * If you have a static model, both geometry and variables, you should
1848 return a value of zero.
1850 * If you have a transient model, then you should return one or more.
1852 For example:
1854 Geometry Variables No. of timesets
1855 --------- ------------------------------ ---------------
1856 static static 0
1857 static transient, all using same timeset 1
1859 transient transient, all using same timeset as geom 1
1861 static transient, using 3 different timesets 3
1863 transient transient, using 3 different timesets and
1864 none of them the same as the
1865 geometry timeset 4
1866 etc.
1868 NOTE: ALL GEOMETRY MUST USE THE SAME TIMESET!!! You will have to provide
1869 the timeset number to use
1870 for geometry in:
1871 USERD_get_geom_timeset_number
1873 Variables can use the same timeset as the geometry, or can use
1874 other timesets. More than one variable can use the same timeset.
1876 example: changing geometry at 5 steps, 0.0, 1.0, 2.0, 3.0, 4.0
1877 variable 1 provided at these same five steps
1878 variable 2 provided at 3 steps, 0.5, 1.25, 3.33
1880 This routine should return a value of 2, because only
1881 two different timesets are needed. Timeset 1 would be for the
1882 geometry and variable 1 (they both use it). Timeset 2 would
1883 be for variable 2, which needs its own in this case.
1889 --------------------------------------------------------------------
1890 USERD_get_number_of_variables
1892 Description:
1893 -----------
1894 Get the number of variables for which you will be providing info.
1896 Specification:
1897 -------------
1898 int USERD_get_number_of_variables( void )
1900 Returns:
1901 -------
1902 Number of variables (includes constant, scalar, vector and tensor types)
1903 (>=0 if okay, <0 if problem)
1905 Arguments:
1906 ---------
1907 none
1909 Notes:
1910 -----
1911 *****************************************************************
1912 * Variable numbers, by which references will be made, are implied
1913 here. If you say there are 3 variables, the variable numbers
1914 will be 1, 2, and 3.
1915 *****************************************************************
1917 * Num_variables would be set here
1921 --------------------------------------------------------------------
1922 USERD_get_part_coords
1924 Description:
1925 -----------
1926 Gets the coordinates for an unstructured part.
1928 Specification:
1929 -------------
1930 int USERD_get_part_coords(int part_number, float **coord_array)
1932 Returns:
1933 -------
1934 Z_OK if successful
1935 Z_ERR if not successful
1937 Arguments:
1938 ---------
1939 (IN) part_number = The part number
1940 (1-based index of part table, namely:
1942 1 ... Numparts_available.
1944 It is NOT the part_id that
1945 is loaded in USERD_get_gold_part_build_info)
1947 (OUT) coord_array = 2D float array which contains,
1948 x,y,z coordinates of each node
1949 in the part.
1951 (IMPORTANT: The second dimension of this aray is 1-based!!!)
1953 (Array will have been allocated
1954 3 by (number_of_nodes + 1) for the part
1955 long - see USERD_get_gold_part_build_info)
1958 ex) If number_of_nodes = 100
1959 as obtained in:
1960 USERD_get_gold_part_build_info
1962 Then the allocated dimensions of the
1963 pointer sent to this routine will be:
1964 coord_array[3][101]
1966 Ignore the coord_array[0][0]
1967 coord_array[1][0]
1968 coord_array[2][0] locations and start
1969 the node coordinates at:
1970 coord_array[0][1]
1971 coord_array[1][1]
1972 coord_array[2][1]
1974 coord_array[0][2]
1975 coord_array[1][2]
1976 coord_array[2][2]
1978 etc.
1980 Notes:
1981 -----
1982 * Not called unless Num_unstructured_parts is > 0
1984 * Will be based on Current_time_step
1987 --------------------------------------------------------------------
1988 USERD_get_part_element_ids_by_type
1990 Description:
1991 -----------
1992 Gets the ids for the elements of a particular type for an unstructured
1993 or structured part.
1995 Specification:
1996 -------------
1997 int USERD_get_part_element_ids_by_type(int part_number,
1998 int element_type,
1999 int *elemid_array)
2001 Returns:
2002 -------
2003 Z_OK if successful
2004 Z_ERR if not successful
2006 Arguments:
2007 ---------
2008 (IN) part_number = The part number
2009 (1-based index of part table, namely:
2011 1 ... Numparts_available.
2013 It is NOT the part_id that
2014 is loaded in USERD_get_gold_part_build_info)
2016 (IN) element_type = One of the following (See global_extern.h)
2017 Z_POINT node point element
2018 Z_BAR02 2 node bar
2019 Z_BAR03 3 node bar
2020 Z_TRI03 3 node triangle
2021 Z_TRI06 6 node triangle
2022 Z_QUA04 4 node quad
2023 Z_QUA08 8 node quad
2024 Z_TET04 4 node tetrahedron
2025 Z_TET10 10 node tetrahedron
2026 Z_PYR05 5 node pyramid
2027 Z_PYR13 13 node pyramid
2028 Z_PEN06 6 node pentahedron
2029 Z_PEN15 15 node pentahedron
2030 Z_HEX08 8 node hexahedron
2031 Z_HEX20 20 node hexahedron
2033 Z_G_POINT ghost node point element
2034 Z_G_BAR02 2 node ghost bar
2035 Z_G_BAR03 3 node ghost bar
2036 Z_G_TRI03 3 node ghost triangle
2037 Z_G_TRI06 6 node ghost triangle
2038 Z_G_QUA04 4 node ghost quad
2039 Z_G_QUA08 8 node ghost quad
2040 Z_G_TET04 4 node ghost tetrahedron
2041 Z_G_TET10 10 node ghost tetrahedron
2042 Z_G_PYR05 5 node ghost pyramid
2043 Z_G_PYR13 13 node ghost pyramid
2044 Z_G_PEN06 6 node ghost pentahedron
2045 Z_G_PEN15 15 node ghost pentahedron
2046 Z_G_HEX08 8 node ghost hexahedron
2047 Z_G_HEX20 20 node ghost hexahedron
2049 (OUT) elemid_array = 1D array containing id of each
2050 element of the type.
2052 (Array will have been allocated
2053 number_of_elements of the type long)
2055 ex) If number_of_elements[Z_TRI03] = 25
2056 number_of_elements[Z_QUA04] = 100
2057 number_of_elements[Z_HEX08] = 30
2058 as obtained in:
2059 USERD_get_gold_part_build_info
2061 Then the allocated dimensions available
2062 for this routine will be:
2063 conn_array[25] when called with Z_TRI03
2065 conn_array[100] when called with Z_QUA04
2067 conn_array[30] when called with Z_HEX08
2069 Notes:
2070 -----
2071 * Not called unless element label status is set to TRUE in
2072 USERD_get_element_label_status
2074 * Will be based on Current_time_step
2078 --------------------------------------------------------------------
2079 USERD_get_part_elements_by_type
2081 Description:
2082 -----------
2083 Gets the connectivities for the elements of a particular type in an
2084 unstructured part
2086 Specification:
2087 -------------
2088 int USERD_get_part_elements_by_type(int part_number,
2089 int element_type,
2090 int **conn_array)
2092 Returns:
2093 -------
2094 Z_OK if successful
2095 Z_ERR if not successful
2097 Arguments:
2098 ---------
2099 (IN) part_number = The part number
2100 (1-based index of part table, namely:
2102 1 ... Numparts_available.
2104 It is NOT the part_id that
2105 is loaded in USERD_get_gold_part_build_info)
2107 (IN) element_type = One of the following (See global_extern.h)
2108 Z_POINT node point element
2109 Z_BAR02 2 node bar
2110 Z_BAR03 3 node bar
2111 Z_TRI03 3 node triangle
2112 Z_TRI06 6 node triangle
2113 Z_QUA04 4 node quad
2114 Z_QUA08 8 node quad
2115 Z_TET04 4 node tetrahedron
2116 Z_TET10 10 node tetrahedron
2117 Z_PYR05 5 node pyramid
2118 Z_PYR13 13 node pyramid
2119 Z_PEN06 6 node pentahedron
2120 Z_PEN15 15 node pentahedron
2121 Z_HEX08 8 node hexahedron
2122 Z_HEX20 20 node hexahedron
2124 Z_G_POINT ghost node point element
2125 Z_G_BAR02 2 node ghost bar
2126 Z_G_BAR03 3 node ghost bar
2127 Z_G_TRI03 3 node ghost triangle
2128 Z_G_TRI06 6 node ghost triangle
2129 Z_G_QUA04 4 node ghost quad
2130 Z_G_QUA08 8 node ghost quad
2131 Z_G_TET04 4 node ghost tetrahedron
2132 Z_G_TET10 10 node ghost tetrahedron
2133 Z_G_PYR05 5 node ghost pyramid
2134 Z_G_PYR13 13 node ghost pyramid
2135 Z_G_PEN06 6 node ghost pentahedron
2136 Z_G_PEN15 15 node ghost pentahedron
2137 Z_G_HEX08 8 node ghost hexahedron
2138 Z_G_HEX20 20 node ghost hexahedron
2141 (OUT) conn_array = 2D array containing connectivity
2142 of each element of the type.
2144 (Array will have been allocated
2145 num_of_elements of the type by
2146 connectivity length of the type)
2148 ex) If number_of_elements[Z_TRI03] = 25
2149 number_of_elements[Z_QUA04] = 100
2150 number_of_elements[Z_HEX08] = 30
2151 as obtained in:
2152 USERD_get_gold_part_build_info
2154 Then the allocated dimensions available
2155 for this routine will be:
2156 conn_array[25][3] when called with Z_TRI03
2158 conn_array[100][4] when called with Z_QUA04
2160 conn_array[30][8] when called with Z_HEX08
2162 Notes:
2163 -----
2164 * Not called unless Num_unstructured_parts is > 0
2166 * Will be based on Current_time_step
2169 --------------------------------------------------------------------
2170 USERD_get_part_node_ids
2172 Description:
2173 -----------
2174 Gets the node ids of an unstructured or structured part.
2176 Specification:
2177 -------------
2178 int USERD_get_part_node_ids(int part_number, int *nodeid_array)
2180 Returns:
2181 -------
2182 Z_OK if successful
2183 Z_ERR if not successful
2185 Arguments:
2186 ---------
2187 (IN) part_number = The part number
2188 (1-based index of part table, namely:
2190 1 ... Numparts_available.
2192 It is NOT the part_id that
2193 is loaded in USERD_get_gold_part_build_info)
2195 (OUT) nodeid_array = 1D array containing node ids of
2196 each node in the part.
2198 (IMPORTANT: This array is 1-based!!!)
2200 (Array will have been allocated
2201 (number_of_nodes + 1) for the part long
2202 see USERD_get_gold_part_build_info)
2204 ex) If number_of_nodes = 100
2205 as obtained in:
2206 USERD_get_gold_part_build_info
2208 Then the allocated dimensions of the
2209 pointer sent to this routine will be:
2210 nodeid_array[101]
2212 Ignore the nodeid_array[0] location and start
2213 the node ids at:
2214 nodeid_array[1]
2216 nodeid_array[2]
2218 etc.
2220 Notes:
2221 -----
2222 * Not called unless node label status is TRUE, as returned from
2223 USERD_get_node_label_status
2225 * Will be based on Current_time_step
2227 * The ids are purely labels, used when displaying or querying node ids.
2228 However, any node id < 0 will never be displayed
2231 --------------------------------------------------------------------
2232 USERD_get_reader_descrip
2234 Description:
2235 -----------
2236 Gets the description of the reader, so gui can give more info
2238 Specification:
2239 -------------
2240 int USERD_get_reader_descrip(char descrip[Z_MAXFILENP])
2242 Returns:
2243 -------
2244 Z_OK if successful
2245 Z_ERR if not successful
2247 Arguments:
2248 ---------
2249 (OUT) descrip = the description of the reader (max length is MAXFILENP,
2250 which is 255)
2252 Notes:
2253 -----
2254 * OPTIONAL ROUTINE! You can have it or not.
2257 --------------------------------------------------------------------
2258 USERD_get_reader_version
2260 Description:
2261 -----------
2262 Gets the version number of the user defined reader
2264 Specification:
2265 -------------
2266 int USERD_get_reader_version(char version_number[Z_MAX_USERD_NAME])
2268 Returns:
2269 -------
2270 Z_OK if successful
2271 Z_ERR if not successful (and will assume is version 1.0)
2273 Arguments:
2274 ---------
2275 (OUT) version_number = the version number of the reader
2276 (max length is Z_MAX_USERD_NAME, which
2277 is 20)
2279 Notes:
2280 -----
2281 * This needs to be "2.000" or greater. Otherwise EnSight will assume
2282 this reader is API 1.0
2284 * should set it to "2.010" for this version of the API
2289 --------------------------------------------------------------------
2290 USERD_get_sol_times
2292 Description:
2293 -----------
2294 Get the solution times associated with each time step for
2295 desired timeset.
2297 Specification:
2298 -------------
2299 int USERD_get_sol_times(int timeset_number,
2300 float *solution_times)
2302 Returns:
2303 -------
2304 Z_OK if successful
2305 Z_ERR if not successful
2307 Arguments:
2308 ---------
2309 (IN) timeset_number = the timeset number
2311 For example: If USERD_get_number_of_timesets
2312 returns 2, the valid
2313 timeset_number's would be 1 and 2
2315 (OUT) solution_times = 1D array of solution times per time step
2317 (Array will have been allocated
2318 Num_time_steps[timeset_number] long)
2320 Notes:
2321 -----
2322 * The solution times must be non-negative and increasing.
2326 --------------------------------------------------------------------
2327 USERD_get_timeset_description -
2329 Description:
2330 -----------
2331 Get the description to associate with the desired timeset.
2333 Specification:
2334 -------------
2335 int USERD_get_timeset_description(int timeset_number,
2336 char timeset_description[Z_BUFL])
2338 Returns:
2339 -------
2340 Z_OK if successful
2341 Z_ERR if not successful
2343 Arguments:
2344 ---------
2345 (IN) timeset_number = the timeset number
2347 For example: If USERD_get_number_of_timesets
2348 returns 2, the valid
2349 timeset_number's would be 1 and 2
2351 (OUT) timeset_description = timeset description string
2354 Notes:
2355 -----
2356 * A string of NULLs is valid for timeset_description
2361 --------------------------------------------------------------------
2362 USERD_get_var_by_component
2364 Description:
2365 -----------
2366 Gets the values of a variable component. Both unstructured and structured
2367 parts use this routine.
2369 if Z_PER_NODE:
2370 Get the component value at each node for a given variable in the part.
2372 or if Z_PER_ELEM:
2373 Get the component value at each element of a specific part and type
2374 for a given variable.
2376 Specification:
2377 -------------
2378 int USERD_get_var_by_component(int which_variable,
2379 int which_part,
2380 int var_type,
2381 int which_type,
2382 int imag_data,
2383 int component,
2384 float *var_array)
2386 Returns:
2387 -------
2388 Z_OK if successful
2389 Z_ERR if not successful
2391 or: Z_UNDEF, in which case you need not load any values into var_array
2394 Arguments:
2395 ---------
2396 (IN) which_variable = The variable number
2398 (IN) which_part Since EnSight Version 7.4
2399 -------------------------
2400 = The part number
2402 (1-based index of part table, namely:
2404 1 ... Numparts_available.
2406 It is NOT the part_id that
2407 is loaded in USERD_get_gold_part_build_info)
2409 Prior to EnSight Version 7.4
2410 ----------------------------
2411 = The part id This is the part_id label loaded
2412 in USERD_get_gold_part_build_info.
2413 It is NOT the part table index.
2415 (IN) var_type = Z_SCALAR
2416 Z_VECTOR
2417 Z_TENSOR (symmetric tensor)
2418 Z_TENSOR9 (asymmetric tensor)
2420 (IN) which_type
2422 if Z_PER_NODE: Not used
2424 if Z_PER_ELEM: = The element type
2425 Z_POINT node point element
2426 Z_BAR02 2 node bar
2427 Z_BAR03 3 node bar
2428 Z_TRI03 3 node triangle
2429 Z_TRI06 6 node triangle
2430 Z_QUA04 4 node quad
2431 Z_QUA08 8 node quad
2432 Z_TET04 4 node tetrahedron
2433 Z_TET10 10 node tetrahedron
2434 Z_PYR05 5 node pyramid
2435 Z_PYR13 13 node pyramid
2436 Z_PEN06 6 node pentahedron
2437 Z_PEN15 15 node pentahedron
2438 Z_HEX08 8 node hexahedron
2439 Z_HEX20 20 node hexahedron
2441 Z_G_POINT ghost node point element
2442 Z_G_BAR02 2 node ghost bar
2443 Z_G_BAR03 3 node ghost bar
2444 Z_G_TRI03 3 node ghost triangle
2445 Z_G_TRI06 6 node ghost triangle
2446 Z_G_QUA04 4 node ghost quad
2447 Z_G_QUA08 8 node ghost quad
2448 Z_G_TET04 4 node ghost tetrahedron
2449 Z_G_TET10 10 node ghost tetrahedron
2450 Z_G_PYR05 5 node ghost pyramid
2451 Z_G_PYR13 13 node ghost pyramid
2452 Z_G_PEN06 6 node ghost pentahedron
2453 Z_G_PEN15 15 node ghost pentahedron
2454 Z_G_HEX08 8 node ghost hexahedron
2455 Z_G_HEX20 20 node ghost hexahedron
2457 (IN) imag_data = TRUE if imag component
2458 FALSE if real component
2460 (IN) component = The component: (0 if Z_SCALAR)
2461 (0 - 2 if Z_VECTOR)
2462 (0 - 5 if Z_TENSOR)
2463 (0 - 8 if Z_TENSOR9)
2465 * 6 Symmetric Indicies, 0:5 *
2466 * ---------------------------- *
2467 * | 11 12 13 | | 0 3 4 | *
2468 * | | | | *
2469 * T = | 22 23 | = | 1 5 | *
2470 * | | | | *
2471 * | 33 | | 2 | *
2474 * 9 General Indicies, 0:8 *
2475 * ---------------------------- *
2476 * | 11 12 13 | | 0 3 4 | *
2477 * | | | | *
2478 * T = | 21 22 23 | = | 6 1 5 | *
2479 * | | | | *
2480 * | 31 32 33 | | 7 8 2 | *
2482 (OUT) var_array
2484 -----------------------------------------------------------------------
2485 (IMPORTANT: this array is 1-based for both Z_PER_NODE and Z_PER_ELEM!!!)
2486 -----------------------------------------------------------------------
2488 if Z_PER_NODE: = 1D array containing variable component value
2489 for each node.
2491 (Array will have been allocated
2492 (number_of_nodes + 1) long)
2494 Info stored in this fashion:
2495 var_array[0] = not used
2496 var_array[1] = var component for node 1 of part
2497 var_array[2] = var_component for node 2 of part
2498 var_array[3] = var_component for node 3 of part
2499 etc.
2501 if Z_PER_ELEM: = 1D array containing variable component
2502 value for each element of a particular
2503 part and type.
2505 (Array will have been allocated
2506 (number_of_elements[which_part][which_type] + 1)
2507 long. See USERD_get_gold_part_build_info)
2509 Info stored in this fashion:
2510 var_array[1] = var component for elem 1 (of part and type)
2511 var_array[2] = var component for elem 2 (of part and type)
2512 var_array[3] = var component for elem 3 (of part and type)
2513 etc.
2515 Notes:
2516 -----
2517 * Not called unless Num_variables is > 0
2519 * The per_node or per_elem classification must be obtainable from the
2520 variable number (a var_classify array needs to be retained)
2522 * Will be based on Current_time_step
2524 * If the variable is not defined for this part, simply return with a
2525 value of Z_UNDEF. EnSight will treat the variable as undefined for
2526 this part.
2529 --------------------------------------------------------------------
2530 USERD_get_var_value_at_specific
2532 Description:
2533 -----------
2534 if Z_PER_NODE:
2535 Get the value of a particular variable at a particular node in a
2536 particular part at a particular time.
2538 or if Z_PER_ELEM:
2539 Get the value of a particular variable at a particular element of
2540 a particular type in a particular part at a particular time.
2543 Specification:
2544 -------------
2545 int USERD_get_var_value_at_specific(int which_var,
2546 int which_node_or_elem,
2547 int which_part,
2548 int which_elem_type,
2549 int time_step,
2550 float values[3],
2551 int imag_data)
2553 Returns:
2554 -------
2555 Z_OK if successful
2556 Z_ERR if not successful
2558 Arguments:
2559 ---------
2560 (IN) which_var = The variable number
2562 (IN) which_node_or_elem
2564 If Z_PER_NODE:
2565 = The node number. This is not the id, but is
2566 the index of the global node
2567 list (1 based), or the block's
2568 node list (1 based).
2570 Thus, coord_array[1]
2571 coord_array[2]
2572 coord_array[3]
2573 . |
2574 . |which_node_or_elem index
2575 . ----
2578 If Z_PER_ELEM:
2579 = The element number. This is not the id, but is
2580 the element number index
2581 of the number_of_element array
2582 (see USERD_get_gold_part_build_info),
2583 or the block's element list (1 based).
2585 Thus, for which_part:
2586 conn_array[which_elem_type][0]
2587 conn_array[which_elem_type][1]
2588 conn_array[which_elem_type][2]
2589 . |
2590 . which_node_or_elem index
2591 . ----
2594 (IN) which_part Since EnSight Version 7.4
2595 -------------------------
2596 = The part number
2598 (1-based index of part table, namely:
2600 1 ... Numparts_available.
2602 It is NOT the part_id that
2603 is loaded in USERD_get_gold_part_build_info)
2605 Prior to EnSight Version 7.4
2606 ----------------------------
2607 = The part id This is the part_id label loaded
2608 in USERD_get_gold_part_build_info.
2609 It is NOT the part table index.
2612 (IN) which_elem_type
2614 If Z_PER_NODE, or block part:
2615 = Not used
2617 If Z_PER_ELEM:
2618 = The element type. This is the element type index
2619 of the number_of_element array
2620 (see USERD_get_gold_part_build_info)
2622 (IN) time_step = The time step
2624 (IN) imag_data = TRUE if want imaginary value.
2625 FALSE if want real value.
2627 (OUT) values = scalar or vector component value(s)
2628 values[0] = scalar or vector[0]
2629 values[1] = vector[1]
2630 values[2] = vector[2]
2633 Notes:
2634 -----
2635 * This routine is used in node querys over time (or element querys over
2636 time for Z_PER_ELEM variables). If these operations are not critical
2637 to you, this can be a dummy routine.
2639 * The per_node or per_elem classification must be obtainable from the
2640 variable number (a var_classify array needs to be retained)
2642 * The time step given is for the proper variable timeset.
2645 --------------------------------------------------------------------
2646 USERD_set_filenames
2648 Description:
2649 -----------
2650 Receives the geometry and result filenames entered in the data
2651 dialog. The user written code will have to store and use these
2652 as needed. The user written code must manage its own files!!
2654 Specification:
2655 -------------
2656 int USERD_set_filenames(char filename_1[],
2657 char filename_2[],
2658 char the_path[],
2659 int swapbytes)
2661 Returns:
2662 -------
2663 Z_OK if successful
2664 Z_ERR if not successful
2666 Arguments:
2667 ---------
2668 (IN) filename_1 = the filename entered into the geometry
2669 field of the data dialog.
2671 (IN) filename_2 = the filename entered into the result
2672 field of the data dialog.
2673 (If the two_fields flag in USERD_get_name_of_reader
2674 is FALSE, this will be null string)
2676 (IN) the_path = the path info from the data dialog.
2677 Note: filename_1 and filename_2 have already
2678 had the path prepended to them. This
2679 is provided in case it is needed for
2680 filenames contained in one of the files
2682 (IN) swapbytes = TRUE if should swap bytes when reading data.
2683 = FALSE normally.
2685 Notes:
2686 -----
2687 * Since you must manage everything from the input that is entered in
2688 these data dialog fields, this is an important routine!
2690 * It may be that you will need to have an executive type file that contains
2691 info and other filenames within it, like EnSight6's case file.
2694 --------------------------------------------------------------------
2695 USERD_set_server_number
2697 Description:
2698 -----------
2699 Receives the server number of how many total servers.
2701 Specification:
2702 -------------
2703 int USERD_set_server_number(int cur_serv,
2704 int tot_servs)
2706 Returns:
2707 -------
2708 nothing
2710 Arguments:
2711 ---------
2712 (IN) cur_serv = the current server.
2714 (IN) tot_servs = the total number of servers.
2716 Notes:
2717 -----
2718 * Only useful if your user defined reader is being used with EnSight's
2719 Server-of-Server capability. And even then, it may or may not be
2720 something that you can take advantage of. If your data is already
2721 partitioned in some manner, such that you can access the proper
2722 portions using this information.
2724 For all non-SOS uses, this will simply be 1 of 1
2728 --------------------------------------------------------------------
2729 USERD_set_time_set_and_step
2731 Description:
2732 -----------
2733 Set the current time step in the desired timeset. All functions that
2734 need time, and that do not explicitly pass it in, will use the timeset
2735 and step set by this routine, if needed.
2737 Specification:
2738 -------------
2739 void USERD_set_time_set_and_step(int timeset_number,
2740 int time_step)
2742 Returns:
2743 -------
2744 nothing
2746 Arguments:
2747 ---------
2748 (IN) timeset_number = the timeset number (1 based).
2750 For example: If USERD_get_number_of_timesets
2751 returns 2, the valid timeset_number's
2752 would be 1 and 2.
2754 (IN) time_step = The current time step to set
2756 Notes:
2757 -----
2758 * Current_time_step and Current_timeset would be set here
2762 --------------------------------------------------------------------
2763 USERD_stop_part_building
2765 Description:
2766 -----------
2767 This routine called when the part building dialog is closed. It is
2768 provided in case you desire to release memory, etc. that was only needed
2769 during the part building process.
2771 Specification:
2772 -------------
2773 void USERD_stop_part_building( void )
2775 Returns:
2776 -------
2777 nothing
2779 Arguments:
2780 ---------
2781 none
2783 Notes:
2784 -----
2787 ---- end of doucment ----