Programming Overview

This section provides general information about the HOOPS SAM SDKs distribution and valuable information on various programming topics.

HOOPS Access Modules

Each library contains a set of object oriented modules which implement the functionality of a particular library. Modules are object-based in that they support the encapsulation of a set of functions and data within an object, so that the data is only accessible though a well defined interface. A module (also termed a “class” in object-oriented technology) also supports the instantiation of multiple objects, each with its own private data. An object may be destroyed at any time, freeing its private data and local memory resources.

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 HOOPS SAM begin with vut_, vml_, vsy_, vis_, vgl_, vfe_, vfs_, vdm_, vfx_`or `msh_. 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.

Include Files and Data Types

The first step in writing a HOOPS SAM application is to include the proper header files. All HOOPS SAM applications must include the base.h header file located in the base directory. This file includes typedefs for all basic data types and defined constants. The basic data types are listed below.

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

All arguments (other than specific object pointers) passed to any user callable HOOPS SAM 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.

Pointers to specific object types are typedef ‘ed 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 src/sam/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 HOOPS SAM 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

Floating Point Precision

A number of HOOPS SAM modules support various levels of floating point precision. The precision levels are the following:

  • 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 reduced precision type, SYS_HALF, is implemented using the 16 bit IEEE floating point standard. This standard represents approximately 3.3 decimal digits of precision. The minimum and maximum representable values are 6.10e-5 and 65504.

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.

Language Bindings

C++

HOOPS SAM supports a C++ language binding. The C++ language binding is a derivative of the C language binding. The object oriented technology of the C language binding maps naturally into C++ classes. The following rules determine the form of the C++ language binding from the C language binding.

  • All HOOPS SAM 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/sam/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.

C#

HOOPS SAM 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. The initial memory allocation of these StringBuilder variables must be large enough to contain the returned value. The vsy.SYS_MAXPATHCHAR macro can be used to initialize them when retrieving paths, while the vsy.SYS_MAXNAME macro can be used in all other cases.

  • 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.

The built-in HOOPS SAM CMake system may be used to build the C# library and examples. The C# library can be built by setting the CMake boolean variable CEE_SAM_INTERFACE_CSHARP to ON.

FORTRAN (deprecated)

HOOPS SAM 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/sam/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

Major Version Migration

Migration scripts are provided to ease code modifications following a major HOOPS SAM version update. The provided scripts are Python scripts and can be found in the migration_scripts directory of the distribution archive. Each migration script is linked to only 1 increment of the major version numbering. These scripts are designed to update all text files in the current directory and its subdirectories. While these scripts tackle most of the changes, some remaining issues (such as deprecated functions or defines) will need to be manually fixed.

Currently, the following scripts are provided:

  • 2.0 update, can be found in the 2.0 directory of the migration_scripts directory. This script updates includes following the reorganization of the vdm modules, updates includes due to the migration from src to src/sam and src/legacy, updates includes and module names of the renamed meshing modules, and update the prorender module includes and name.