Merging trunk up to r38932.

8 files changed, 234 insertions, 67 deletions

diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst
index 882bbc39b9f..12ce8617457 100644
--- a/doc/python_api/rst/bge.constraints.rst
+++ b/doc/python_api/rst/bge.constraints.rst
@@ -1,28 +1,47 @@
 
-Game Engine bge.constraints Module
-==================================
+Physics Constraints (bge.constraints)
+=====================================
 
-.. note::
-   This documentation is still very weak, and needs some help!
-
-.. function:: createConstraint([obj1, [obj2, [restLength, [restitution, [damping]]]]])
+.. function:: createConstraint(physicsid, physicsid2, constrainttype, [pivotX, pivotY, pivotZ, [axisX, axisY, axisZ, [flag]]]])
 
    Creates a constraint.
 
-   :arg obj1: first object on Constraint
-   :type obj1: :class:'bge.types.KX_GameObject' #I think, there is no error when I use one
+   :arg physicsid: the physics id of the first object in constraint
+   :type physicsid: int
 
-   :arg obj2: second object on Constraint
-   :type obj2: :class:'bge.types.KX_GameObject' #too
+   :arg physicsid2: the physics id of the second object in constraint
+   :type physicsid2: int
 
-   :arg restLength: #to be filled
-   :type restLength: float
+   :arg constrainttype: the type of the constraint. The constraint types are:
 
-   :arg restitution: #to be filled
-   :type restitution: float
+   - :class:`POINTTOPOINT_CONSTRAINT`
+   - :class:`LINEHINGE_CONSTRAINT`
+   - :class:`ANGULAR_CONSTRAINT`
+   - :class:`CONETWIST_CONSTRAINT`
+   - :class:`VEHICLE_CONSTRAINT`
 
-   :arg damping: #to be filled
-   :type damping: float
+   :type constrainttype: int
+
+   :arg pivotX: pivot X position
+   :type pivotX: float
+
+   :arg pivotY: pivot Y position
+   :type pivotY: float
+
+   :arg pivotZ: pivot Z position
+   :type pivotZ: float
+
+   :arg axisX: X axis
+   :type axisX: float
+
+   :arg axisY: Y axis
+   :type axisY: float
+
+   :arg axisZ: Z axis
+   :type axisZ: float
+
+   :arg flag: .. to do
+   :type flag: int
 
 .. attribute:: error
 
@@ -49,7 +68,7 @@ Game Engine bge.constraints Module
    :type constraintId: int
 
    :return: a vehicle constraint object.
-   :rtype: :class:'KX_VehicleWrapper'
+   :rtype: :class:`bge.types.KX_VehicleWrapper`
 
 .. function:: removeConstraint(constraintId)
 
@@ -60,10 +79,10 @@ Game Engine bge.constraints Module
 
 .. function:: setCcdMode(ccdMode)
 
-   ..note::
+   .. note::
       Very experimental, not recommended
 
-   Sets the CCD mode in the Physics Environment.
+   Sets the CCD (Continous Colision Detection) mode in the Physics Environment.
 
    :arg ccdMode: The new CCD mode.
    :type ccdMode: int
@@ -73,21 +92,21 @@ Game Engine bge.constraints Module
    .. note::
       Reasonable default is 0.02 (if units are meters)
 
-   Sets the contact breaking treshold in the Physics Environment.
+   Sets tresholds to do with contact point management.
 
    :arg breakingTreshold: The new contact breaking treshold.
    :type breakingTreshold: float
 
 .. function:: setDeactivationAngularTreshold(angularTreshold)
 
-   Sets the deactivation angular treshold.
+   Sets the angular velocity treshold.
 
    :arg angularTreshold: New deactivation angular treshold.
    :type angularTreshold: float
 
 .. function:: setDeactivationLinearTreshold(linearTreshold)
 
-   Sets the deactivation linear treshold.
+   Sets the linear velocity treshold.
 
    :arg linearTreshold: New deactivation linear treshold.
    :type linearTreshold: float
@@ -104,21 +123,20 @@ Game Engine bge.constraints Module
    Sets the debug mode.
 
    Debug modes:
-      - No debug: 0
-      - Draw wireframe: 1
-      - Draw Aabb: 2 #What's Aabb?
-      - Draw freatures text: 4
-      - Draw contact points: 8
-      - No deactivation: 16
-      - No help text: 32
-      - Draw text: 64
-      - Profile timings: 128
-      - Enable sat comparision: 256
-      - Disable Bullet LCP: 512
-      - Enable CCD: 1024
-      - Draw Constraints: #(1 << 11) = ?
-      - Draw Constraint Limits: #(1 << 12) = ?
-      - Fast Wireframe: #(1 << 13) = ?
+      - :class:`DBG_NODEBUG`
+      - :class:`DBG_DRAWWIREFRAME`
+      - :class:`DBG_DRAWAABB`
+      - :class:`DBG_DRAWFREATURESTEXT`
+      - :class:`DBG_DRAWCONTACTPOINTS`
+      - :class:`DBG_NOHELPTEXT`
+      - :class:`DBG_DRAWTEXT`
+      - :class:`DBG_PROFILETIMINGS`
+      - :class:`DBG_ENABLESATCOMPARISION`
+      - :class:`DBG_DISABLEBULLETLCP`
+      - :class:`DBG_ENABLECCD`
+      - :class:`DBG_DRAWCONSTRAINTS`
+      - :class:`DBG_DRAWCONSTRAINTLIMITS`
+      - :class:`DBG_FASTWIREFRAME`
 
    :arg mode: The new debug mode.
    :type mode: int
