Merged changes in the trunk up to revision 41099.

13 files changed, 390 insertions, 16 deletions

diff --git a/doc/build_systems/scons-dev.txt b/doc/build_systems/scons-dev.txt
index ca1b3924804..4cc4e6c6ec2 100644
--- a/doc/build_systems/scons-dev.txt
+++ b/doc/build_systems/scons-dev.txt
@@ -189,6 +189,6 @@ $Id$
     need changes elsewhere in the system, as it is handled automatically
     with the central library repository.
 
-    Enjoy the new system!
+    Enjoy the new system!!
 
     /Nathan Letwory (jesterKing)
diff --git a/doc/manpage/blender.1 b/doc/manpage/blender.1
index 20cd40e32ee..620a90e61d2 100644
--- a/doc/manpage/blender.1
+++ b/doc/manpage/blender.1
@@ -1,4 +1,4 @@
-.TH "BLENDER" "1" "September 22, 2011" "Blender Blender 2\&.59 (sub 3)"
+.TH "BLENDER" "1" "October 17, 2011" "Blender Blender 2\&.60 (sub 0)"
 
 .SH NAME
 blender \- a 3D modelling and rendering package
@@ -15,7 +15,7 @@ Use Blender to create TV commercials, to make technical visualizations, business
 http://www.blender.org
 .SH OPTIONS
 
-Blender 2.59 (sub 3)
+Blender 2.59 (sub 4)
 Usage: blender [args ...] [file] [args ...]
 .br
 .SS "Render Options:"
@@ -382,6 +382,7 @@ Arguments are executed in the order they are given. eg
   \fIBLENDER_SYSTEM_DATAFILES\fR Directory for system wide data files.
   \fIBLENDER_SYSTEM_PYTHON\fR Directory for system python libraries.
   \fITMP\fR or \fITMPDIR\fR Store temporary files here.
+  \fISDL_AUDIODRIVER\fR LibSDL audio driver \- alsa, esd, dma.
   \fIPYTHONHOME\fR Path to the python directory, eg. /usr/lib/python.
 .br
 .br
diff --git a/doc/manpage/blender.1.py b/doc/manpage/blender.1.py
index 40234300994..21df42a4082 100644
--- a/doc/manpage/blender.1.py
+++ b/doc/manpage/blender.1.py
@@ -22,6 +22,7 @@
 
 import subprocess
 import os
+import sys
 
 import time
 import datetime
@@ -43,10 +44,15 @@ def man_format(data):
 
     return data
 
+# allow passing blender as argument
+if sys.argv[-1].endswith(os.sep + "blender"):
+    blender_bin = sys.argv[-1]
+else:
+    blender_bin = os.path.join(os.path.dirname(__file__), "../../blender.bin")
 
-blender_bin = os.path.join(os.path.dirname(__file__), "../../blender.bin")
-
-blender_help = subprocess.Popen([blender_bin, "--help"], stdout=subprocess.PIPE).communicate()[0].decode()
+cmd = [blender_bin, "--help"]
+print("  executing:", " ".join(cmd))
+blender_help = subprocess.Popen(cmd, stdout=subprocess.PIPE).communicate()[0].decode()
 
 blender_version = subprocess.Popen([blender_bin, "--version"], stdout=subprocess.PIPE).communicate()[0].decode().strip()
 blender_version = blender_version.split("Build")[0]
diff --git a/doc/python_api/examples/mathutils.Color.py b/doc/python_api/examples/mathutils.Color.py
new file mode 100644
index 00000000000..a55f1195bf6
--- /dev/null
+++ b/doc/python_api/examples/mathutils.Color.py
@@ -0,0 +1,30 @@
+import mathutils
+
+# color values are represented as RGB values from 0 - 1, this is blue
+col = mathutils.Color((0.0, 0.0, 1.0))
+
+# as well as r/g/b attribute access you can adjust them by h/s/v
+col.s *= 0.5
+
+# you can access its components by attribute or index
+print("Color R:", col.r)
+print("Color G:", col[1])
+print("Color B:", col[-1])
+print("Color HSV: %.2f, %.2f, %.2f", col[:])
+
+
+# components of an existing color can be set
+col[:] = 0.0, 0.5, 1.0
+
+# components of an existing color can use slice notation to get a tuple
+print("Values: %f, %f, %f" % col[:])
+
+# colors can be added and subtracted
+col += mathutils.Color((0.25, 0.0, 0.0))
+
+# Color can be multiplied, in this example color is scaled to 0-255
+# can printed as integers
+print("Color: %d, %d, %d" % (col * 255.0)[:])
+
+# This example prints the color as hexidecimal
+print("Hexidecimal: %.2x%.2x%.2x" % (col * 255.0)[:])
diff --git a/doc/python_api/examples/mathutils.Euler.py b/doc/python_api/examples/mathutils.Euler.py
index bc7702c1d53..3f87cc0ab04 100644
--- a/doc/python_api/examples/mathutils.Euler.py
+++ b/doc/python_api/examples/mathutils.Euler.py
@@ -1,3 +1,32 @@
 import mathutils
