From 9f05cc59fab2cd3e82be759e46bf4dacd2dbad05 Mon Sep 17 00:00:00 2001 From: Luca Bonavita Date: Wed, 13 Oct 2010 14:44:22 +0000 Subject: [PATCH] == docs == - moved files in proper directories and adapted paths where needed - deleted doc/oldbugs.txt (asked confirmation to jesterking a week ago in irc) - still working on doxygen files, for now I'll leave them in doc/ - NOTE: while checking if other files were referring to these files, I noted that "GPL-license.txt" is also used in the files below: - release/windows/installer/00.sconsblender.nsi - release/windows/specific.sh but these files should't be affected by this commit, but please check :) --- CMakeLists.txt | 2 +- COPYING | 2 +- doc/{ => build_systems}/README.windows-gcc | 0 .../cmake.txt} | 0 .../scons-dev.txt} | 0 .../scons.txt} | 2 +- doc/{ => guides}/blender-guardedalloc.txt | 0 doc/{ => guides}/interface_API.txt | 0 doc/guides/python-dev-guide.txt | 170 ++++++++++++++++++ doc/{ => license}/BL-license.txt | 0 doc/{ => license}/GPL-license.txt | 0 doc/{ => license}/bf-members.txt | 0 doc/{ => manpage}/blender.1 | 0 doc/{ => manpage}/blender.1.py | 2 +- source/blender/editors/interface/interface.c | 2 +- .../editors/interface/interface_panel.c | 2 +- source/creator/CMakeLists.txt | 2 +- 17 files changed, 177 insertions(+), 7 deletions(-) rename doc/{ => build_systems}/README.windows-gcc (100%) rename doc/{blender-cmake.txt => build_systems/cmake.txt} (100%) rename doc/{blender-scons-dev.txt => build_systems/scons-dev.txt} (100%) rename doc/{blender-scons.txt => build_systems/scons.txt} (99%) rename doc/{ => guides}/blender-guardedalloc.txt (100%) rename doc/{ => guides}/interface_API.txt (100%) create mode 100644 doc/guides/python-dev-guide.txt rename doc/{ => license}/BL-license.txt (100%) rename doc/{ => license}/GPL-license.txt (100%) rename doc/{ => license}/bf-members.txt (100%) rename doc/{ => manpage}/blender.1 (100%) rename doc/{ => manpage}/blender.1.py (98%) diff --git a/CMakeLists.txt b/CMakeLists.txt index fe23aacaabf..67dd7e40100 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -146,7 +146,7 @@ TEST_SSE_SUPPORT() # On Macs: # cmake -D PYTHON_INC=/System/Library/Frameworks/Python.framework/Versions/3.1/include/python3.1 -D PYTHON_LIBPATH=/System/Library/Frameworks/Python.framework/Versions/3.1/lib/python3.1/config -G Xcode ../blender # -# When changing any of this remember to update the notes in doc/blender-cmake.txt +# When changing any of this remember to update the notes in doc/build_systems/cmake.txt #----------------------------------------------------------------------------- #Platform specifics diff --git a/COPYING b/COPYING index 6e1e14ac224..3be7c91320a 100644 --- a/COPYING +++ b/COPYING @@ -2,7 +2,7 @@ Blender uses the GNU General Public License, which describes the rights to distribute or change the code. Please read this file for the full license. -doc/GPL-license.txt +doc/license/GPL-license.txt Apart from the GNU GPL, Blender is not available under other licenses. diff --git a/doc/README.windows-gcc b/doc/build_systems/README.windows-gcc similarity index 100% rename from doc/README.windows-gcc rename to doc/build_systems/README.windows-gcc diff --git a/doc/blender-cmake.txt b/doc/build_systems/cmake.txt similarity index 100% rename from doc/blender-cmake.txt rename to doc/build_systems/cmake.txt diff --git a/doc/blender-scons-dev.txt b/doc/build_systems/scons-dev.txt similarity index 100% rename from doc/blender-scons-dev.txt rename to doc/build_systems/scons-dev.txt diff --git a/doc/blender-scons.txt b/doc/build_systems/scons.txt similarity index 99% rename from doc/blender-scons.txt rename to doc/build_systems/scons.txt index 016ba39fd09..b4d9a905885 100644 --- a/doc/blender-scons.txt +++ b/doc/build_systems/scons.txt @@ -20,7 +20,7 @@ $Id$ with the patch to get started. This document describes the usage of the new SCons scripts. The - inner workings are described in blender-scons-dev.txt. + inner workings are described in scons-dev.txt. Building Blender ---------------- diff --git a/doc/blender-guardedalloc.txt b/doc/guides/blender-guardedalloc.txt similarity index 100% rename from doc/blender-guardedalloc.txt rename to doc/guides/blender-guardedalloc.txt diff --git a/doc/interface_API.txt b/doc/guides/interface_API.txt similarity index 100% rename from doc/interface_API.txt rename to doc/guides/interface_API.txt diff --git a/doc/guides/python-dev-guide.txt b/doc/guides/python-dev-guide.txt new file mode 100644 index 00000000000..75c9ccb57e5 --- /dev/null +++ b/doc/guides/python-dev-guide.txt @@ -0,0 +1,170 @@ +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. diff --git a/doc/BL-license.txt b/doc/license/BL-license.txt similarity index 100% rename from doc/BL-license.txt rename to doc/license/BL-license.txt diff --git a/doc/GPL-license.txt b/doc/license/GPL-license.txt similarity index 100% rename from doc/GPL-license.txt rename to doc/license/GPL-license.txt diff --git a/doc/bf-members.txt b/doc/license/bf-members.txt similarity index 100% rename from doc/bf-members.txt rename to doc/license/bf-members.txt diff --git a/doc/blender.1 b/doc/manpage/blender.1 similarity index 100% rename from doc/blender.1 rename to doc/manpage/blender.1 diff --git a/doc/blender.1.py b/doc/manpage/blender.1.py similarity index 98% rename from doc/blender.1.py rename to doc/manpage/blender.1.py index 086c99e70e5..805de1f24a1 100644 --- a/doc/blender.1.py +++ b/doc/manpage/blender.1.py @@ -44,7 +44,7 @@ def man_format(data): return data -blender_bin = os.path.join(os.path.dirname(__file__), "../blender") +blender_bin = os.path.join(os.path.dirname(__file__), "../../blender") blender_help = subprocess.Popen([blender_bin, "--help"], stdout=subprocess.PIPE).communicate()[0].decode() diff --git a/source/blender/editors/interface/interface.c b/source/blender/editors/interface/interface.c index 97a3225f5c6..55428a4a241 100644 --- a/source/blender/editors/interface/interface.c +++ b/source/blender/editors/interface/interface.c @@ -67,7 +67,7 @@ #define MENU_SEP_HEIGHT 6 /* - * a full doc with API notes can be found in bf-blender/blender/doc/interface_API.txt + * a full doc with API notes can be found in bf-blender/trunk/blender/doc/guides/interface_API.txt * * uiBlahBlah() external function * ui_blah_blah() internal function diff --git a/source/blender/editors/interface/interface_panel.c b/source/blender/editors/interface/interface_panel.c index 9d22f3c5212..ca7065ca636 100644 --- a/source/blender/editors/interface/interface_panel.c +++ b/source/blender/editors/interface/interface_panel.c @@ -25,7 +25,7 @@ * ***** END GPL LICENSE BLOCK ***** */ -/* a full doc with API notes can be found in bf-blender/blender/doc/interface_API.txt */ +/* a full doc with API notes can be found in bf-blender/trunk/blender/doc/guides/interface_API.txt */ #include #include diff --git a/source/creator/CMakeLists.txt b/source/creator/CMakeLists.txt index dbd2f817204..0433f76c846 100644 --- a/source/creator/CMakeLists.txt +++ b/source/creator/CMakeLists.txt @@ -212,7 +212,7 @@ IF(WITH_INSTALL) DESTINATION ${CMAKE_INSTALL_PREFIX}/bin ) INSTALL( - FILES ${CMAKE_SOURCE_DIR}/doc/blender.1 + FILES ${CMAKE_SOURCE_DIR}/doc/manpage/blender.1 DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1 ) INSTALL(