Extending tsPython

So you want to extend the trueSpace Python language with your favorite missing functionality? The following pages is 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 have 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 your extension with.

Here are the pertinent urls

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 the 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 efficiency 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 have 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 programming C++ 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

  1. Do

C:\Temp> dumpbin /exports tsxpythn.dll > tsxpythn.def

  2. Remove all lines in tsxpythn that is not part of the set of exported symbols.

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

  4. Add a line at the beginning saying EXPORTS.

  5. Do

C:\Temp> lib /def:tsxpythn.def

  6. Link your extension with the generated tsxpythn.lib (and tsxapi.lib from the tSX SDK if you intend to call any trueSpace API functions).

Lars Nilsson
Email: chamaeleon@quantumchamaeleon.com
Page last modified: 08/16/02

[Home]