BPython:

- Blender.Window: added function GetPerspMatrix() (Tom Musgrave's patch, thanks);
- added Chris Want's patch to tell argc, argv to the Python interpreter (thanks, Hos);
- Blender.Image: added image.glFree() to free textures bound by the recently added
  image.glLoad() (both suggested by Campbell Barton -- thanks, with these Blender can
  be used to load textures for scripts);
- Blender.Sound: removed for now at least a few get/set methods of vars that can't be
  accessed via interface;
- renamed Get/makeActive to Get/setCurrent in Blender.World (actually added alias for
  now), same in Blender.Sound: renamed makeActive to setCurrent.  Stephen Swaney
  pointed this some weeks ago, we should stick to one naming convention.
- added documentation for Sound and Window.Theme modules and the other added
  functions, made other small updates.
- Blender.Object: made 'worldspace' become the default output of .getMatrix and .mat/.matrix:
  after reading a discussion on blender.org's Python forum where eeshlo mentioned the
  pre 2.34 default was worldspace, I took a better look at Blender's relevant code,
  confirmed, talked to Theeth about this and as he suggested am changing the default
  back to 'worldspace'.

8 files changed, 362 insertions, 20 deletions

diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py
index 94f583211fc..8f684c79144 100644
--- a/source/blender/python/api2_2x/doc/API_intro.py
+++ b/source/blender/python/api2_2x/doc/API_intro.py
@@ -34,11 +34,13 @@ The Blender Python API Reference
   - L{Scene} (*)
      - L{Radio}
      - L{Render}
+  - L{Sound} (new)
   - L{Text}
   - L{Texture}
   - L{Types}
-  - L{Window}
-  - L{World}
+  - L{Window} (*)
+     - L{Theme} (new)
+  - L{World} (*)
   - L{sys<Sys>}
 
  (*) - marks updated.
diff --git a/source/blender/python/api2_2x/doc/BGL.py b/source/blender/python/api2_2x/doc/BGL.py
index cbb8b455b19..6c20e4ec7b4 100644
--- a/source/blender/python/api2_2x/doc/BGL.py
+++ b/source/blender/python/api2_2x/doc/BGL.py
@@ -74,6 +74,9 @@ Example::
   #
   Draw.Register(show_win, ev, None)      # start the main loop
 
+@note: you can use the L{Image} module and L{Image.Image} bpy object to load
+    and set textures.  See L{Image.Image.glLoad} and L{Image.Image.glFree},
+    for example.
 @see: U{www.opengl.org}
 @see: U{nehe.gamedev.net}
 """
diff --git a/source/blender/python/api2_2x/doc/Image.py b/source/blender/python/api2_2x/doc/Image.py
index f09a5fbcc69..df4b5c6a65c 100644
--- a/source/blender/python/api2_2x/doc/Image.py
+++ b/source/blender/python/api2_2x/doc/Image.py
@@ -6,7 +6,7 @@ The Blender.Image submodule.
 Image
 =====
 
-B{New}: L{Image.reload}, L{Image.getBindCode}.
+B{New}: L{Image.glLoad}, L{Image.glFree}.
 
 This module provides access to B{Image} objects in Blender.
 
@@ -110,8 +110,8 @@ class Image:
 
   def getBindCode():
     """
-    Get the Image's bindcode.  This is for texture loading using BGL calls,
-    see for example L{BGL.glBindTexture}.
+    Get the Image's bindcode.  This is for texture loading using BGL calls.
+    See, for example, L{BGL.glBindTexture} and L{glLoad}.
     @rtype: int
     """
 
@@ -125,6 +125,29 @@ class Image:
     @returns: None
     """
 
+  def glLoad():
+    """
+    Load this image's data into OpenGL texture memory, if it is not already
+    loaded (image.bindcode is 0 if it is not loaded yet).
+    @note: Usually you don't need to call this method.  It is only necessary
+       if you want to draw textured objects in the Scripts window and the
+       image's bind code is zero at that moment, otherwise Blender itself can
+       take care of binding / unbinding textures.  Calling this method for an
+       image with nonzero bind code simply returns the image's bind code value
+       (see L{getBindCode}).
+    @rtype: int
+    @returns: the texture's bind code.
+    """
+
+  def glFree():
+    """
+    Delete this image's data from OpenGL texture memory, only (the image itself
+    is not removed from Blender's memory).  Internally, glDeleteTextures (see
+    L{BGL.glDeleteTextures}) is used, but this method also updates Blender's
+    Image object so that its bind code is set to 0.  See also L{Image.glLoad},
+    L{Image.getBindCode}.
+    """
+
   def setName(name):
     """
     Set the name of this Image object.
diff --git a/source/blender/python/api2_2x/doc/Object.py b/source/blender/python/api2_2x/doc/Object.py
index 07c674b9dbe..c2d1db093ca 100644
--- a/source/blender/python/api2_2x/doc/Object.py
+++ b/source/blender/python/api2_2x/doc/Object.py
@@ -3,7 +3,8 @@
 """
 The Blender.Object submodule
 
-B{New}: 'oldlocal' parameter in L{Object.Object.getMatrix}. 
+B{New}: 'old_worldspace' parameter in L{Object.Object.getMatrix}, which now
+defaults to 'worldspace'. 
 
 Object
 ======
@@ -146,7 +147,7 @@ class Object:
     @cvar data: The data of the object. (Read-only)
     @cvar ipo: The ipo data associated with the object. (Read-only)
     @cvar mat: The matrix of the object relative to its parent. (Read-only)
-    @cvar matrix: The matrix of the object relative to its parent. (Read-only)
+    @cvar matrix: The matrix of the object in world space. (Read-only)
     @cvar matrixLocal: The matrix of the object relative to its parent. (Read-only)
     @cvar matrixWorld: The matrix of the object in world space. (Read-only)
     @cvar colbits: The Material usage mask. A set bit #n means: the Material
@@ -287,17 +288,17 @@ class Object:
     @return: list of Material Objects assigned to the object.
     """
 
-  def getMatrix(space = 'localspace'):
+  def getMatrix(space = 'worldspace'):
     """
     Returns the object matrix.
     @type space: string
     @param space: The desired matrix:
-      - localspace (default): relative to the object's parent;
-      - worldspace: absolute, taking vertex parents, tracking and ipo's into
-          account;
-      - oldlocal: old behavior, prior to Blender 2.34, where eventual changes
-          made by the script itself were not taken into account until the
-          script finished executing.
+      - worldspace (default): absolute, taking vertex parents, tracking and
+          ipo's into account;
+      - localspace: relative to the object's parent;
+      - old_worldspace: old behavior, prior to Blender 2.34, where eventual
+          changes made by the script itself were not taken into account until
+          a redraw happened, either called by the script or upon its exit.
     Returns the object matrix.
     @rtype: Py_Matrix
     @return: a python 4x4 matrix object
diff --git a/source/blender/python/api2_2x/doc/Sound.py b/source/blender/python/api2_2x/doc/Sound.py
new file mode 100644
index 00000000000..6cc72f471cf
--- /dev/null
+++ b/source/blender/python/api2_2x/doc/Sound.py
@@ -0,0 +1,112 @@
+# Blender.Sound module and the Sound PyType object
+
+"""
+The Blender.Sound submodule.
+
+Sound
+=====
+
+This module provides access to B{Sound} objects in Blender.
+
+Example::
+  import Blender
+  from Blender import Sound
+  #
+  sound = Sound.Load("/path/to/my/sound.wav")    # load a sound file
+  print "Sound from", sound.getFilename(),
+  print "loaded to obj", sound.getName())
+  print "All Sounds available now:", Sound.Get()
+"""
+
+def Load (filename):
+  """
+  Load the sound called 'filename' into a Sound object.
+  @type filename: string
+  @param filename: The full path to the sound file.
+  @rtype:  Blender Sound
+  @return: A Blender Sound object with the data from I{filename}.
+  """
+
+def Get (name = None):
+  """
+  Get the Sound object(s) from Blender.
+  @type name: string
+  @param name: The name of the Sound object.
+  @rtype: Blender Sound or a list of Blender Sounds
+  @return: It depends on the I{name} parameter:
+      - (name): The Sound object called I{name}, None if not found;
+      - (): A list with all Sound objects in the current scene.
+  """
+
+
+class Sound:
+  """
+  The Sound object
+  ================
+    This object gives access to Sounds in Blender.
+  @cvar name: The name of this Sound object.
+  @cvar filename: The filename (path) to the sound file loaded into this Sound
+     object.
+  """
+
+  def getName():
+    """
+    Get the name of this Sound object.
+    @rtype: string
+    """
+
+  def getFilename():
+    """
+    Get the filename of the sound file loaded into this Sound object.
+    @rtype: string
+    """
+
+  def play():
+    """
+    Play this sound.
+    """
+
+  def setCurrent():
+    """
+    Make this the active sound in the sound buttons window (also redraws).
+    """
+
+  def getVolume():
+    """
+    Get this sound's volume.
+    rtype: float
+    """
+
+  def setVolume(f):
+    """
+    Set this sound's volume.
+    @type f: float
+    @param f: the new volume value in the range [0.0, 1.0].
+    """
+
+  def getAttenuation():
+    """
+    Get this sound's attenuation value.
+    rtype: float
+    """
+
+  def setAttenuation(f):
+    """
+    Set this sound's attenuation.
+    @type f: float
+    @param f: the new attenuation value in the range [0.0, 5.0].
+    """
+
+  def getPitch():
+    """
+    Get this sound's pitch value.
+    rtype: float
+    """
+
+  def setPitch(f):
+    """
+    Set this sound's pitch.
+    @type f: float
+    @param f: the new pitch value in the range [-12.0, 12.0].    
+    """
+
diff --git a/source/blender/python/api2_2x/doc/Theme.py b/source/blender/python/api2_2x/doc/Theme.py
new file mode 100644
index 00000000000..facfee068c2
--- /dev/null
+++ b/source/blender/python/api2_2x/doc/Theme.py
@@ -0,0 +1,188 @@
+# Blender.Window.Theme submodule and the Theme PyType object
+
+"""
+The Blender.Window.Theme submodule.
+
+Theme
+=====
+
+This module provides access to B{Theme} objects in Blender.
+
+Example::
+  # this is a simplified version of the save_theme.py script
+  # shipped with Blender:
+  import Blender
+  from Blender.Window import Theme, FileSelector
+
+  theme = Theme.Get()[0] # get current theme
+
+  def write_theme(filename):
+    "Write the current theme as a bpython script"
+
+    f = file(filename, "w")
+
+    f.write("import Blender")
+    f.write("from Blender.Window import Theme")
+    f.write("theme = Theme.New('%s')" % theme.name)
+
+    for tsp in theme.get(): # write each theme space
+      command = "\\n%s = theme.get('%s')" % (tsp, tsp)
+      f.write(command + "\\n")
+      exec(command)
+      exec("vars = dir(%s)" % tsp)
+      vars.remove('theme')
+
+      for var in vars: # write each variable from each theme space
+        v = "%s.%s" % (tsp, var)
+        exec("value = %s" % v)
+        f.write("%s = %s\\n" % (v, value))
+
+    f.write('\\nBlender.Redraw(-1)') # redraw to update the screen
+    f.close()
+
+  FileSelector(write_theme, "Save Current Theme", default_fname)
+"""
+
+def New (name = "New Theme", theme = '<default>'):
+  """
+  Create a new Theme object.
+  @type name: string
+  @param name: The name of the new theme.
+  @type theme: Blender Theme
+  @param theme: a base theme to copy all data from.  It defaults to the current
+      one.
+  @rtype:  Blender Theme
+  @return: A new Blender Theme object.
+  """
+
+def Get (name = None):
+  """
+  Get the Theme object(s) from Blender.
+  @type name: string
+  @param name: The name of the Theme object.
+  @rtype: Blender Theme or a list of Blender Themes
+  @return: It depends on the I{name} parameter:
+      - (name): The Theme object called I{name}, None if not found;
+      - (): A list with all Theme objects currently in Blender.
+  """
+
+
+class Theme:
+  """
+  The Theme object
+  ================
+    This object gives access to Themes in Blender.  Each Theme object is
+    composed of one UI (Use Interface) theme and many Space themes
+    (3d view, Text Editor, Buttons window, etc).
+  @cvar name: The name of this Theme object.
+  """
+
+  def getName():
+    """
+    Get the name of this Theme object.
+    @rtype: string
+    @return: the name of this Theme object.
+    """
+
+  def setName(s):
+    """
+    Rename this theme.
+    @type s: string
+    @param s: the new name.
+    """
+
+  def get(t = None):
+    """
+    Get a space or the ui (sub)theme from this Theme.
+    @type t: string, int or None
+    @param t: the wanted sub-theme as either:
+        - int: -1 for UI or the types in L{Window.Types} for the others;
+        - string: use get() to know them (they are case insensitive);
+        - nothing: as written above, get() returns a list of names.
+    @rtype: Blender ThemeSpace or ThemeUI or list of sub-theme types as strings.
+    @return: It depends on the given parameter:
+      - (): a list with all available types, as strings;
+      - (type): the chosen sub-theme.
+    """
+
+  class ThemeUI:
+    """
+    The User Interface sub-theme
+    ============================
+      This can be accessed with theme.get(t), where t can be 'ui' or -1.
+      The available variables follow the internal (C coded) ThemeUI struct in
+      Blender.  Most of them represent rgba (red, green, blue, alpha) colors,
+      with each component in the range [0, 255].  There is more than one way to
+      access them.
+
+      Examples::
+        print outline.R
+        outline.r = 180 # it's case insensitive
+        outline[0] = 94 # 0 for red, 1 for green, ...
+        outline = [200, 200, 200, 255] # setting all components at once
+    @type theme: string
+    @cvar theme: the parent Theme for this object.
+    @cvar outline: theme rgba var.
+    @cvar neutral: theme rgba var.
+    @cvar action: theme rgba var.
+    @cvar setting: theme rgba var.
+    @cvar setting1: theme rgba var.
+    @cvar setting2: theme rgba var.
+    @cvar num: theme rgba var.
+    @cvar textfield: theme rgba var.
+    @cvar popup: theme rgba var.
+    @cvar text: theme rgba var.
+    @cvar text_hi: theme rgba var.
+    @cvar menu_back: theme rgba var.
+    @cvar menu_item: theme rgba var.
+    @cvar menu_hilite: theme rgba var.
+    @cvar menu_text: theme rgba var.
+    @cvar menu_text_hi: theme rgba var.
+    @type drawType: int
+    @cvar drawType: the draw type (minimal, rounded, etc) in the range [1, 4].
+    """
+
+  class ThemeSpace:
+    """
+    The Space sub-themes
+    ====================
+      There is a sub-theme for each space in Blender (except for the Scripts
+      window, but it will be added soon).  Please read the information about
+      L{Theme.ThemeUI}, since it is also relevant here.  In Blender,
+      all theme spaces share the same C structure.  For this reason, all of
+      them here share the same variables, event though some spaces only use
+      a few of them.  This lower-level access is acceptable because generally
+      users will prefer to use the interface to change single theme options
+      and only use scripting to save or restore themes.  But anyway, checking
+      the Themes tab in the User Preferences space in Blender and using the
+      bundled "Save current theme" script (or its simplified version written
+      on the top of this page) can help you finding out any specific info you
+      may need.
+    @type theme: string
+    @cvar theme: the parent Theme for this object.
+    @cvar back: theme rgba var.
+    @cvar text: theme rgba var.
+    @cvar text_hi: theme rgba var.
+    @cvar header: theme rgba var.
+    @cvar panel: theme rgba var.
+    @cvar shade1: theme rgba var.
+    @cvar shade2: theme rgba var.
+    @cvar hilite: theme rgba var.
+    @cvar grid: theme rgba var.
+    @cvar wire: theme rgba var.
+    @cvar select: theme rgba var.
+    @cvar active: theme rgba var.
+    @cvar transform: theme rgba var.
+    @cvar vertex: theme rgba var.
+    @cvar vertex_select: theme rgba var.
+    @cvar edge: theme rgba var.
+    @cvar edge_select: theme rgba var.
+    @cvar edge_seam: theme rgba var.
+    @cvar edge_facesel: theme rgba var.
+    @cvar face: theme rgba var.
+    @cvar face_select: theme rgba var.
+    @cvar normal: theme rgba var.
+    @type vertex_size: int
+    @cvar vertex_size: size of the vertices dots on screen in the range [1, 10].
+    """
+
diff --git a/source/blender/python/api2_2x/doc/Window.py b/source/blender/python/api2_2x/doc/Window.py
index 9cc17a26a2e..60f1396dbce 100644
--- a/source/blender/python/api2_2x/doc/Window.py
+++ b/source/blender/python/api2_2x/doc/Window.py
@@ -8,7 +8,7 @@ Window
 
 This module provides access to B{Window} functions in Blender.
 
-B{New}: many new functions related to screens and events.
+B{New}: L{GetPerspMatrix}.
 
 Example:
 --------
@@ -81,6 +81,12 @@ DrawProgressBar::
     - LSHIFT
     - RSHIFT
     - SHIFT
+
+@type MButs: readonly dictionary
+@var MButs: Mouse buttons.
+    - L: left mouse button
+    - M: middle mouse button
+    - R: right mouse button
 """
 
 def Redraw (spacetype = '<Types.VIEW3D>'):
@@ -201,6 +207,13 @@ def GetViewMatrix ():
   @return: the current matrix.
   """
 
+def GetPerspMatrix ():
+  """
+  Get the current 3d perspective matrix.
+  @rtype: 4x4 float matrix
+  @return: the current matrix.
+  """
+
 def EditMode(enable = -1, undo_msg = 'From script'):
   """
   Get and optionally set the current edit mode status: in or out.
@@ -358,7 +371,7 @@ def SetMouseCoords (coords):
 
 def GetMouseButtons ():
   """
-  Get the current mouse button state (compare with events from L{Draw}).
+  Get the current mouse button state (see / compare against L{MButs}).
   @rtype: int
   @return: an or'ed flag with the currently pressed buttons.
   """
diff --git a/source/blender/python/api2_2x/doc/World.py b/source/blender/python/api2_2x/doc/World.py
index a8d10ce7073..cd2edd922eb 100644
--- a/source/blender/python/api2_2x/doc/World.py
+++ b/source/blender/python/api2_2x/doc/World.py
@@ -3,7 +3,7 @@
 """
 The Blender.World submodule
 
-B{New}: scriptLink methods: L{World.getScriptLinks}, ...
+B{New}: L{GetCurrent}, L{World.setCurrent}.
 
 INTRODUCTION
 ============
@@ -44,7 +44,7 @@ def New (name):
   @type name: string
   @param name: World's name (optionnal).
   @rtype: Blender World
-  @return: The created World. If the "name" paraeter has not been provided, it will be automatically be set by blender.
+  @return: The created World. If the "name" parameter has not been provided, it will be automatically be set by blender.
   """
 
 def Get (name):
@@ -59,7 +59,7 @@ def Get (name):
   """
 
 
-def GetActive ():
+def GetCurrent ():
   """
   Get the active world of the scene.
   @rtype: Blender World or None
@@ -315,7 +315,7 @@ class World:
     @param event: "FrameChanged" or "Redraw".
     """
   
-  def makeActive ():
+  def setCurrent ():
     """
     Make this world active in the current scene.
     @rtype: PyNone