+import math
 
-# todo
+# create a new euler with default axis rotation order
+eul = mathutils.Euler((0.0, math.radians(45.0), 0.0), 'XYZ')
+
+# rotate the euler
+eul.rotate_axis(math.radians(10.0), 'Z')
+
+# you can access its components by attribute or index
+print("Euler X", eul.x)
+print("Euler Y", eul[1])
+print("Euler Z", eul[-1])
+
+# components of an existing euler can be set
+eul[:] = 1.0, 2.0, 3.0
+
+# components of an existing euler can use slice notation to get a tuple
+print("Values: %f, %f, %f" % eul[:])
+
+# the order can be set at any time too
+eul.order = 'ZYX'
+
+# eulers can be used to rotate vectors
+vec = mathutils.Vector((0.0, 0.0, 1.0))
+vec.rotate(eul)
+
+# often its useful to convert the euler into a matrix so it can be used as
+# transformations with more flexibility
+mat_rot = eul.to_matrix()
+mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
+mat = mat_loc * mat_rot.to_4x4()
diff --git a/doc/python_api/examples/mathutils.Matrix.py b/doc/python_api/examples/mathutils.Matrix.py
index bc7702c1d53..079070a5ec7 100644
--- a/doc/python_api/examples/mathutils.Matrix.py
+++ b/doc/python_api/examples/mathutils.Matrix.py
@@ -1,3 +1,28 @@
 import mathutils
+import math
 
-# todo
+# create a location matrix
+mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
+
+# create an identitiy matrix
+mat_sca = mathutils.Matrix.Scale(0.5, 4, (0.0, 0.0, 1.0))
+
+# create a rotation matrix
+mat_rot = mathutils.Matrix.Rotation(math.radians(45.0), 4, 'X')
+
+# combine transformations
+mat_out = mat_loc * mat_rot * mat_sca
+print(mat_out)
+
+# extract components back out of the matrix
+loc, rot, sca = mat_out.decompose()
+print(loc, rot, sca)
+
+# it can also be useful to access components of a matrix directly
+mat = mathutils.Matrix()
+mat[0][0], mat[1][0], mat[2][0] = 0.0, 1.0, 2.0
+
+mat[0][0:3] = 0.0, 1.0, 2.0
+
+# each item in a matrix is a vector so vector utility functions can be used
+mat[0].xyz = 0.0, 1.0, 2.0
diff --git a/doc/python_api/examples/mathutils.Quaternion.py b/doc/python_api/examples/mathutils.Quaternion.py
index bc7702c1d53..d8c696e6ba6 100644
--- a/doc/python_api/examples/mathutils.Quaternion.py
+++ b/doc/python_api/examples/mathutils.Quaternion.py
@@ -1,3 +1,23 @@
 import mathutils
+import math
 
-# todo
+# a new rotation 90 degrees about the Y axis
+quat_a = mathutils.Quaternion((0.7071068, 0.0, 0.7071068, 0.0))
+
+# passing values to Quaternion's directly can be confusing so axis, angle
+# is supported for initializing too
+quat_b = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
+
+print("Check quaternions match", quat_a == quat_b)
+
+# like matrices, quaternions can be multiplied to accumulate rotational values
+quat_a = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
+quat_b = mathutils.Quaternion((0.0, 0.0, 1.0), math.radians(45.0))
+quat_out = quat_a * quat_b
+
+# print the quat, euler degrees for mear mortals and (axis, angle)
+print("Final Rotation:")
+print(quat_out)
+print("%.2f, %.2f, %.2f" % tuple(math.degrees(a) for a in quat_out.to_euler()))
+print("(%.2f, %.2f, %.2f), %.2f" % (quat_out.axis[:] +
+                                    (math.degrees(quat_out.angle), )))
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index 798491b4710..82e69965840 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -106,7 +106,7 @@ There are also methods to access the current :class:`bge.types.KX_Scene`
 Matricies as used by the game engine are **row major**
 ``matrix[row][col] = float``
 
