Merging r47572 through r47580 form trunk into soc-2011-tomato
[blender.git] / doc / guides / 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.