Port Python updates from Tuhopuu2:

getType/setType to action/sound actuator (sgefant)
Use a more generic python -> math conversion.

9 files changed, 115 insertions, 28 deletions

diff --git a/source/gameengine/PyDoc/BL_ActionActuator.py b/source/gameengine/PyDoc/BL_ActionActuator.py
index ba6068055ed..41f41080c31 100644
--- a/source/gameengine/PyDoc/BL_ActionActuator.py
+++ b/source/gameengine/PyDoc/BL_ActionActuator.py
@@ -79,6 +79,22 @@ class BL_ActionActuator(SCA_IActuator):
 		@type blendtime: float
 		"""
 
+	def setType(mode):
+		"""
+		Sets the operation mode of the actuator
+
+		@param mode: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+		@type mode: integer
+		"""
+
+	def getType():
+		"""
+		Returns the operation mode of the actuator
+	    
+		@rtype: integer
+		@return: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+		"""
+	
 	def getAction():
 		"""
 		getAction() returns the name of the action associated with this actuator.
diff --git a/source/gameengine/PyDoc/GameLogic.py b/source/gameengine/PyDoc/GameLogic.py
index d4fccc7c3a0..630b2ae97c1 100644
--- a/source/gameengine/PyDoc/GameLogic.py
+++ b/source/gameengine/PyDoc/GameLogic.py
@@ -8,7 +8,9 @@ Documentation for the GameLogic Module.
 		- L{GameKeys}
 		- L{Rasterizer}
 	
-	All the other modules are accessibly through the methods in GameLogic.
+	All the other modules are accessible through the methods in GameLogic.
+	
+	See L{WhatsNew} for updates, changes and new functionality in the Game Engine Python API.
 	
 	Examples::
 		# To get a controller:
@@ -120,6 +122,20 @@ Documentation for the GameLogic Module.
 @var KX_RANDOMACT_FLOAT_NORMAL:		See L{SCA_RandomActuator}
 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL:		See L{SCA_RandomActuator}
 
+@group Action Actuator: KX_ACTIONACT_PLAY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND, KX_ACTIONACT_PROPERTY
+@var KX_ACTIONACT_PLAY:	    See L{BL_ActionActuator}
+@var KX_ACTIONACT_FLIPPER:  See L{BL_ActionActuator}
+@var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
+@var KX_ACTIONACT_LOOPEND:  See L{BL_ActionActuator}
+@var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
+
+@group Sound Actuator: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
+@var KX_SOUNDACT_PLAYSTOP:		    See L{KX_SoundActuator}
+@var KX_SOUNDACT_PLAYEND:		    See L{KX_SoundActuator}
+@var KKX_SOUNDACT_LOOPSTOP:		    See L{KX_SoundActuator}
+@var KX_SOUNDACT_LOOPEND:		    See L{KX_SoundActuator}
+@var KX_SOUNDACT_LOOPBIDIRECTIONAL:	    See L{KX_SoundActuator}
+@var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP:    See L{KX_SoundActuator}
 """
 
 
diff --git a/source/gameengine/PyDoc/KX_GameObject.py b/source/gameengine/PyDoc/KX_GameObject.py
index dd9e4b0bb23..a19e36d6dd0 100644
--- a/source/gameengine/PyDoc/KX_GameObject.py
+++ b/source/gameengine/PyDoc/KX_GameObject.py
@@ -7,10 +7,14 @@ class KX_GameObject:
 	
 	Properties assigned to game objects are accessible as attributes of this class.
 	
-	@ivar mass: The object's mass (provided the object has a physics controller). float. read only
+	@ivar name: The object's name.
+	@type name: string.
+	@ivar mass: The object's mass (provided the object has a physics controller). Read only.
+	@type mass: float
 	@ivar parent: The object's parent object. (Read only)
 	@type parent: L{KX_GameObject}
-	@ivar visible: visibility flag. boolean.
+	@ivar visible: visibility flag.
+	@type visible: boolean
 	@ivar position: The object's position. 
 	@type position: list [x, y, z]
 	@ivar orientation: The object's orientation. 3x3 Matrix.  
diff --git a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
index eef08a3fd56..ef216aed55c 100644
--- a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
+++ b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
@@ -6,22 +6,24 @@ class KX_SCA_AddObjectActuator(SCA_IActuator):
 	"""
 	Edit Object Actuator (in Add Object Mode)
 	
-	@warning: Add Object actuators will be ignored if at game start, the linked object doesn't exist
+	@warning: An Add Object actuator will be ignored if at game start, the linked object doesn't exist
 		  (or is empty) or the linked object is in an active layer.
 		  
 		  This will genereate a warning in the console:
 		  
 		  C{ERROR: GameObject I{OBName} has a AddObjectActuator I{ActuatorName} without object (in 'nonactive' layer)}
 	"""
-	def setObject(name):
+	def setObject(obj):
 		"""
-		Sets the name of the game object to add.
+		Sets the game object to add.
 		
-		A copy of the named object will be added to the scene.
+		A copy of the object will be added to the scene.
 		
-		If the named object does not exist, this function is ignored.
+		If the object does not exist, this function is ignored.
 		
-		@type name: string
+		obj can either be a L{KX_GameObject} or the name of an object.
+		
+		@type obj: L{KX_GameObject} or string
 		"""
 	def getObject():
 		"""
diff --git a/source/gameengine/PyDoc/KX_SceneActuator.py b/source/gameengine/PyDoc/KX_SceneActuator.py
index e0eae7a5526..eba899bd322 100644
--- a/source/gameengine/PyDoc/KX_SceneActuator.py
+++ b/source/gameengine/PyDoc/KX_SceneActuator.py
@@ -27,9 +27,11 @@ class KX_SceneActuator(SCA_IActuator):
 		"""
 	def setCamera(camera):
 		"""
