diff options
Diffstat (limited to 'doc/guides/python-dev-guide.txt')
-rw-r--r-- | doc/guides/python-dev-guide.txt | 170 |
1 files changed, 0 insertions, 170 deletions
diff --git a/doc/guides/python-dev-guide.txt b/doc/guides/python-dev-guide.txt deleted file mode 100644 index 75c9ccb57e5..00000000000 --- a/doc/guides/python-dev-guide.txt +++ /dev/null @@ -1,170 +0,0 @@ -Simple Blender Python Developer's Guide ---------------------------------------- - -This is an outline for a future guide yet to be written. It is meant for -programmers wanting to understand and maybe help with the embedding of Python -inside Blender. - -I - Introduction - -We could praise Python here for its many qualities, but it's probably better -to just give some links: - -The main site is at www.python.org , with documentation at www.python.org/doc/ - -Also worth of mention: it's an interpreted language and is available for -many different systems. The download includes the interpreter, many modules -(think libs), good documentation and some programs / examples. If you use -linux, there's a high chance you already have Python installed, just try -"man python". - -The reason for embedding a language environment inside Blender is to give -users the ability to access the program's internal data and functionality. -This can be used to import / export (from / to other 2d / 3d formats) or -change the data (to create new objects procedurally, among many other -interesting possibilities). Script writers (Blender Python programmers) can -also expand Blender in new ways, adding new features on-the-fly, without having -to recompile it. It is usually much easier and faster to write scripts in -Python than to code the equivalent in C. - -II - 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. Specially useful as a fast reference is its Index, at letter -P, where all commands are. - -Specially useful commands are Py_BuildValue and the family of parsing -functions, PyArg_Parse* (PyArg_Parse(), PyArg_ParseTuple(), -PyArg_ParseTupleAndKeywords()). 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 resource. - -- The Blender 2.25 API documentation ( www.blender.org ) is, along with -the source, our basic API ref. - -III - 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 to "freeze" it. - -Another important dir for starters is blender/source/blender/makesdna, -where the headers with Blender structs lie. - -IV - Experimental Python - -The new implementation, currently referred to 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. - -It is in blender/source/blender/python , more specifically inside -api2_2x/ - -To make it clear, exppython is the new implementation being worked on. It -will possibly become the de-facto implementation in Blender 2.28, the next -Blender version. Currently, Blender still comes with the same implementation -found in the 2.25 version of the program. So we call that the 2.25 -implementation, or bpython. - -BPython had plenty of "macro magic", lot's of complicate #define's, etc., -since a lot of the embedding work is quite repetitive. But that 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 and the access is safer; -- the file selector (or file browser, if you prefer) is back: - It's now in the Window module, along with an image selector, too. -- there are totally new modules, unavailable in 2.25: - Fellow new developers joining our team are contributing new modules - that have been requested by the community for a long time. - - -V - Coding - -The Camera module is a good 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 and CreateObject 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 object, 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 for a simple object? 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. - -If you want to help exppython and in the process possibly learn more about -embedding, the Python/C API and Blender internals, there's this mailing list: - -Bf-python mailing list -Bf-python@blender.org -http://www.blender.org/mailman/listinfo/bf-python - -There you can ask what hasn't been done yet, get help, make suggestions for -new features we should consider, send bug reports, etc. |