-:class:`bge.types.KX_Camera` has some examples using matricies.
+:class:`bge.types.KX_Camera` has some examples using matrices.
 
 *********
 Variables
diff --git a/doc/python_api/rst/bgl.rst b/doc/python_api/rst/bgl.rst
index 61400351d16..8fe765836a1 100644
--- a/doc/python_api/rst/bgl.rst
+++ b/doc/python_api/rst/bgl.rst
@@ -20,7 +20,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources.
    See :class:`Image.gl_load` and :class:`Image.gl_load`,
    for example.
    `OpenGL.org <http://www.opengl.org>`_
-   `NeHe GameDev <nehe.gamedev.net>`_
+   `NeHe GameDev <http://nehe.gamedev.net>`_
 
 
 .. function:: glAccum(op, value):
diff --git a/doc/python_api/rst/gpu.rst b/doc/python_api/rst/gpu.rst
index 72a5dc2f5d3..2ca7fdda9d5 100644
--- a/doc/python_api/rst/gpu.rst
+++ b/doc/python_api/rst/gpu.rst
@@ -1,7 +1,10 @@
-
 GPU functions (gpu)
 ===================
 
+.. module:: gpu
+
+This module provides access to materials GLSL shaders.
+
 *****
 Intro
 *****
@@ -16,7 +19,6 @@ and in the game engine.
     are are closely related to Blender's internal GLSL code and may change if the GLSL code 
     is modified (e.g. new uniform type). 
 
-.. module:: gpu
 
 *********
 Constants
diff --git a/doc/python_api/rst/info_best_practice.rst b/doc/python_api/rst/info_best_practice.rst
index 2fbc636613c..180a9fd1aa3 100644
--- a/doc/python_api/rst/info_best_practice.rst
+++ b/doc/python_api/rst/info_best_practice.rst
@@ -2,8 +2,9 @@
 Best Practice
 *************
 
+When writing you're own scripts python is great for new developers to pick up and become productive, but you can also pick up odd habits or at least write scripts that are not easy for others to understand.
 
-TODO: Intro text
+For you're own work this is of course fine, but if you want to collaborate with others or have you're work included with blender there are practices we encourage.
 
 
 Style Conventions
@@ -61,5 +62,233 @@ TODO: Thomas
 Script Efficiency
 =================
 
-TODO: Campbell
+List Manipulation (General Python Tips)
+---------------------------------------
 
