Table of Contents

1. Introduction

• Base - Foundation objects. Error handling, object collections, etc.
• VglTools - Graphics library. Hierarchical display lists, graphics device interface, software rendering, industry standard 2D image and 3D object file support.
• VisTools - Visualization algorithms. Contouring, isosurface extraction, streamline generation, curve and surface tessellation, graphing, etc.
• VisTools/Mesh - Mesh generation. Mapped meshing, extrusion, 2D planar triangular meshing, 3D curve and surface meshing and 3D volume tetrahedral meshing.
• VdmTools - Data management for engineering and scientific applications. Interface to most commercial finite element data file formats.
• VfeTools - Finite element formulations and material models library. Solid, shell, beam element formulations and supporting material models.
• VfsTools - Finite element system solution library. Linear equation solvers, eigenvalue solvers, solution procedures.
• VfxTools - Application level modules

1.1 Application Development Environment

The application programming interface (API) consists of a header file and a series of entry points defining the functional interface (also termed "methods" in object-oriented technology) for each module. The private data for each module is defined in a C language structure, struct, which is a defined type, typedef. In order to avoid naming conflicts, all function names and defined types of the modules delivered with DevTools begin with vut_, vml_, vsy_, vis_, vgl_, vfe_, vfs_, vdm_ or vfx_. The four character prefix is followed by the module and function name in initial capital letters. For example the function to draw contours on a curvilinear array of computational cells in VisTools is vis_ContourCurv. All arguments to module functions are either simple variables, arrays or pointers to structures containing the private data of an object. Each module contains functions to begin and end an instance of the module. For example to create a Contour object use vis_ContourBegin. This function allocates an instance (an object) of the module and returns a pointer (object handle) to a struct containing the private data of the object. If object creation fails, a NULL pointer is returned. The end function destroys the object and frees its memory resources. For example, use vis_ContourEnd to destroy a Contour object.

Table of Contents

1.2 Directory Structure

devtools                      DevTools MAKEDEFS for built-in make system
devtools/lib                  Empty directory for DevTools archives
devtools/src/base             DevTools base source and header files
devtools/src/base/ext         DevTools ZLIB source
devtools/src/base/exam        DevTools base examples
devtools/src/vgl              VglTools source and header files
devtools/src/vgl/exam         VglTools examples
devtools/src/vgl/ext          VglTools PNG, TIFF, JPEG source
devtools/src/vgl/fonts        VglTools FreeType font files
devtools/src/vgl/test         VglTools feature and performance tests
devtools/src/vis              VisTools source and header files
devtools/src/vis/exam         VisTools examples
devtools/src/vdm              VdmTools source and header files
devtools/src/vdm/exam         VdmTools examples
devtools/src/vfe              VfeTools source and header files
devtools/src/vfe/exam         VfeTools examples
devtools/src/vfs              VfsTools source and header files
devtools/src/vfs/exam         VfsTools examples
devtools/src/vfx              VfxTools source and header files
devtools/src/vfx/exam         VfxTools examples

Each DevTools module exists as a source file (.c or .cxx) and associated header file (.h) in the source directory. For example the Contour module source and header files are contour.c and contour.h respectively and reside in the VisTools src/vis directory. There are additional source and header files which contain internal utility procedures and DevTools-wide macro definitions.

The base directory contains all the foundation module source and header files for all DevTools components. Examples of foundation modules are Error, List and Stack.

The lib directory contains a set of subdirectories which are empty at initial installation. They may be used to place object or archive files resulting from compiling DevTools components on a specific platform.

Table of Contents

1.3 Compiling and Linking DevTools

Each DevTools library has a different set of compilation options (C preprocessor directives) which are required for proper compilation on a particular platform, operating system, window system, etc. These options are documented in the "Compiling and Linking" section of each library. The base library must be compiled for all DevTools installations, along with each of the DevTools libraries delivered.

There are a variety of C preprocessor definitions which are used to conditionally compile source code. The following definitions are common to all DevTools libraries. The primary category is machine architecture which is related to the overall computing platform. The machine architecture implies an operating system such as LINUX, Microsoft Windows and platform dependent varitions of UNIX. Possible architectures are the following,

