
VTK for Fortran Documentation
Tom Bulatewicz
10 September 2003


Contents
  0. Introduction
  1. Naming
  2.void* arguments
  3.Skipped functions
  4. Open Issues


Requires:

VTK installed somewhere.
xmlgen installed somewhere.


-1. Build Commands

-1.1 Inside the VTK folder


note, you'll need to upgrade your java xalan if you get "not more dtd's error"


generate.pl - generates all the wrapper code for all the headers listed in the headers.txt file (has internal flags that determine what wrapper code gets generated).

generate_makefile.pl - generates a makefile that will build all the wrapper code for all the headers listed in the headers.txt file.

makefile.header - used by the generate_makefile script.

headers.all.txt - a list of all the VTK headers we're wrapping.

doc - documentation directory
	headers.txt - a list of the VTK headers we want to generate wrappers for.
	common.html - automatically generated documentation for the common.xsl sheet.
	fc_c.html - automatically generated documentation for the fc_c.xsl sheet.
	fc_f.html - automatically generated documentation for the fc_f.xsl sheet.
	ReadMe.txt - the readme file.
	xsltdoc.css, xsltdoc.xsl, xhtml-lat1.ent - auto documenting tools.
	header.h - a default header that is included by all the cxx generated code.
	mapping.dtd - the dtd for the xsl sheets.

xsl - xslt sheet folder
	fc_c.xsl - the cxx wrapper generation xsl sheet
	fc_f.xsl - the fortran wrapper generation xsl sheet
	fc_ftypes.xsl - the fortran types module generation xsl sheet
	common.xsl - some templates used by the other xsl sheets (not to be used directly)
	user.xml - the user preferences xml file


0. Introduction

The overall design of the wrapper code generation is based on 3 xsl transformation sheets:
fc_ftypes.xsl - generates the Fortran types
fc_f.xsl - generates the fortran wrapper code
fc_c.xsl - generates the cxx wrapper code
common.xsl - common templates used by other xsl files (not used directly)

 all methods that return values are moved up as an argument in the fortran wrappers.


1 Naming

1.1 Fortran function names

There are two types of function names in the Fortran wrapper code.  The first type is the visible function name that users call from their Fortran code.  

1.1.1 Visible function names

For non-constructors/destructors, the visible function name is the exact same name as the Cxx method name, plus a "_F" (to differentiate methods that are identical except for their return values....fortran can't "overload" functions based on the return type, just based on the arguments).  For constructors/destructors, the function name is generated as follows:
for constructors: class_alias + "_" + "NEW"
for destructors: class_alias + "_" + "DELETE"

Note that the class alias is used.  The class alias is a shortened version of a class name that is meant to be used in places where the users will see it.  Therefore, it should be a user-friendly name.  If a class has an alias entry in the user xml file, then it will be used in the constructor/destructor name; if not, the original class name is used.

1.1.2 Internal function names

For non-constructors/destructors, the internal function name is generated as follows:
 non-ctor/dtor: original_method_name + "_" + method_id + class_id < + "_F" >

The original_method_name is the exact same name as the Cxx method name.  The method_id is just what position the method is in in the class.  E.g. the first method listed in a class definition is 1, the one below it in the definition is 2, etc, etc...  The class_id is a unique 2-digit identifier that is assigned to each class.  This class id is specified for each class in the user xml file.  The "_F" is only appended to functions in which the original cxx class has a return value.

The method_id is appended to the name to avoid intra-class method name clashes since each method gets its own number within a class.  The class_id is appended to avoid inter-class method name clashes, since each class gets its own identifier.  I am not sure if the "_F" is needed, or if the method_id solves the problem.

for ctor/dtor: ????


1.2 Cxx Function Names

All Cxx function names are generated as follows:
for non-ctor/dtor: original_method_name + "_" + method_id + class_id < + "_F" > + "_C"

All of the parts of the function names are the same as for internal Fortran function names, with the addition of the "_C", which is appended to differentiate the Cxx wrapper functions from the Fortran wrapper functions.

for ctor/dtor: ????


1.3 Type Names

For every typedef, struct, and class that is used in the original Cxx code, there needs to be a Fortran type definition so that they can be used on the Fortran side (note they are deep, since the actual memory is allocated on the Cxx side and the Fortran type is simply an integer that holds the address of the object on the Cxx side).  Each Fortran type is defined within its own module and are named as follows:

module typename_type
  type typename
    integer x
  end type typename
end module typename_type

where typename is the name of the Cxx typedef/struct/class.


1.4 Fortran module names

The Fortran module names are generated as follows:
module name: headerfilename + "Mod"

The headerfilename is the name of the header file that is being wrapped, without the .h extension.  


2 void* arguments

Cxx methods that have void* arguments are problematic because there is no equivalent generic type in Fortran.  For this reason, multiple Fortran wrappers need to be generated for the same method, that differ by their arguments.  All the Fortran wrappers will actually call the same Cxx wrapper, but each Fortran wrapper needs its own explicit type.  For example, if you have a Cxx method that takes two void* arguments, and you want all void* arguments to be able to be called with integers and reals, then there needs to be 4 Fortran wrappers for that method (I.e. foo( integer integer ), foo( real real ), foo( int real ), foo( real int ).


3 Skipped Functions

Some Cxx functions can't be wrapped.  There is a template in the common.xsl file that determines if a wrapper should be generated for a given Cxx function.  Some reasons for excepting a function include:
functions that have the same name as Fortran intrinsic functions
functions that have iostream arguments
methods that are protected or private


4 Open Issues

As of 9/11/03, the following are open issues in the wrapper code generation:
the xsl does not properly support nested classes
a problem with "conv" kind methods in xmlgen
problem with name clashes with intrinsics (workaround)
problem with duplicate wrappers generated for inherited methods

Suggested solutions:
 blah...
