VTK/Remove BTX ETX

The new wrappers introduced in VTK 5.8 do not use the BTX/ETX markers. These markers are unnecessary for the most part, because the new vtkParse understands much more of the C++ grammar, and the wrapper generators are able to decide for themselves which methods can or cannot be wrapped. Removing these markers will require modification to virtually every VTK header file, so it will be a disruptive change to anyone who maintains their own VTK source tree. As a result, the best time for this change would be the beginning of a new stage of VTK development, e.g. immediately after either the VTK 5.8 release or immediately after the VTK 5.10 release.

Replacement for BTX/ETX

There is a new preprocessor symbol, __WRAP__, which is defined by vtkParse. It can be used to mark blocks of code that are to be skipped by the parser. It should be used sparingly, any need for its use should be considered to be due to inadequacy in vtkParse.

#ifndef __WRAP__
  // code to be skipped by wrappers
#endif

To keep wrapping behavior consistent between vtkParse and Mummy, it might be useful to define the following:

#define __WRAP__ __GCCXML__

Use of BTX/ETX in third-party projects

The behavior of vtkParse with respect to BTX/ETX is different for external projects as compared to code within VTK itself. In external projects, BTX/ETX function exactly as they did before the new wrappers were introduced. This is for the sake of backwards compatibility.

Ideally, external projects should also remove all use of BTX/ETX, but unfortunately they cannot do this yet. The reason is that, in order to wrap methods that take arguments that are not simple known types like int, float, etcetera, it is necessary that vtkParse can do it "wtti" or "wrapper-time type identification" on those types. And for that, it needs to use the vtkKitHierarchy.txt files that were introduced in VTK 5.8. Here is an example:

void vtkSomeClass::SetVariantValue(MyIndexType idx, vtkVariant val);

The vtkCommonHierarchy.txt file contains an entry for vtkVariant that shows its pedigree, i.e. so that the wrappers know that it is a wrapped type but is not derived from vtkObjectBase. Likewise, one of the other hierarchy.txt files might have a typedef entry for MyIndexType to let the wrappers know that it is "unsigned long". The wrappers use the hierarchy.txt files to elucidate type information, so that they do not have to parse all the files included by the .h files they are wrapping.

Unfortunately, the vtkKitHierarchy.txt files are not yet visible to external projects. This restricts the range of types that the wrappers are able to handle in these projects. In order to overcome this deficit, the VTK cmake files will have to be modified so that the vtkKitHierarchy.txt files are exported and utilized in external projects. Doing this will require a substantial amount of work, but is a necessary step in order to completely eradicate BTX/ETX.