VKI_ARCH_HP       Hewlett Packard HPUX systems
VKI_ARCH_IBM      IBM AIX systems
VKI_ARCH_LINUX    LINUX operating system
VKI_ARCH_MAC      Apple MAC OS X
VKI_ARCH_SGI      Silicon Graphics IRIX systems
VKI_ARCH_SUN      SUN Solaris systems
VKI_ARCH_WIN32    MicroSoft Windows

VKI_LIBAPI_ZLIB     ZLIB user installed external library
VKI_EXTAPI_ZLIB     ZLIB base/ext/zlib source

VKI_LIBAPI_BLASMKL_SEQUENTIAL  Enable MKL sequential BLAS functionality
VKI_LIBAPI_BLASMKL_THREAD      Enable MKL threaded BLAS functionality

VKI_LIBAPI_OPENMP    Enable OpenMP Threading functionality

VKI_LIBAPI_SOCKETS    Enable sockets functionality

VKI_CHECK_ERRS    Include additional error checking

For example, on LINUX systems, create a directory LINUX under lib to hold the final devtools.a archive file. Then from the devtools/src/base directory compile using

gcc -c -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c

ar rs ../../lib/LINUX/devtools.a *.o

To build a dynamic link library on LINUX systems, use the same LINUX directory under lib to hold the final devtools.so library file. Then from the devtools/src/base directory compile using

gcc -c -fPIC -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c

gcc -shared -Wl,-soname,devtools.so -o ../../lib/devtools.so *.o -lc

On Microsoft Windows systems, compile from within a nmake file using:

     !include <ntwin32.mak>
     cl.exe $(cflags) $(cvars) /O2 -DVKI_ARCH_WIN32 -DVKI_CHECK_ERRS -I.. *.c

creating .obj files in the base directory. To place the object files in a library file issue

lib /out:../../lib/INTEL/devtools.lib *.obj

To build a dynamic link library (.dll) in Microsoft Windows rather than a static library, define the macro VKI_EXTERN to be __declspec(dllexport) when compiling DevTools source code as follows:

     !include <ntwin32.mak>
     cl.exe $(cflags) $(cvars) /O2 -DVKI_ARCH_WIN32 -DVKI_CHECK_ERRS \
            -DVKI_EXTERN=__declspec(dllexport) -I.. *.c

     link /dll /implib:devtools.lib /out:devtools.dll /machine:i386 *.obj

Table of Contents

1.4 The Built-in Make System

LINUX    LINUX 32 bit
LINUX64  LINUX 64 bit
MAC      Apple MAC OS X
WIN32    Microsoft Windows 32 bit
WIN64    Microsoft Windows 64 bit

     nmake /f Makefile.win32 build

     make build

     nmake /f Makefile.win32 buildext

     make buildext

In order to build any one of the supplied examples after the object library or archive has been built using the procedure above, change directory to the exam directory in any of the toolkit source directories. Then issue the appropriate make command to build one of the examples. For example to build Example 1 as a console application in the base library on Microsoft Windows, change directory to devtools/src/base/exam and enter

     nmake /f Makefile.win32 exam1

Table of Contents

1.5 Include Files and Data Types

Vchar    character, a single byte
Vtchar   character, single byte or wchar_t
Vuchar   unsigned character
Vwchar   wide character, type wchar_t
Vshort   short integer, 16 bits
Vushort  unsigned short integer
Vint     integer, 32 bits
Vuint    unsigned integer
Vlong    long integer, 64 bits
Vulong   unsigned long integer
Vfloat   single precision floating point, the same size as Vint
Vdouble  double precision floating point, 64 bits
Vobject  void*
Vword    maximum sizeof Vint, Vfloat and Vobject
Vquad    quadruple precision floating point, 128 bits

Pointers to specific object types are typedefed using a four letter prefix, such as vis_ in the VisTools library, and the name of the module from which the object was instanced. For example, Contour objects are typed as vis_Contour. These module type definitions appear in the header file for each module. The base.h, vis.h, vismesh.h, vgl.h, vfe.h, vfs.h, vfx.h and vdm.h files include all the required module header files. It is recommended that one use the #include pre-processor directive as follows:

