[Bf-python] Basic dev guide

[Willian Padovani Germano]

Hi,

This is meant as an outline for new developers.  Hopefully with replies
it will become useful for Michel's guide.

1 - Reference material:

There are two important texts for us in the documentation that comes
with Python ( docs also available online at www.python.org ):

- Extending and Embedding (tutorial for C/C++ programmers)

and specially

- Python/C API.

You can read the first one to get a feel for how things are done
(reference counting is probably the most important part), but the second
doc is a must.  Whenever I start coding, I open it at its index, letter
P, where all commands are, for fast reference.

Specially useful commands are Py_BuildValue and the family of parsing
functions, PyArg_Parse... Py_BuildValue is usually the best way to make
Python Objects (the 'variables' that the Python Interpreter understands)
out of C ones.  The PyArg_Parse... functions do the opposite, they parse
Python Objects to C variables.

So, understand PyArg_Parse... functions, Py_BuildValue and reference
counting.  The first doc has a good discussion about them.

- C knowledge is also necessary, of course, use your favorite reference.

- The Blender 2.25 API documentation ( www.blender.org ) is, along with
the source, our basic API ref.

2 - Directories

The previous Blender Python API's are spread in blender/intern/python
and the C part of the current one, bpython, is at
blender/source/blender/bpython/, specially in intern/.  The current
solution is a Python wrapper on top of this bpython one, at
blender/intern/python/modules/Blender/

Note: since it's in Python, they needed the freeze Python utility, a
process/program that creates stand-alone executables out of python
source files -- that is, it packs together an interpreter, the needed
modules and the source of a python program so that users of this program
don't need to have the python interpreter already installed in their
machines to run the program -- Blender, in this case.

The new implementation is pure C, so we won't need the "freeze thing" as
it's called.  From what I read at the mailing list, no one will miss it
...

It is in blender/source/blender/python , more specifically inside
api2_2x/

Another important dir for starters is blender/source/blender/makesdna,
where the header with object structs lie.

3 - Experimental Python

The new implementation, currently referred as experimental python -
exppython - was started by Michel Selten.  He chose to solve the mess in
Blender Python by starting over from scratch, in C, but keeping API
compatibility with the current 2.25 API used by Blender.

BPython was full of "macro magic", lot's of complicate #define's, etc.,
since a lot of the embedding work is quite repetitive.  But that also
makes it much harder for newbies to jump in and learn, so the new files
in exppython avoid that.

This means: Blender, Object, Camera, Lamp, Image, Text, Window modules
(the files have the same names, ending obviously with .c and .h)

To speed things up, some independent parts of bpython are being
integrated directly into exppython.  That already happened with Draw and
BGL, both taken from opy_draw.c in the bpython/intern dir.  The same is
happening with NMesh (Mesh is written in Python and imports NMesh to
extend / change its functionality).

For a good example of dexterity with macros (cheers to the NaN
programmer(s)!), look at BGL.[ch], the OpenGL API wrapper.  The defines
are in the header.

Besides keeping compatibility with the 2.25 API, there are already some
additions to exppython: some modules have access to more variables than
2.25 had, there are more method functions, access is safer and -- my
favorite -- the file selector (or file browser, if you prefer) is back. 
It's now in the Window module, along with an image selector, too.  From
what I know, the FileSelector was the only reason for wanting the GUI
module (which disappeared) back.

- Coding

Personally, I keep the Camera module as a reference, since it is like
most others, in terms of programming, but is smaller and simple.  It's
in Camera.c and Camera.h . To have it working, it was also necessary to
include a line to the end of Blender.c (registering it as a Blender
submodule) and another to modules.h (declaring its init method)

Currently, one of our conventions is to prepend M_ to module functions,
doc strings, etc. and C_ to the new types we had to create for Python,
like C_Camera, C_Lamp, etc.

If you look at Camera.[ch], you'll find code for creating the Camera
module and the Camera "type", with all its methods and access policies. 
It's really a new type defined in Python, like PyInt or PyFloat,
PyString, etc.  In practice, it's a "thin" (because it doesn't make
copies of the variables) wrapper for the Blender Camera Data Object.

A note about Blender: objects in Blender share a common base, the
Object, whose attributes are things like the matrix, the location, the
rotation, the size, etc.  A Camera is actually an Object of type Camera
(which means that its "data" field points to a Camera Data obj) and a
Camera Data obj, which is the specific camera part of the object
(attributes like lens, clip start, etc.).  Same for other objects, like
Lamp, Mesh, etc.

That's why C_Camera is a wrapper for the Blender Camera **Data**
object.  The full wrapper is Object("Camera") linked with
Camera("camera_name").

How to write a new module from a simple object like Camera?  Use
Camera.[ch] as templates, check the specifics of your object in the
makesdna dir (for example, the camera one is DNA_camera_types.h) and
make the necessary changes.  That's how I did.  Looked at Michel's
Object.c, made the start of Camera.c, then improved it till it was a
good template.  Then I used it to write Lamp.c and the others I worked
on, except the files and pieces of code that were only pasted /
integrated / improved / etc from old bpython files.  There's no module
World in 2.25, but that might be an easy one to add.  There are many
others, more complicate.  Anything, just ask and we all can think about
it together, that's what this list is for.

Well, guess this is enough for a start : ) ...

--
Willian, wgermano at ig.com.br