@@ -138,7 +156,10 @@ Game Engine bge.constraints Module
 
 .. function:: setLinearAirDamping(damping)
 
-   Not implemented.
+   .. note::
+      Not implemented.
+
+   Sets the linear air damping for rigidbodies.
 
 .. function:: setNumIterations(numiter)
 
@@ -156,10 +177,10 @@ Game Engine bge.constraints Module
 
 .. function:: setSolverDamping(damping)
 
-   ..note::
+   .. note::
       Very experimental, not recommended
 
-   Sets the solver damping.
+   Sets the damper constant of a penalty based solver.
 
    :arg damping: New damping for the solver.
    :type damping: float
@@ -169,7 +190,7 @@ Game Engine bge.constraints Module
    .. note::
       Very experimental, not recommended
 
-   Sets the solver tau.
+   Sets the spring constant of a penalty based solver.
 
    :arg tau: New tau for the solver.
    :type tau: float
@@ -189,7 +210,7 @@ Game Engine bge.constraints Module
    .. note::
       Very experimental, not recommended
 
-   Sets the sor constant.
+   Sets the successive overrelaxation constant.
 
    :arg sor: New sor value.
    :type sor: float
@@ -197,3 +218,136 @@ Game Engine bge.constraints Module
 .. function:: setUseEpa(epa)
 
    Not implemented.
+
+.. data:: DBG_NODEBUG
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   No debug.
+
+.. data:: DBG_DRAWWIREFRAME
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw wireframe in debug.
+
+.. data:: DBG_DRAWAABB
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw Axis Aligned Bounding Box in debug.
+
+.. data:: DBG_DRAWFREATURESTEXT
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw freatures text in debug.
+
+.. data:: DBG_DRAWCONTACTPOINTS
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw contact points in debug.
+
+.. data:: DBG_NOHELPTEXT
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Debug without help text.
+
+.. data:: DBG_DRAWTEXT
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw text in debug.
+
+.. data:: DBG_PROFILETIMINGS
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw profile timings in debug.
+
+.. data:: DBG_ENABLESATCOMPARISION
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Enable sat comparision in debug.
+
+.. data:: DBG_DISABLEBULLETLCP
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Disable Bullet LCP.
+
+.. data:: DBG_ENABLECCD
+
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Enable Continous Colision Detection in debug.
+
+.. data:: DBG_DRAWCONSTRAINTS
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw constraints in debug.
+
+.. data:: DBG_DRAWCONSTRAINTLIMITS
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw constraint limits in debug.
+
+.. data:: DBG_FASTWIREFRAME
+   
+   .. note::
+      Debug mode to be used with function :class:`setDebugMode`
+   
+   Draw a fast wireframe in debug.
+
+.. data:: POINTTOPOINT_CONSTRAINT
+
+   .. note::
+      Constraint type to be used with function :class:`createConstraint`
+
+   .. to do
+
+.. data:: LINEHINGE_CONSTRAINT
+
+   .. note::
+      Constraint type to be used with function :class:`createConstraint`
+
+   .. to do
+
+.. data:: ANGULAR_CONSTRAINT
+
+   .. note::
+      Constraint type to be used with function :class:`createConstraint`
+
+   .. to do
+
+.. data:: CONETWIST_CONSTRAINT
+
+   .. note::
+       Constraint type to be used with function :class:`createConstraint`
+
+   .. to do
+
+.. data:: VEHICLE_CONSTRAINT
+
+   .. note::
+      Constraint type to be used with function :class:`createConstraint`
+
+   .. to do
diff --git a/doc/python_api/rst/bge.events.rst b/doc/python_api/rst/bge.events.rst
index cc76ecded85..074e928f0d8 100644
--- a/doc/python_api/rst/bge.events.rst
+++ b/doc/python_api/rst/bge.events.rst
@@ -1,6 +1,6 @@
 
-Game Engine bge.events Module
-=============================
+Game Keys (bge.events)
+======================
 
 *****
 Intro
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index f7163ea928e..128f87f76bd 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -1,6 +1,7 @@
 
-Game Engine bge.logic Module
-============================
+Game Logic (bge.logic)
+======================
+
 *****
 Intro
 *****
diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst
index 9f17455601b..10514049a8a 100644
--- a/doc/python_api/rst/bge.render.rst
+++ b/doc/python_api/rst/bge.render.rst
@@ -1,6 +1,6 @@
 
