VTK/Wrappers

In addition to C++, VTK can be used through Tcl, Python, Java, and .NET (e.g. C#, Visual Basic). These are commonly referred to as the "wrapper languages" for VTK. Wrapping is the process by which the API of VTK (i.e. its class interfaces, as described by the VTK class header files) are made available in another language through the creation of "glue code".

Wrapping Process

Wrapping is a multi-stage process, involving the following steps:

1. Identify header files that contain wrappable interfaces
2. Generate build rules that will create glue code from header files
3. Parse the header files to generate a description of the interfaces
4. Generate glue code from these descriptions
5. Compile and link the glue code to create wrapper-language modules

Steps 1 and 2 are done by CMake. Steps 3 and 4 are done by the VTK wrapping tools (steps 3 and 4 are often done by a single program). Step 5 is done by a C++ compiler.

CMake Wrapping Functions

The CMake wrapping functions are contained in the VTK/CMake directory.

• vtkWrapping.cmake: This file defines the function vtk_add_wrapping(module_name module_srcs module_hdrs), which will generate the wrappers for module_name. Regardless of its name, the module_hdrs parameter should not contain all the headers in the module. It should only contain headers that do not declare classes, such as vtkSetGet.h or vtkType.h. All other headers should be included in module_srcs instead.

• vtkTclWrapping.cmake, vtkPythonWrapping.cmake, vtkJavaWrapping.cmake: These files contain language-specific versions of the vtk_add_wrapping() function. For example, vtk_add_python_wrapping(module_name module_srcs module_hdrs) generates a python module for the specified VTK module. It does so by using vtkWrapPython.cmake, which is described below.

• vtkWrapPython.cmake, vtkWrapTcl.cmake, vtkWrapJava.cmake: These files generate glue code for a module by running the wrapper tools on each of the wrappable header files in the module. For example, vtkWrapPython.cmake will generate a rule to call vtkWrapPython.exe on every .h file that is to be wrapped. The glue code that is generated by the executable is compiled and linked by vtkPythonWrapping.cmake.

• vtkWrapHierarchy.cmake: This file generates a Hierarchy.txt file for a module. The Hierarchy.txt file lists the class hierarchy for the module and for all its dependencies, as well as any typedefs or enum types that are defined in the header files. The wrapper tools use this Hierarchy.txt file to expand typedefs and to perform type introspection.

Wrapping Tools

The wrapping tools that come with VTK are:

• vtkWrapPython
• vtkWrapTcl
• vtkWrapJava/vtkParseJava
• vtkWrapJavaBeans (obsolete)
• vtkWrapHierarchy
• vtkHTML (obsoleted in favor of Doxygen)
• vtkPrint (obsolete)

Usage of command-line tools:

• Command Line Arguments

Wrapping Tool Source Code

The source code for the VTK wrapper tools is located in VTK/Wrapping/Tools.

• vtkParse.y (vtkParse.tab.c): A C++ parser built with "yacc". The file vtkParse.y contains the rules of the C++ grammar, or at least all rules that are needed to parse a C++ interface. It parses everything except for the code within function bodies, which it ignores. The file vtkParse.tab.c is generated from vtkParse.y with "yacc":

yacc -b vtkParse vtkParse.y

• vtkParse.l (lex.yy.c): A helper file for the parser, which is responsible for breaking a C++ header file into C++ tokens, and also for calling upon the preprocessor when macros and preprocessor directives are encountered in the code. The source file lex.yy.c is generated from vtkParse.l with the following command:

flex --nodefault -olex.yy.c vtkParse.l

• vtkParsePreprocess.c: A C++ preprocessor, which evaluates preprocessor directives and expands preprocessor macros.

• vtkParseMain.c: Contains code for reading options from the command line.

• vtkWrapPython.c: Generates glue code for the python wrappers.

Wrapper Improvement Projects

• Wrapper Changes for VTK 5.8
• Wrapper Changes for VTK 6.0
• Wrapping Special Types
• WrapHierarchy and Hierarchy Files
• BTX/ETX
• Python Wrapper Enhancement
• Wrapping C++11 Code