-		Sets the name of the camera to change to.
+		Sets the camera to change to.
 		
-		@type camera: string
+		Camera can be either a L{KX_Camera} or the name of the camera.
+		
+		@type camera: L{KX_Camera} or string
 		"""
 	def getUseRestart():
 		"""
diff --git a/source/gameengine/PyDoc/KX_SoundActuator.py b/source/gameengine/PyDoc/KX_SoundActuator.py
index 6fbdca8991e..072af5b816c 100644
--- a/source/gameengine/PyDoc/KX_SoundActuator.py
+++ b/source/gameengine/PyDoc/KX_SoundActuator.py
@@ -127,3 +127,19 @@ class KX_SoundActuator(SCA_IActuator):
 			| o21, o22, o23 |
 			| o31, o32, o33 |
 		"""
+	
+	def setType(mode):
+		"""
+		Sets the operation mode of the actuator.
+		
+		@param mode: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
+		@type mode: integer
+		"""
+
+	def getType():
+		"""
+		Returns the operation mode of the actuator.
+		
+		@rtype: integer
+		@return:  KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
+		"""
diff --git a/source/gameengine/PyDoc/KX_TrackToActuator.py b/source/gameengine/PyDoc/KX_TrackToActuator.py
index f0333d62608..8b93a82dada 100644
--- a/source/gameengine/PyDoc/KX_TrackToActuator.py
+++ b/source/gameengine/PyDoc/KX_TrackToActuator.py
@@ -18,8 +18,8 @@ class KX_TrackToActuator(SCA_IActuator):
 		"""
 		Sets the object to track.
 		
-		@type object: string
-		@param object: the name of the object to track.
+		@type object: L{KX_GameObject} or string
+		@param object: Either a reference to a game object or the name of the object to track.
 		"""
 	def getObject():
 		"""
diff --git a/source/gameengine/PyDoc/KX_VertexProxy.py b/source/gameengine/PyDoc/KX_VertexProxy.py
index 2802829033f..8dc2752c037 100644
--- a/source/gameengine/PyDoc/KX_VertexProxy.py
+++ b/source/gameengine/PyDoc/KX_VertexProxy.py
@@ -76,20 +76,20 @@ class KX_VertexProxy:
 		"""
 		Gets the colour of this vertex.
 		
-		Example:
-		# Big endian:
-		col = v.getRGBA()
-		red = (col & 0xff000000) >> 24
-		green = (col & 0xff0000) >> 16
-		blue = (col & 0xff00) >> 8
-		alpha = (col & 0xff)
+		The colour is represented as four bytes packed into an integer value.  The colour is 
+		packed as RGBA.
 		
-		# Little endian:
-		col = v.getRGBA()
-		alpha = (col & 0xff000000) >> 24
-		blue = (col & 0xff0000) >> 16
-		green = (col & 0xff00) >> 8
-		red = (col & 0xff)
+		Since Python offers no way to get each byte without shifting, you must use the struct module to
+		access colour in an machine independent way.
+		
+		Because of this, it is suggested you use the r, g, b and a attributes or the colour attribute instead.
+		
+		Example::
+			import struct;
+			col = struct.unpack('4B', struct.pack('I', v.getRGBA()))
+			# col = (r, g, b, a)
+			# black = (  0,   0,   0, 255)
+			# white = (255, 255, 255, 255)
 		
 		@rtype: integer
 		@return: packed colour. 4 byte integer with one byte per colour channel in RGBA format.
@@ -98,8 +98,20 @@ class KX_VertexProxy:
 		"""
 		Sets the colour of this vertex.
 		
-		@type col: integer
-		@param col: the new colour of this vertex in packed format.
+		See getRGBA() for the format of col, and its relevant problems.  Use the r, g, b and a attributes
+		or the colour attribute instead.
+		
+		setRGBA() also accepts a four component list as argument col.  The list represents the colour as [r, g, b, a]
+		with black = [0.0, 0.0, 0.0, 1.0] and white = [1.0, 1.0, 1.0, 1.0]
+		
+		Example::
+			v.setRGBA(0xff0000ff) # Red
+			v.setRGBA(0xff00ff00) # Green on little endian, transparent purple on big endian
+			v.setRGBA([1.0, 0.0, 0.0, 1.0]) # Red
+			v.setRGBA([0.0, 1.0, 0.0, 1.0]) # Green on all platforms.
+		
+		@type col: integer or list [r, g, b, a]
+		@param col: the new colour of this vertex in packed RGBA format.
 		"""
 	def getNormal():
 		"""
diff --git a/source/gameengine/PyDoc/WhatsNew.py b/source/gameengine/PyDoc/WhatsNew.py
new file mode 100644
index 00000000000..5e16f08375f
--- /dev/null
+++ b/source/gameengine/PyDoc/WhatsNew.py
@@ -0,0 +1,19 @@
+# $Id$
+"""
+New Python Functionality in this Version of Blender
+===================================================
+
+This document lists what has been changed in the Game Engine Python API.
+
+Blender 2.34
+------------
+
+	- Added getType() and setType() to L{BL_ActionActuator} and L{KX_SoundActuator} (sgefant)
+	- New Scene module: L{KX_Scene}
+	- New Camera module: L{KX_Camera}
+	- New Light module: L{KX_Light}
+	- Added attributes to L{KX_GameObject}, L{KX_VertexProxy}
+	- L{KX_SCA_AddObjectActuator}.setObject(), L{KX_TrackToActuator}.setObject() and 
+	  L{KX_SceneActuator}.setCamera() now accept L{KX_GameObject}s as parameters
+
+"""