== docs ==
authorLuca Bonavita <mindrones@gmail.com>
Wed, 13 Oct 2010 14:44:22 +0000 (14:44 +0000)
committerLuca Bonavita <mindrones@gmail.com>
Wed, 13 Oct 2010 14:44:22 +0000 (14:44 +0000)
- 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 :)

17 files changed:
doc/build_systems/README.windows-gcc [moved from doc/README.windows-gcc with 100% similarity]
doc/build_systems/cmake.txt [moved from doc/blender-cmake.txt with 100% similarity]
doc/build_systems/scons-dev.txt [moved from doc/blender-scons-dev.txt with 100% similarity]
doc/build_systems/scons.txt [moved from doc/blender-scons.txt with 99% similarity]
doc/guides/blender-guardedalloc.txt [moved from doc/blender-guardedalloc.txt with 100% similarity]
doc/guides/interface_API.txt [moved from doc/interface_API.txt with 100% similarity]
doc/guides/python-dev-guide.txt [new file with mode: 0644]
doc/license/BL-license.txt [moved from doc/BL-license.txt with 100% similarity]
doc/license/GPL-license.txt [moved from doc/GPL-license.txt with 100% similarity]
doc/license/bf-members.txt [moved from doc/bf-members.txt with 100% similarity]
doc/manpage/blender.1 [moved from doc/blender.1 with 100% similarity]
doc/manpage/blender.1.py [moved from doc/blender.1.py with 98% similarity]

index fe23aacaabfa151c405c930c3db8fdb8289571cd..67dd7e4010072546ab6025696a8275bfc35abc71 100644 (file)
@@ -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 6e1e14ac224a742bd4c22f9f8a864bdef8514601..3be7c91320a650eb99fc4ebda1f5fab48c7dbea2 100644 (file)
@@ -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.
 Apart from the GNU GPL, Blender is not available under other licenses.
similarity index 99%
rename from doc/blender-scons.txt
rename to doc/build_systems/scons.txt
index 016ba39fd09745ce4799109599eb01d5cce97464..b4d9a90588500a290577c4bd54d840ada422a31c 100644 (file)
@@ -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/guides/python-dev-guide.txt b/doc/guides/python-dev-guide.txt
new file mode 100644 (file)
index 0000000..75c9ccb
--- /dev/null
@@ -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
+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
+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
+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
+There you can ask what hasn't been done yet, get help, make suggestions for 
+new features we should consider, send bug reports, etc.
similarity index 100%
rename from doc/blender.1
rename to doc/manpage/blender.1
similarity index 98%
rename from doc/blender.1.py
rename to doc/manpage/blender.1.py
index 086c99e70e50a6d27eebab47c9267317e642a480..805de1f24a156164f2563cb50728f2ea288489cf 100644 (file)
@@ -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()
index 97a3225f5c638bfdfd673a1040adddc99def9194..55428a4a2412d636367e50a608489b73c400e1b1 100644 (file)
@@ -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
index 9d22f3c5212cf12a9c8248a30d1bf64c7fa53fce..ca7065ca636232845f3f11bf8d2c4717c58f23b8 100644 (file)
@@ -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 <math.h>
 #include <stdlib.h>
index dbd2f817204af73f55059d12ee3e596227e661cd..0433f76c84657e9f2aa14df266ec0a29d34fe9a8 100644 (file)
@@ -212,7 +212,7 @@ IF(WITH_INSTALL)
                        DESTINATION ${CMAKE_INSTALL_PREFIX}/bin
-                       FILES ${CMAKE_SOURCE_DIR}/doc/blender.1
+                       FILES ${CMAKE_SOURCE_DIR}/doc/manpage/blender.1
                        DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man1