#include "base/base.h"
#include "vgl/vgl.h"
#include "vis/vis.h"
#include "vis/vismesh.h"
#include "vdm/vdm.h"
#include "vfe/vfe.h"
#include "vfs/vfs.h"
#include "vfx/vfx.h"

An include file, userdefs.h, is installed in the devtools/src/base directory specifically for user defined C preprocessor commands and is meant to be edited and customized by the user. This include file is guaranteed to be included by any DevTools include file. One particular use of userdefs.h is customization with respect to compiling features in VfxTools which are dependent upon underlying toolkits. The following #define's should be added indicating toolkits which are not licensed.

#define VKI_NOVGLTOOLS
#define VKI_NOVISTOOLS
#define VKI_NOVISTOOLSMESH
#define VKI_NOVDMTOOLS

Table of Contents

1.6 Building an Application Using Visual Studio

File -> Open -> Project/Solution

and pointing the file selector to the above file. You can also use Windows Explorer to locate the file src\base\exam\windows\exam.vcproj and open Visual Studio by double clicking on it.

The chosen example is src\base\exam\exam1.c. Other examples can be built by following the same procedures as in this example. The example has been configured in both "Debug" and "Release" modes, and supports both Win32 and x64 platforms.

The example properties windows can be displayed by right-clicking on the example "exam" then choosing "Properties" (the last entry in Visual Studio 9.0). The following changes from the default empty project were made:

Configuration Properties -> C/C++ -> General

Under "Additional Include Directories" the path "..\..\.." was added to reflect the relative path for the "src" directory.

Configuration Properties -> C/C++ -> Preprocessor

Under "Preprocessor Definitions" we added

VKI_ARCH_WIN32
VKI_WIND_WIN32
VKI_3DAPI_OPENGL

Configuration Properties -> Linker -> General

Under "Additional Library Directories" the path ..\..\..\lib\WIN32 was added to the Win32 platform, and the path ..\..\..\lib\WIN64 was added to the x64 platform. It is expected that the 32-bit version of devtools.lib will be placed in lib\WIN32 while the 64-bit version of devtools.lib will be placed in lib\WIN64. Instructions for building devtools.lib are available elsewhere in this documentation.

Configuration Properties -> Linker -> Input

Under "Additional Dependencies" the libraries "devtools.lib opengl32.lib vfw32.lib" were added. The last two libraries - opengl32.lib and vfw32.lib - are standard Windows libraries.

Selecting an active configuration and platform is done by clicking on the "Configuration Manager..." button in the properties window and choosing a "Configuration" and a "Platform" for the "exam" Project.

Use the Visual Studio sequence "Debug -> Start Without Debugging" to build and run this console application. You can also debug the application by choosing the Visual Studio sequence "Debug -> Start Debugging".

Table of Contents

1.7 Versioning

#define SYS_VERSION 312

Table of Contents

1.8 C++ Language Bindings

• All DevTools C language modules map into C++ classes. The "Begin" and "End" functions in a module become the constructor and destructor methods for the corresponding C++ classes. These functions correspond to the new and delete operators in C++. All other module functions map into a corresponding member function of the class. C++ class names are the same as the C language module names.
• The class methods are derived from the module functions by removing the letters vis_ and the module name. For example, vis_ContourSetObject now becomes contour->SetObject assuming that the contour object had been created as follows:

       vis_Contour *contour;
       contour = new vis_Contour;

• The argument lists are identical except for the elimination of the first argument (the object argument). For example:

  (C)   vis_ContourSetTopology(contour,VIS_SHAPEQUAD,0,0)
  (C++) contour->SetTopology(VIS_SHAPEQUAD,0,0).

• The C++ class definitions and functions are contained in the cplusplus subdirectory in the source directory for each library. For example, the C++ wrapper files for the VisTools library reside in src/vis/cplusplus. The C++ wrapper files need to be compiled only if C++ bindings are required. The header files to be used with the C++ classes are the standard C language header files.

1.9 FORTRAN Language Bindings