+
+Searching for list items
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Python there are some handy list functions that save you having to search through the list.
+
+Even though you're not looping on the list data **python is**, so you need to be aware of functions that will slow down your script by searching the whole list.
+
+.. code-block:: python
+
+   my_list.count(list_item)
+   my_list.index(list_item)
+   my_list.remove(list_item)
+   if list_item in my_list: ...
+
+
+Modifying Lists
+^^^^^^^^^^^^^^^
+In python we can add and remove from a list, This is slower when the list length is modifier, especially at the start of the list, since all the data after the index of modification needs to be moved up or down 1 place.
+
+The most simple way to add onto the end of the list is to use ``my_list.append(list_item)`` or ``my_list.extend(some_list)`` and the fastest way to remove an item is ``my_list.pop()`` or ``del my_list[-1]``.
+
+To use an index you can use ``my_list.insert(index, list_item)`` or ``list.pop(index)`` for list removal, but these are slower.
+
+Sometimes its faster (but more memory hungry) to just rebuild the list.
+
+
+Say you want to remove all triangle faces in a list.
+
+Rather than...
+
+.. code-block:: python
+
+   faces = mesh.faces[:]  # make a list copy of the meshes faces
+   f_idx = len(faces)     # Loop backwards
+   while f_idx:           # while the value is not 0
+       f_idx -= 1
+
+       if len(faces[f_idx].vertices) == 3:
+           faces.pop(f_idx)  # remove the triangle
+
+
+It's faster to build a new list with list comprehension.
+
+.. code-block:: python
+
+   faces = [f for f in mesh.faces if len(f.vertices) != 3]
+
+
+Adding List Items
+^^^^^^^^^^^^^^^^^
+
+If you have a list that you want to add onto another list, rather then...
+
+.. code-block:: python
+
+   for l in some_list:
+       my_list.append(l)
+
+Use...
+
+.. code-block:: python
+
+   my_list.extend([a, b, c...])
+
+
+Note that insert can be used when needed, but it is slower than append especially when inserting at the start of a long list.
+
+This example shows a very sub-optimal way of making a reversed list.
+
+
+.. code-block:: python
+
+   reverse_list = []
+   for list_item in some_list:
+       reverse_list.insert(0, list_item)
+
+
+Removing List Items
+^^^^^^^^^^^^^^^^^^^
+
+Use ``my_list.pop(index)`` rather than ``my_list.remove(list_item)``
+
+This requires you to have the index of the list item but is faster since ``remove()`` will search the list.
+
+Here is an example of how to remove items in 1 loop, removing the last items first, which is faster (as explained above).
+
+.. code-block:: python
+
+   list_index = len(my_list)
+
+   while list_index:
+       list_index -= 1
+       if my_list[list_index].some_test_attribute == 1:
+           my_list.pop(list_index)
+
+
+This example shows a fast way of removing items, for use in cases were where you can alter the list order without breaking the scripts functionality. This works by swapping 2 list items, so the item you remove is always last.
+
+.. code-block:: python
+
+   pop_index = 5
+
+   # swap so the pop_index is last.
+   my_list[-1], my_list[pop_index] = my_list[pop_index], my_list[-1]
+
+   # remove last item (pop_index)
+   my_list.pop()
+
+
+When removing many items in a large list this can provide a good speedup.
+
+
+Avoid Copying Lists
+^^^^^^^^^^^^^^^^^^^
+
+When passing a list/dictionary to a function, it is faster to have the function modify the list rather then returning a new list so python dosn't have tp duplicate the list in memory.
+
+Functions that modify a list in-place are more efficient then functions that create new lists.
+
+
+This is generally slower so only use for functions when it makes sense not to modify the list in place.
+
+>>> my_list = some_list_func(my_list)
+
+
+This is generally faster since there is no re-assignment and no list duplication.
+
+>>> some_list_func(vec)
+
+
+Also note that passing a sliced list makes a copy of the list in python memory
+
+>>> foobar(my_list[:])
+
+If my_list was a large array containing 10000's of items, a copy could use a lot of extra memory.
+
+
+Writing Strings to a File (Python General)
+------------------------------------------
+
+Here are 3 ways of joining multiple strings into 1 string for writing
+
+This really applies to any area of your code that involves a lot of string joining.
+
+
+Pythons string addition, *don't use if you can help it, especially when writing data in a loop.*
+
+>>> file.write(str1 + " " + str2 + " " + str3 + "\n")
+
+
+String formatting. Use this when you're writing string data from floats and int's
+
+>>> file.write("%s %s %s\n" % (str1, str2, str3))
+
+
+Pythons string joining function. To join a list of strings
+
+>>> file.write(" ".join([str1, str2, str3, "\n"]))
+
+
+join is fastest on many strings, string formatting is quite fast too (better for converting data types). String arithmetic is slowest.
+
+
+Parsing Strings (Import/Exporting)
+----------------------------------
+
+Since many file formats are ASCII, the way you parse/export strings can make a large difference in how fast your script runs.
+
+When importing strings to make into blender there are a few ways to parse the string.
+
+Parsing Numbers
+^^^^^^^^^^^^^^^
+
+Use ``float(string)`` rather than ``eval(string)``, if you know the value will be an int then ``int(string)``,  float() will work for an int too but its faster to read ints with int().
+
+Checking String Start/End
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your checking the start of a string for a keyword, rather than...
+
+>>> if line[0:5] == "vert ": ...
+
+Use...
+
+>>> if line.startswith("vert "):
+
+Using ``startswith()`` is slightly faster (approx 5%) and also avoids a possible error with the slice length not matching the string length.
+
+my_string.endswith("foo_bar") can be used for line endings too.
+
+if your unsure whether the text is upper or lower case use lower or upper string function.
+
+>>> if line.lower().startswith("vert ")
+
+
+Use try/except Sparingly
+------------------------
+
+The **try** statement useful to save time writing error checking code.
+
+However **try** is significantly slower then an **if** since an exception has to be set each time, so avoid using **try** in areas of your code that execute in a loop and runs many times.
+
+There are cases where using **try** is faster than checking weather the condition will raise an error, so it is worth experimenting.
+
+
+Value Comparison
+----------------
+
+Python has two ways to compare values ``a == b`` and ``a is b``, The difference is that ``==`` may run the objects comparison function ``__cmp__()`` where as ``is`` compares identity, that both variables reference the same item in memory. 
+
+In cases where you know you are checking for the same value which is referenced from multiple places, ``is`` is faster.
+
+
+Time You're Code
+----------------
+
+While developing a script its good to time it to be aware of any changes in performance, this can be done simply.
+
+.. code-block:: python
+
+   import time
+   time_start = time.time()
+
+   # do something...
+
+   print("My Script Finished: %.4f sec" % time.time() - time_start)
diff --git a/doc/python_api/rst/info_gotcha.rst b/doc/python_api/rst/info_gotcha.rst
index e7903dcf96a..b17debbb15c 100644
--- a/doc/python_api/rst/info_gotcha.rst
+++ b/doc/python_api/rst/info_gotcha.rst
@@ -223,6 +223,26 @@ While writing scripts that deal with armatures you may find you have to switch b
 This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, however for operator access you may still need to enter pose mode.
 
 
