Table of Contents
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
In addition to the above directories, each toolkit directory contains subdirectories "fortran", "cplusplus", and "csharp" that contain the bindings for FORTRAN, C++, and C#, respectively.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
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,
Publicly available external library support for compression. There are two options. The user may conditionally compile source to reference a user supplied installation of the external library or conditionally compile source to reference a modified version of the publicly available source which is delivered in the base/ext directory.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
Enable Intel's MKL BLAS functionality. These definitions must be used when compiling all objects in the base, vfs and vfx directories.VKI_LIBAPI_ZLIB ZLIB user installed external library VKI_EXTAPI_ZLIB ZLIB base/ext/zlib source
Enable multi-threading functionality which uses OpenMP. These definitions must be used when compiling all objects in the base, vfs and vfx directories.VKI_LIBAPI_BLASMKL_SEQUENTIAL Enable MKL sequential BLAS functionality VKI_LIBAPI_BLASMKL_THREAD Enable MKL threaded BLAS functionality
Enable sockets functionality. This definition must be used when compiling all objects in the base directory.VKI_LIBAPI_OPENMP Enable OpenMP Threading functionality
In general, most user input arguments to functions are checked for validity. In some cases where the error checking may degrade performance, a compile time option is available to conditionally compile the additional error checking code. This option also adds some memory integrity checking. The compile time definition related to error and memory checking is the following.VKI_LIBAPI_SOCKETS Enable sockets functionality
Once the DevTools source code is compiled, either the object files may be used directly or they may be installed in an object library archive so that the loader may selectively relocate only the objects which are required. DevTools is written in ANSI C. It is suggested to use the highest level of serial optimization options available on the C compiler.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
creating .o files in the base directory. To place the object files in an archive file issuegcc -c -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c
The object files may be deleted after the devtools.a archive is successfully created. At this point the devtools.a archive contains all base objects. Place the devtools.a archive immediately after the application code libraries in the load line. A devtools.a archive must be built for each computer platform using the methodology outlined above.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
creating .o files in the base directory that are suitable for building a dynamic link library. The library itself may be created withgcc -c -fPIC -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c
This will create the shared library devtools.so in the LINUX subdirectory. You can now link with this library, provided your environment variable LD_LIBRARY_PATH contains this subdirectory (separated by a colon).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
The object files may be deleted after the devtools.lib library is successfully created.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.. *.ccreating .obj files in the base directory. Then these .obj files must be linked into a dynamic link library using:
link /dll /implib:devtools.lib /out:devtools.dll /machine:i386 *.objWhen compiling user code referencing a Devtools function which has been placed in a dynamic link library, it is suggested to define the macro VKI_EXTERN to be __declspec(dllimport). Note that the devtools.dll must be placed in a directory that can be found by Microsoft Windows when the application is executed.
Table of Contents
In order to build the source code, first set the appropriate VKI_MACH value. Then change directory to the devtools/src/base directory and enter the following command for Microsoft Windows: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 buildor for all other systems enter
make buildThe base directory contains an ext sub directory. This directory contains ZLIB source. If you already use a pre-installed version of ZLIB you do not need to compile this source, Otherwise build it using the following command for Microsoft Windows:
nmake /f Makefile.win32 buildextor for all other systems enter
make buildextThen visit each licensed toolkit source directory and repeat the procedure. An ext subdirectory only exists in the base and vgl source directories. If the C++ interfaces are desired in addition to the standard C interfaces, then substitute buildCC for build in the make commands above. Once all files have been compiled, a final library resides in the directory lib/$(VKI_MACH) for the platform used.
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 exam1This will create exam1.exe.
Table of Contents
All arguments (other than specific object pointers) passed to any user callable DevTools function are typed using the above defined types. The Vtchar type is single byte (char) by default or wide character (wchar_t) if the symbol VKI_WIDECHAR is defined.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
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
The first two are needed to specify that the Windows architecture and Windows windowing systems are being used; the last indicates that OpenGL will be used for all graphics displays.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
#define SYS_VERSION 312This integer is guaranteed to be monotonically increasing for each new release.
Table of Contents
vis_Contour *contour; contour = new vis_Contour;
(C) vis_ContourSetTopology(contour,VIS_SHAPEQUAD,0,0) (C++) contour->SetTopology(VIS_SHAPEQUAD,0,0).
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.
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
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.
String mystring = Marshal.PtrToStringAnsi (myintptr);
int id = 0; vis.IdTranGetId (idtran,10,ref id);
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
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.
Table of Contents
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
Error Error handling Memory Memory system Print Standard output VQuad Quadruple precision
Heap Heap PQueue Priority queue
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
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
Concat Concatenated storage DataTable Interpolate data LinkList Linked list storage PropSet Extensible set of named properties of different types Random Random numbers
ADTree Geometric Searching, Alternating Digital Tree LineCon Line Connectivity TriCon Triangle Connectivity VertLoc Point Colocation Pred Geometric predicates
MachInfo Machine Information PTask Threading Timer Timers VSocket Interprocess communication
TextFun Text Functions TextTee Text Tee PlainText Plain Text Format HTMLText HTML Text Format LaTeXText LaTeX Text Format