DevTools supports a FORTRAN language binding. The FORTRAN language binding is a derivative of the C language binding and maintains the same object oriented technology as the C language binding. Functionality is in all cases identical for all language bindings. The following rules determine the form of the FORTRAN language binding from the C language binding.

• There is a one to one correspondence between C and FORTRAN entry points. The FORTRAN entry point may be derived from any C entry point by adding a lower case letter f to the 3 letter prefix. For example the entry point to set an attribute object in a Contour object vis_ContourSetObject becomes visf_ContourSetObject. Note that FORTRAN is case insensitive. The FORTRAN language binding does not conform to the FORTRAN 77 standard in the sense that entry point names exceed 6 characters.
• All functions in the C binding become subroutine calls in the FORTRAN binding. The argument lists are identical except for those functions in the C binding which have function return values. There are two cases. 1) The object creation functions (eg. vis_ContourBegin) return an object. The corresponding FORTRAN subroutine returns the object in an argument list (eg. visf_ContourBegin(contour)). Use a double precision variable in FORTRAN to hold the object (eg. real*8 contour). 2) The object error flag return functions (eg. vis_ContourError) return an integer error flag. The corresponding FORTRAN subroutine returns the error flag at the end of the argument list (eg. visf_ContourError(contour,errorflag)).
• All defined constants in C become identically named integer parameters in FORTRAN. The FORTRAN entry points are contained in the fortran subdirectory in the source directory for each library. For example, the FORTRAN wrapper files for the VisTools library reside in src/vis/fortran. The FORTRAN wrapper files need to be compiled only if FORTRAN bindings are required. All standard C language header (.h) files have a corresponding include (.inc) file for FORTRAN.
• Use the following data type translations.

  Vchar      character
  Vtchar     character
  Vuchar     character
  Vshort     integer*2
  Vushort    integer*2
  Vint       integer
  Vuint      integer
  Vfloat     real
  Vdouble    real*8
  Vobject    real*8
  Vword      real*8
  

1.10 C# Language Bindings

DevTools supports a C# language binding. The C# language binding is a derivative of the C language binding and maintains the same object oriented technology as the C language binding. Functionality is in all cases identical for all language bindings. The following rules determine the form of the C# language binding from the C language binding.

• There is a one to one correspondence between C and C# entry points. The C# entry point may be derived from any C entry point by replacing the first _ (underbar) in a function name by a . (dot). For example the entry point to set an attribute object in a Contour object vis_ContourSetObject becomes vis.ContourSetObject.
• All strings passed to functions which are defined in C as NULL-terminated arrays of type char become StringBuilder classes.
• All strings which are returned by address in C become type IntPtr. The C# String may be retrieved from the IntPtr using

       String mystring = Marshal.PtrToStringAnsi (myintptr);

• Multi-dimensional arrays in C become single-dimensional arrays in C#. For example, the C declaration int a[10][3]; becomes int [] a = new int[30]; in C#.
• All objects become type IntPtr. This means that all Begin methods return IntPtr variables.
• All function arguments that only return a single variable are passed in C# by reference. Note that all references must be first initialized. For example,

       int id = 0;
       vis.IdTranGetId (idtran,10,ref id);

• Function arguments that may return one or more values must be declared as arrays, even if only one parameter is being returned.
• All constant parameters for all modules in each toolkit are contained in their respective classes. For example, TRANSMAP_UP, defined in the TransMap module, is referred to as vis.TRANSMAP_UP in a C# program. Likewise, all parameters defined in the base directory can be accessed using the vsy class name. For example, one would use vsy.SYS_ON, vsy.SYS_RES_D, etc.
• The C# class definitions and functions are contained in the csharp subdirectory in the source directory for each library. C# wrappers consist of a single class for each directory: vsy, for the base directory; vis, for the vis directory; vgl, for the vgl directory; vdm, for the vdm directory; vfe, for the vfe directory; vfs, for the vfs directory; and vfx, for the vfx directory.

     cd base
     nmake /f Makefile.win32 buildcs
     cd ../vdm
     nmake /f Makefile.win32 buildcs
     cd ../vis
     nmake /f Makefile.win32 buildcs
     cd ../vgl
     nmake /f Makefile.win32 buildcs
     cd ../vfe
     nmake /f Makefile.win32 buildcs
     cd ../vfs
     nmake /f Makefile.win32 buildcs
     cd ../vfx
     nmake /f Makefile.win32 buildcs
     cd ../..
     nmake -f Makefile.win32 buildcs

