Quantum Chamaeleon

Extending tsPython

So you want to extend the trueSpace Python language with your favorite missing functionality? The following pages are my attempt to, as clearly as possible, explain how this can be done. There are a few prerequisites that need to be satisfied before proceeding. Although possible, Microsoft Visual C++ may NOT be the best environment for developing a tsPython extension. The reason is quite simple; Microsoft has, in their infinite wisdom, decided not to ship a program that can generate an import library for a DLL. On the other hand, Symantec C++ (now defunct, see further down the page) and Borland C++ Builder does ship with such a utility, called implib.exe. It is possible that this is included with Borland's free offering, but I haven't investigated that further. The other requirement is the header files for the Python language corresponding to version 1.5.2.

News: With a little bit of work it is possible to use Visual C++. See the end of this page for instructions on how to generate the required tsxpythn.lib for linking with your extension.

Here are the pertinent urls:

Digital Mars C++
DMC++ is the evolution of Symantec C++. The original developer of this compiler has managed to acquire the distribution rights for what was once known as Symantec C++ and is now making it freely available as a download, as well as very cheap on CD with the entire development environment (the free download is more or less equivalent to the Borland C++ Builder download, having compilers and linkers, etc, but no GUI). I'm recommending this one because I used Symantec C++ for quite some time and was very disappointed when they stopped supporting it in favor of Java.
Borland C++ Builder
I have no particular experience with Borland C++ Builder, but I am pretty sure that the free download will be sufficient if it does include implib.exe in the distribution.
Python 1.5.2
In order to ensure compatibility with tsPython, I recommend using this version as it most closely matches what Caligari uses (1.5.1). It is possible that there are some differences that could cause problems, but I haven't run into any yet.

Both the DMC++ and BC++ downloads consist of command line tools only. DMC++ is available with an IDE for $25.

Once the above requirements have been satisfied you will be ready to work on your very own extension. If you intend to call trueSpace API functions you will also require the tSX SDK from Caligari.

STEP 1

Create the required libraries to be linked in with your extension. This is a required step (one-time, if you save the result for reuse) as the library included in the tSX SDK is necessary if your extension is calling any of the tSX API functions. Copy the tsxapi.dll and tspythn.dll files from your trueSpace directory to C:\Temp (or some other location). The following two commands will, for the DMC++ version of implib.exe, create the two required libraries.
C:\Temp> implib /s tsxapi.lib tsxapi.dll
C:\Temp> implib /s tspythn.lib tspythn.dll
Copy tsxapi.lib and tspythn.lib either to the location where you intend to build your project, or to a location where you will make the header files for the tSX API and Python 1.5.2 available. It doesn't matter where, as long as you include them appropriately for the compiler you're using.

STEP 2

Create a project for your extension. This project should be for building a DLL.

STEP 3

Initialization code for a Python function named fib, and a constant name MeaningOfLife, both contained in a module Example. ???

PyMethodDef exampleMethods[] =
{
  {"fib", exampleFibonacci, METH_VARARGS},
  {NULL, NULL}
};

__declspec(dllexport) void initExample()
{
  PyObject *module, *dictionary;

  module = Py_InitModule("Example", ::exampleMethods);
  dictionary = PyModule_GetDict(module);

  PyObject *meaningOfLife = PyInt_FromLong(42);
  PyDict_SetItemString(dictionary, "MeaningOfLife", meaningOfLife);
}

STEP 4

Implement your functionality. (This is not an example of the most efficient or best possible algorithm for computing Fibonacci numbers. ;)
int fibonacciImpl(int n)
{
  if (n < 2)
    return 1;
  else
    return fibonacciImpl(n - 1) + fibonacciImpl(n - 2);
}

PyObject *exampleFibonacci(PyObject *self, PyObject, *args)
{
  int n, result = 0;

  PyArg_ParseTuple(args, "i", &n);

  result = fibonacciImpl(n);

  return Py_BuildValue("i", result);
}

STEP 5

Copy the DLL to your main trueSpace directory, or perhaps better, a directory called Lib in the main trueSpace directory.

STEP 6

Use the new extension you've created in trueSpace:
import Example
print Example.fib(10)
print Example.MeaningOfLife

STEP 7

Think of a better thing to do with Python in trueSpace than computing Fibonacci numbers... Calling the tSX API functions are no different when creating a Python extension, compared to writing a regular tSX.
tsxSceneAddObject((tsxGNODE) *myNewObject, e_tsxFALSE);
The above would, in the extension, add a trueSpace object that has been created by some means (predefined object like a cube, NURBS, or programmatically created polyhedron, etc).

You should also include error checking in your code to catch possible conversion problems from Python objects to integers, etc. This subject should be well enough covered in the Python documentation for creating extensions (the original Python documentation, not the trueSpace Python documentation which only covers the particulars of the functions implemented in trueSpace).

If you have any questions feel free to send me an email. I know the above is not as complete as it should be, and assumes a certain amount of knowledge of C++ programming and setting up projects for compilation.

I've finally come up with very simple example distribution using only the DMC++ command line tools: Example.zip

It will obviously require tinkering with paths in the makefile and the link file (location of Python and tsx header files). It also assumes the implib'ed libraries are put in the example directory (or one can add directives in the link file to specify where they are stored).

VC++ Library Generation

Do:

C:\Temp> dumpbin /exports tsxpythn.dll > tsxpythn.def
Remove all lines in tsxpythn that is not part of the set of exported symbols.

Change all remaining lines to only contain the name of the exported symbol.

Add a line at the beginning saying EXPORTS.
Do:

C:\Temp> lib /def:tsxpythn.def
Link your extension with the generated tsxpythn.lib (and tsxapi.lib from the tSX SDK if you intend to call any trueSpace API functions).