+Relative File Paths
+===================
+
+Blenders relative file paths are not compatible with standard python modules such as ``sys`` and ``os``.
+
+Built in python functions don't understand blenders ``//`` prefix which denotes the blend file path.
+
+A common case where you would run into this problem is when exporting a material with assosiated image paths.
+
+>>> bpy.path.abspath(image.filepath)
+
+
+When using blender data from linked libraries there is an unfortunate complication since the path will be relative to the library rather then the open blend file. When the data block may be from an external blend file pass the library argument from the `bpy.types.ID`.
+
+>>> bpy.path.abspath(image.filepath, library=image.library)
+
+
+These returns the absolute path which can be used with native python modules.
+
+
 Unicode Problems
 ================
 
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index c3f8675a30e..eb19b232b2b 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -83,6 +83,7 @@ else:
         "aud",
         "bgl",
         "blf",
+        "gpu",
         "mathutils",
         "mathutils.geometry",
         "Freestyle",
@@ -1050,7 +1051,9 @@ def rna2sphinx(BASEPATH):
         fw("html_theme = 'blender-org'\n")
         fw("html_theme_path = ['../']\n")
 
-    fw("html_favicon = 'favicon.ico'\n")
+        # copied with the theme, exclude else we get an error [#28873]
+        fw("html_favicon = 'favicon.ico'\n")
+
     # not helpful since the source us generated, adds to upload size.
     fw("html_copy_source = False\n")
     fw("\n")
@@ -1130,6 +1133,8 @@ def rna2sphinx(BASEPATH):
         fw("   bgl.rst\n\n")
     if "blf" not in EXCLUDE_MODULES:
         fw("   blf.rst\n\n")
+    if "gpu" not in EXCLUDE_MODULES:
+        fw("   gpu.rst\n\n")
     if "aud" not in EXCLUDE_MODULES:
         fw("   aud.rst\n\n")
     if "bpy_extras" not in EXCLUDE_MODULES:
@@ -1274,6 +1279,13 @@ def rna2sphinx(BASEPATH):
         import shutil
         shutil.copy2(os.path.join(BASEPATH, "..", "rst", "bgl.rst"), BASEPATH)
 
+    if "gpu" not in EXCLUDE_MODULES:
+        #import gpu as module
+        #pymodule2sphinx(BASEPATH, "gpu", module, "GPU Shader Module")
+        #del module
+        import shutil
+        shutil.copy2(os.path.join(BASEPATH, "..", "rst", "gpu.rst"), BASEPATH)
+
     if "aud" not in EXCLUDE_MODULES:
         import aud as module
         pymodule2sphinx(BASEPATH, "aud", module, "Audio System")