The last step in the sequence above creates a devtools.dll and devtoolscs.dll. While the path to devtools.dll may be added to the Windows PATH environment variable, devtoolscs.dll must be registered in the GAC. Alternatively, it may be copied to the location where the application that uses it resides. The latter is the approach utilized in the examples provided.

To build and run the intro1 example in vfe/exam use

     cd vfe/exam
     nmake /f Makefile.win32 intro1cs
     intro1cs.exe

Table of Contents

1.11 Parallelization and Thread Safety

Single instances of objects containing global data such as finite element model and results information may be reliably shared and accessed by multiple threads through a set of read only functions. These functions will have const declarations of the object in their prototypes. There are additional functions which can be used by multiple threads with a single object which are not declared const. These functions are documented with (thread safe) in the function summary. These functions can not formally be declared as const since the object internal error flag may be set if a user input error is detected.

Certain DevTools functions are internally parallelized. There are two types of internally parallelized functions.

• Implicit parallelization using OpenMP. These functions use OpenMP internally and the number of threads to be used is set by the environment variable OMP_NUM_THREADS or alternatively the environment variable VKI_NUM_THREADS. The variable VKI_NUM_THREADS, if defined, takes precedent over the variable OMP_NUM_THREADS. These functions are documented with (parallel) in the function summary and also listed in a Parallel Functions section for each object. This feature requires compilation with VKI_LIBAPI_OPENMP. If these environment variables are not defined or define a number of threads less than or equal to 1, then serial execution is indicated. The defined number of threads is capped by an internally defined DevTools maximum.

• Explicit parallelization set using an object function call such as vfs_DofTabSetNumThreads. All functions which are internally parallelized in this way will be individually documented as such. The default number of threads is 1. A number of threads specified less than 1 will result in an error being generated. A number of threads equal to 1 will result in serial execution. The specified number of threads is capped by an internally defined DevTools maximum.

Table of Contents

1.12 Floating Point Precision

• SYS_DOUBLE, 64 bit floating point type Vdouble

• SYS_FLOAT, 32 bit floating point type Vfloat

• SYS_HALF, 16 bit floating point type Vshort

The modules which support varying precision levels have facilities for setting and accessing data in float and double precision. These access routines will ensure that the data which is set and returned is properly converted to the internal precision representation.

Table of Contents

1.13 Base Library

• Error Handling, Memory System

  Error       Error handling
  Memory      Memory system
  Print       Standard output
  VQuad       Quadruple precision
  

• Priority queues

  Heap        Heap
  PQueue      Priority queue
  

• Object Collections

  Dictionary  Objects stored by character string key
  HashTable   Objects stored by arbitrary integer key
  List        Objects stored by sequential integer key
  Stack       Objects stored on a conventional stack
  

• Numeric Type Collections

  BitVec      Extensible vector of bits
  DblVec      Extensible vector of doubles
  FltVec      Extensible vector of floats
  IntDict     Dictionary of ints
  IntHash     Hashtable of ints
  IntQue      Queue of ints
  IntVec      Extensible vector of ints
  

• Utilities

  Concat      Concatenated storage
  DataTable   Interpolate data
  LinkList    Linked list storage
  PropSet     Extensible set of named properties of different types
  Random      Random numbers
  

• Geometry Tools

  ADTree      Geometric Searching, Alternating Digital Tree
  LineCon     Line Connectivity
  TriCon      Triangle Connectivity
  VertLoc     Point Colocation
  Pred        Geometric predicates
  

• System

  MachInfo    Machine Information
  PTask       Threading
  Timer       Timers
  VSocket     Interprocess communication
  

• Text Processing

  TextFun     Text Functions
  TextTee     Text Tee
  PlainText   Plain Text Format
  HTMLText    HTML Text Format
  LaTeXText   LaTeX Text Format