doc/python-dev-guide.txt

   1 Simple Blender Python Developer's Guide
   2 ---------------------------------------
   3
   4 This is an outline for a future guide yet to be written.  It is meant for
   5 programmers wanting to understand and maybe help with the embedding of Python
   6 inside Blender.
   7
   8 I - Introduction
   9
  10 We could praise Python here for its many qualities, but it's probably better
  11 to just give some links:
  12
  13 The main site is at www.python.org , with documentation at www.python.org/doc/
  14
  15 Also worth of mention: it's an interpreted language and is available for
  16 many different systems.  The download includes the interpreter, many modules
  17 (think libs), good documentation and some programs / examples.  If you use
  18 linux, there's a high chance you already have Python installed, just try
  19 "man python".
  20
  21 The reason for embedding a language environment inside Blender is to give
  22 users the ability to access the program's internal data and functionality.
  23 This can be used to import / export (from / to other 2d / 3d formats) or
  24 change the data (to create new objects procedurally, among many other
  25 interesting possibilities).  Script writers (Blender Python programmers) can
  26 also expand Blender in new ways, adding new features on-the-fly, without having
  27 to recompile it.  It is usually much easier and faster to write scripts in
  28 Python than to code the equivalent in C.
  29
  30 II - Reference material:
  31
  32 There are two important texts for us in the documentation that comes
  33 with Python ( docs also available online at www.python.org ):
  34
  35 - Extending and Embedding (tutorial for C/C++ programmers)
  36
  37 and specially
  38
  39 - Python/C API.
  40
  41 You can read the first one to get a feel for how things are done
  42 (reference counting is probably the most important part), but the second
  43 doc is a must.  Specially useful as a fast reference is its Index, at letter
  44 P, where all commands are.
  45
  46 Specially useful commands are Py_BuildValue and the family of parsing
  47 functions, PyArg_Parse* (PyArg_Parse(), PyArg_ParseTuple(),
  48 PyArg_ParseTupleAndKeywords()). Py_BuildValue is usually the best way to make
  49 Python Objects (the 'variables' that the Python Interpreter understands)
  50 out of C ones.  The PyArg_Parse* functions do the opposite, they parse
  51 Python Objects to C variables.
  52
  53 So, understand PyArg_Parse* functions, Py_BuildValue and reference
  54 counting.  The first doc has a good discussion about them.
  55
  56 - C knowledge is also necessary, of course, use your favorite resource.
  57
  58 - The Blender 2.25 API documentation ( www.blender.org ) is, along with
  59 the source, our basic API ref.
  60
  61 III - Directories
  62
  63 The previous Blender Python API's are spread in blender/intern/python
  64 and the C part of the current one, bpython, is at
  65 blender/source/blender/bpython/, specially in intern/.  The current
  66 solution is a Python wrapper on top of this bpython one, at
  67 blender/intern/python/modules/Blender/
  68
  69 Note: since it's in Python, they needed the freeze Python utility, a
  70 process/program that creates stand-alone executables out of Python
  71 source files -- that is, it packs together an interpreter, the needed
  72 modules and the source of a Python program so that users of this program
  73 don't need to have the Python interpreter already installed in their
  74 machines to run the program -- Blender, in this case.
  75
  76 The new implementation is pure C, so we won't need to "freeze" it.
  77
  78 Another important dir for starters is blender/source/blender/makesdna,
  79 where the headers with Blender structs lie.
  80
  81 IV - Experimental Python
  82
  83 The new implementation, currently referred to as experimental python -
  84 exppython - was started by Michel Selten.  He chose to solve the mess in
  85 Blender Python by starting over from scratch, in C, but keeping API
  86 compatibility with the current 2.25 API used by Blender.
  87
  88 It is in blender/source/blender/python , more specifically inside
  89 api2_2x/
  90
  91 To make it clear, exppython is the new implementation being worked on.  It
  92 will possibly become the de-facto implementation in Blender 2.28, the next
  93 Blender version.  Currently, Blender still comes with the same implementation
  94 found in the 2.25 version of the program.  So we call that the 2.25
  95 implementation, or bpython.
  96
  97 BPython had plenty of "macro magic", lot's of complicate #define's, etc.,
  98 since a lot of the embedding work is quite repetitive.  But that makes it
  99 much harder for newbies to jump in and learn, so the new files in exppython
 100 avoid that.
 101
 102 This means: Blender, Object, Camera, Lamp, Image, Text, Window modules
 103 (the files have the same names, ending obviously with .c and .h)
 104
 105 To speed things up, some independent parts of bpython are being
 106 integrated directly into exppython.  That already happened with Draw and
 107 BGL, both taken from opy_draw.c in the bpython/intern dir.  The same is
 108 happening with NMesh (Mesh is written in Python and imports NMesh to
 109 extend / change its functionality).
 110
 111 For a good example of dexterity with macros (cheers to the NaN
 112 programmer(s)!), look at BGL.[ch], the OpenGL API wrapper.  The defines
 113 are in the header.
 114
 115 Besides keeping compatibility with the 2.25 API, there are already some
 116 additions to exppython:
 117
 118 - some modules have access to more variables than 2.25 had;
 119 - there are more method functions and the access is safer;
 120 - the file selector (or file browser, if you prefer) is back:
 121     It's now in the Window module, along with an image selector, too.
 122 - there are totally new modules, unavailable in 2.25:
 123     Fellow new developers joining our team are contributing new modules
 124     that have been requested by the community for a long time.
 125
 126
 127 V - Coding
 128
 129 The Camera module is a good reference, since it is like most others, in
 130 terms of programming, but is smaller and simple.  It's in Camera.c and
 131 Camera.h .  To have it working, it was also necessary to include a line to
 132 the end of Blender.c (registering it as a Blender submodule) and another to
 133 modules.h (declaring its init and CreateObject method)
 134
 135 Currently, one of our conventions is to prepend M_ to module functions,
 136 doc strings, etc. and C_ to the new types we had to create for Python,
 137 like C_Camera, C_Lamp, etc.
 138
 139 If you look at Camera.[ch], you'll find code for creating the Camera
 140 module and the Camera "type", with all its methods and access policies.
 141 It's really a new type defined in Python, like PyInt or PyFloat,
 142 PyString, etc.  In practice, it's a "thin" (because it doesn't make
 143 copies of the variables) wrapper for the Blender Camera Data Object.
 144
 145 A note about Blender: objects in Blender share a common base, the
 146 Object, whose attributes are things like the matrix, the location, the
 147 rotation, the size, etc.  A Camera is actually an Object of type Camera
 148 (which means that its "data" field points to a Camera Data obj) and a
 149 Camera Data object, which is the specific camera part of the object
 150 (attributes like lens, clip start, etc.).  Same for other objects, like
 151 Lamp, Mesh, etc.
 152
 153 That's why C_Camera is a wrapper for the Blender Camera **Data**
 154 object.  The full wrapper is Object("Camera") linked with
 155 Camera("camera_name").
 156
 157 How to write a new module for a simple object?  Use Camera.[ch] as
 158 templates, check the specifics of your object in the makesdna dir
 159 (for example, the camera one is DNA_camera_types.h) and make the
 160 necessary changes.
 161
 162 If you want to help exppython and in the process possibly learn more about
 163 embedding, the Python/C API and Blender internals, there's this mailing list:
 164
 165 Bf-python mailing list
 166 Bf-python@blender.org
 167 http://www.blender.org/mailman/listinfo/bf-python
 168
 169 There you can ask what hasn't been done yet, get help, make suggestions for
 170 new features we should consider, send bug reports, etc.