-Game Engine bge.render Module
-=============================
+Rasterizer (bge.render)
+=======================
 
 *****
 Intro
@@ -16,8 +16,8 @@ Intro
    import bge.render
    import bge.logic
 
-   # SCALE sets the speed of motion
-   SCALE=[1, 0.5]
+   # scale sets the speed of motion
+   scale = 1.0, 0.5
    
    co = bge.logic.getCurrentController()
    obj = co.getOwner()
@@ -27,8 +27,8 @@ Intro
    
    # Transform the mouse coordinates to see how far the mouse has moved.
    def mousePos():
-      x = (bge.render.getWindowWidth()/2 - mouse.getXPosition())*SCALE[0]
-      y = (bge.render.getWindowHeight()/2 - mouse.getYPosition())*SCALE[1]
+      x = (bge.render.getWindowWidth() / 2 - mouse.getXPosition()) * scale[0]
+      y = (bge.render.getWindowHeight() / 2 - mouse.getYPosition()) * scale[1]
       return (x, y)
    
    pos = mousePos()
@@ -43,7 +43,7 @@ Intro
    bge.logic.addActiveActuator(wmotion, True)
    
    # Centre the mouse
-   bge.render.setMousePosition(bge.render.getWindowWidth()/2, bge.render.getWindowHeight()/2)
+   bge.render.setMousePosition(bge.render.getWindowWidth() / 2, bge.render.getWindowHeight() / 2)
 
 *********
 Constants
diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
index 996f79a313a..f3e9f98dded 100644
--- a/doc/python_api/rst/bge.texture.rst
+++ b/doc/python_api/rst/bge.texture.rst
@@ -1,10 +1,6 @@
 
-Game Engine bge.texture Module
-==============================
-
-.. note::
-   This documentation is still very weak, and needs some help! Right now they are mostly a collection
-   of the docstrings found in the bge.texture source code + some random places filled with text.
+Video Texture (bge.texture)
+===========================
 
 *****
 Intro
diff --git a/doc/python_api/rst/bge.types.rst b/doc/python_api/rst/bge.types.rst
index 367f6470f19..d1fc8593e42 100644
--- a/doc/python_api/rst/bge.types.rst
+++ b/doc/python_api/rst/bge.types.rst
@@ -1,6 +1,6 @@
 
-Game Engine  bge.types Module
-=============================
+Game Types (bge.types)
+======================
 
 .. module:: bge.types
 
diff --git a/doc/python_api/rst/bgl.rst b/doc/python_api/rst/bgl.rst
index 76b7442f2c5..236bfafb295 100644
--- a/doc/python_api/rst/bgl.rst
+++ b/doc/python_api/rst/bgl.rst
@@ -1,6 +1,6 @@
 
-bgl module (OpenGL wrapper)
-===========================
+OpenGL Wrapper (bgl)
+====================
 
 .. module:: bgl
 
@@ -71,8 +71,8 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    .. seealso:: `OpenGL Docs <http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/begin.html>`_
 
    :type mode: Enumerated constant
-   :arg mode: Specifies the primitive that will be create from vertices between glBegin and
-      glEnd.
+   :arg mode: Specifies the primitive that will be create from vertices between
+      glBegin and glEnd.
 
 
 .. function:: glBindTexture(target, texture):
@@ -1886,4 +1886,3 @@ class Buffer:
          the Buffer. If a template is not passed in all fields will be initialized to 0.
       :rtype: Buffer object
       :return: The newly created buffer as a PyObject.
-
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 6b514cf9eb1..f8561c719bc 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -416,6 +416,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
     del key, descr
 
     classes = []
+    submodules = []
 
     for attribute in module_dir:
         if not attribute.startswith("_"):
@@ -437,6 +438,8 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
                 py_c_func2sphinx("", fw, module_name, None, attribute, value, is_class=False)
             elif value_type == type:
                 classes.append((attribute, value))
+            elif issubclass(value_type, types.ModuleType):
+                submodules.append((attribute, value))
             elif value_type in (bool, int, float, str, tuple):
                 # constant, not much fun we can do here except to list it.
                 # TODO, figure out some way to document these!
@@ -444,12 +447,26 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
                 write_indented_lines("   ", fw, "constant value %s" % repr(value), False)
                 fw("\n")
             else:
-                print("\tnot documenting %s.%s" % (module_name, attribute))
+                print("\tnot documenting %s.%s of %r type" % (module_name, attribute, value_type.__name__))
                 continue
 
             attribute_set.add(attribute)
             # TODO, more types...
 
+    # TODO, bpy_extras does this already, mathutils not.
+    """
+    if submodules:
+        fw("\n"
+           "**********\n"
+           "Submodules\n"
+           "**********\n"
+           "\n"
+           )
+        for attribute, submod in submodules:
+            fw("* :mod:`%s.%s`\n" % (module_name, attribute))
+        fw("\n")
+    """
+
     # write collected classes now
     for (type_name, value) in classes:
         # May need to be its own function