copy of docs from 2.4x for python modules that have been kept

source/blender/python/doc/epy/Geometry.py

@@ -0,0 +1,112 @@
+# Blender.Geometry module and its subtypes
+
+"""
+The Blender.Geometry submodule.
+
+Geometry
+========
+(when accessing it from the Game Engine use Geometry instead of Blender.Geometry)
+
+This new module provides access to a geometry function.
+"""
+
+def PolyFill(polylines):
+	"""
+	Takes a list of polylines and calculates triangles that would fill in the polylines.
+	Multiple lines can be used to make holes inside a polyline, or fill in 2 seperate lines at once.
+	@type polylines: List of lists containing vectors, each representing a closed polyline.
+	@rtype: list
+	@return: a list if tuples each a tuple of 3 ints representing a triangle indexing the points given.
+	@note: 2D Vectors will have an assumed Z axis of zero, 4D Vectors W axis is ignored.
+	@note: The order of points in a polyline effect the direction returned triangles face, reverse the order of a polyline to flip the normal of returned faces.
+
+	I{B{Example:}}
+
+	The example below creates 2 polylines and fills them in with faces, then makes a mesh in the current scene::
+		import Blender
+		Vector= Blender.Mathutils.Vector
+
+		# Outline of 5 points
+		polyline1= [Vector(-2.0, 1.0, 1.0), Vector(-1.0, 2.0, 1.0), Vector(1.0, 2.0, 1.0), Vector(1.0, -1.0, 1.0), Vector(-1.0, -1.0, 1.0)]
+		polyline2= [Vector(-1, 1, 1.0), Vector(0, 1, 1.0), Vector(0, 0, 1.0), Vector(-1.0, 0.0, 1.0)]
+		fill= Blender.Geometry.PolyFill([polyline1, polyline2])
+
+		# Make a new mesh and add the truangles into it
+		me= Blender.Mesh.New()
+		me.verts.extend(polyline1)
+		me.verts.extend(polyline2)
+		me.faces.extend(fill) # Add the faces, they reference the verts in polyline 1 and 2
+
+		scn = Blender.Scene.GetCurrent()
+		ob = scn.objects.new(me)
+		Blender.Redraw()
+	"""
+
+def LineIntersect2D(vec1, vec2, vec3, vec4):
+	"""
+	Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
+	@rtype: Vector
+	@return: a 2D Vector for the intersection or None where there is no intersection.
+	"""
+
+def ClosestPointOnLine(pt, vec1, vec2):
+	"""
+	Takes 2 lines vec1, vec2 for the 2 points of the first line and vec2, vec3 for the 2 points of the second line.
+	@rtype: tuple
+	@return: a tuple containing a vector and a float, the vector is the closest point on the line, the float is the position on the line, between 0 and 1 the point is on the line.
+	"""
+
+def PointInTriangle2D(pt, tri_pt1, tri_pt2, tri_pt3):
+	"""
+	Takes 4 vectors (one for the test point and 3 for the triangle)
+	This is a 2d function so only X and Y are used, Z and W will be ignored.
+	@rtype: int
+	@return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
+	"""
+
+def PointInQuad2D(pt, quad_pt1, quad_pt2, quad_pt3):
+	"""
+	Takes 5 vectors (one for the test point and 5 for the quad)
+	This is a 2d function so only X and Y are used, Z and W will be ignored.
+	@rtype: int
+	@return: 1 for a clockwise intersection, -1 for counter clockwise intersection, 0 when there is no intersection.
+	"""
+
+def BoxPack2D(boxlist):
+	"""
+	Takes a list of 2D boxes and packs them into a square.
+	Each box in boxlist must be a list of at least 4 items - [x,y,w,h], after running this script,
+	the X and Y values in each box will be moved to packed, non overlapping locations.
+	
+	Example::
+
+		# Make 500 random boxes, pack them and make a mesh from it
+		from Blender import Geometry, Scene, Mesh
+		import random
+		boxes = []
+		for i in xrange(500):
+			boxes.append( [0,0, random.random()+0.1, random.random()+0.1] )
+		boxsize = Geometry.BoxPack2D(boxes)
+		print 'BoxSize', boxsize
+		me = Mesh.New()
+		for x in boxes:
+			me.verts.extend([(x[0],x[1], 0), (x[0],x[1]+x[3], 0), (x[0]+x[2],x[1]+x[3], 0), (x[0]+x[2],x[1], 0) ])
+			v1= me.verts[-1]
+			v2= me.verts[-2]
+			v3= me.verts[-3]
+			v4= me.verts[-4]
+			me.faces.extend([(v1,v2,v3,v4)])
+		scn = Scene.GetCurrent()
+		scn.objects.new(me)
+	
+	@note: Each boxlist item can be longer then 4, the extra items are ignored and stay untouched.
+	@rtype: tuple
+	@return: a tuple pair - (width, height) of all the packed boxes.
+	"""
+def BezierInterp(vec_knot_1, vec_handle_1, vec_handle_2, vec_knot_2, resolution):
+	"""
+	Takes 4 vectors representing a bezier curve and returns a list of vector points.
+	@note: any vector size is supported, the largest dimension from the input will be used for all returned vectors/
+	@rtype: list
+	@return: a list of vectors the size of resolution including the start and end points (vec_knot_1 and vec_knot_2)
+	"""

source/blender/python/doc/epy/IDProp.py

@@ -0,0 +1,132 @@
+class IDGroup:
+	"""
+	The IDGroup Type
+	================
+	This type supports both iteration and the []
+	operator to get child ID properties.
+	
+	You can also add new properties using the [] operator.
+	For example::
+	
+		group['a float!'] = 0.0
+		group['an int!'] = 0
+		group['a string!'] = "hi!"
+		group['an array!'] = [0, 0, 1.0, 0]
+		
+		group['a subgroup!] = {"float": 0.0, "an int": 1.0, "an array": [1, 2],
+		  "another subgroup": {"a": 0.0, "str": "bleh"}}
+	
+	Note that for arrays, the array type defaults to int unless a float is found
+	while scanning the template list; if any floats are found, then the whole
+	array is float.  Note that double-precision floating point numbers are used for
+	python-created float ID properties and arrays (though the internal C api does 
+	support single-precision floats, and the python code will read them).
+	
+	You can also delete properties with the del operator.  For example:
+	
+	del group['property']
+	
+	To get the type of a property, use the type() operator, for example::
+	
+		if type(group['bleh']) == str: pass
+	
+	To tell if the property is a group or array type, import the Blender.Types module and test
+	against IDGroupType and IDArrayType, like so::
+	
+		from Blender.Types import IDGroupType, IDArrayType.
+	
+		if type(group['bleghr']) == IDGroupType:
+			(do something)
+	
+	@ivar name: The name of the property
+	@type name: string
+	"""
+	
+	def pop(item):
+		"""
+		Pop an item from the group property.
+		@type item: string
+		@param item: The item name.
+		@rtype: can be dict, list, int, float or string.
+		@return: The removed property.	
+		"""
+		
+	def update(updatedict):
+		"""
+		Updates items in the dict, similar to normal python
+		dictionary method .update().
+		@type updatedict: dict
+		@param updatedict: A dict of simple types to derive updated/new IDProperties from.
+		@rtype: None
+		@return: None
+		"""
+	
+	def keys():
+		"""
+		Returns a list of the keys in this property group.
+		@rtype: list of strings.
+		@return: a list of the keys in this property group.	
+		"""
+	
+	def values():
+		"""
+		Returns a list of the values in this property group.
+		
+		Note that unless a value is itself a property group or an array, you 
+		cannot change it by changing the values in this list, you must change them
+		in the parent property group.
+		
+		For example,
+		
+		group['some_property'] = new_value
+		
+		. . .is correct, while,
+		
+		values = group.values()
+		values[0] = new_value
+		
+		. . .is wrong.
+		
+		@rtype: list of strings.
+		@return: a list of the values in this property group.
+		"""
+	
+	def iteritems():
+		"""
+		Implements the python dictionary iteritmes method.
+		
+		For example::
+
+			for k, v in group.iteritems():
+				print "Property name: " + k
+				print "Property value: " + str(v)
+			
+		@rtype: an iterator that spits out items of the form [key, value]
+		@return: an iterator.	
+		"""
+	
+	def convert_to_pyobject():
+		"""
+		Converts the entire property group to a purely python form.
+		
+		@rtype: dict
+		@return: A python dictionary representing the property group
+		"""
+		
+class IDArray:
+	"""
+	The IDArray Type
+	================
+	
+	@ivar type: returns the type of the array, can be either IDP_Int or IDP_Float
+	"""
+	
+	def __getitem__(index):
+		pass
+	
+	def __setitem__(index, value):
+		pass
+	
+	def __len__():
+		pass
+	

source/blender/python/doc/epy/Mathutils.py

@@ -0,0 +1,941 @@
+# Blender.Mathutils module and its subtypes
+
+"""
+The Blender.Mathutils submodule.
+
+Mathutils
+=========
+(when accessing it from the Game Engine use Mathutils instead of Blender.Mathutils)
+
+This module provides access to matrices, eulers, quaternions and vectors.
+
+Example::
+  import Blender
+  from Blender import Mathutils
+  from Blender.Mathutils import *
+
+  vec = Vector([1,2,3])
+  mat = RotationMatrix(90, 4, 'x')
+  matT = TranslationMatrix(vec)
+
+  matTotal = mat * matT
+  matTotal.invert()
+
+  mat3 = matTotal.rotationPart
+  quat1 = mat.toQuat()
+  quat2 = mat3.toQuat()
+
+  angle = DifferenceQuats(quat1, quat2)
+  print angle  
+  
+@group Deprecated: CopyMat, CopyVec, CopyQuat, CopyEuler, RotateEuler, MatMultVec, VecMultMat, CrossVecs, DotVecs, CrossQuats, DotQuats
+"""
+
+def Rand (low=0.0, high = 1.0):
+  """
+  Return a random number within a range.
+  low and high represent are optional parameters which represent the range
+  from which the random number must return its result.
+  @type low: float
+  @param low: The lower range.
+  @type high: float
+  @param high: The upper range.
+  """
+
+def Intersect(vec1, vec2, vec3, ray, orig, clip=1):
+  """
+  Return the intersection between a ray and a triangle, if possible, return None otherwise.
+  @type vec1: Vector object.
+  @param vec1: A 3d vector, one corner of the triangle.
+  @type vec2: Vector object.
+  @param vec2: A 3d vector, one corner of the triangle.
+  @type vec3: Vector object.
+  @param vec3: A 3d vector, one corner of the triangle.
+  @type ray: Vector object.
+  @param ray: A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction.
+  @type orig: Vector object.
+  @param orig: A 3d vector, the origin of the ray.
+  @type clip: integer
+  @param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.
+  @rtype: Vector object
+  @return: The intersection between a ray and a triangle, if possible, None otherwise.
+  """
+
+def TriangleArea(vec1, vec2, vec3):
+  """
+  Return the area size of the 2D or 3D triangle defined.
+  @type vec1: Vector object.
+  @param vec1: A 2d or 3d vector, one corner of the triangle.
+  @type vec2: Vector object.
+  @param vec2: A 2d or 3d vector, one corner of the triangle.
+  @type vec3: Vector object.
+  @param vec3: A 2d or 3d vector, one corner of the triangle.
+  @rtype: float
+  @return: The area size of the 2D or 3D triangle defined.
+  """
+
+def TriangleNormal(vec1, vec2, vec3):
+  """
+  Return the normal of the 3D triangle defined.
+  @type vec1: Vector object.
+  @param vec1: A 3d vector, one corner of the triangle.
+  @type vec2: Vector object.
+  @param vec2: A 3d vector, one corner of the triangle.
+  @type vec3: Vector object.
+  @param vec3: A 3d vector, one corner of the triangle.
+  @rtype: float
+  @return: The normal of the 3D triangle defined.
+  """
+
+def QuadNormal(vec1, vec2, vec3, vec4):
+  """
+  Return the normal of the 3D quad defined.
+  @type vec1: Vector object.
+  @param vec1: A 3d vector, the first vertex of the quad.
+  @type vec2: Vector object.
+  @param vec2: A 3d vector, the second vertex of the quad.
+  @type vec3: Vector object.
+  @param vec3: A 3d vector, the third vertex of the quad.
+  @type vec4: Vector object.
+  @param vec4: A 3d vector, the fourth vertex of the quad.
+  @rtype: float
+  @return: The normal of the 3D quad defined.
+  """
+
+def LineIntersect(vec1, vec2, vec3, vec4):
+  """
+  Return a tuple with the points on each line respectively closest to the other
+  (when both lines intersect, both vector hold the same value).
+  The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.
+  @type vec1: Vector object.
+  @param vec1: A 3d vector, one point on the first line.
+  @type vec2: Vector object.
+  @param vec2: A 3d vector, another point on the first line.
+  @type vec3: Vector object.
+  @param vec3: A 3d vector, one point on the second line.
+  @type vec4: Vector object.
+  @param vec4: A 3d vector, another point on the second line.
+  @rtype: (Vector object, Vector object)
+  @return: A tuple with the points on each line respectively closest to the other.
+  """
+
+def CopyVec(vector):
+  """
+  Create a copy of the Vector object.
+  @attention: B{DEPRECATED} use vector.copy() instead.
+  @type vector: Vector object.
+  @param vector: A 2d,3d or 4d vector to be copied.
+  @rtype: Vector object.
+  @return: A new vector object which is a copy of the one passed in.
+  """
+
+def CrossVecs(vec1, vec2):
+  """
+  Return the cross product of two vectors.
+  @attention: B{DEPRECATED} use vector.cross(other) instead.
+  @type vec1: Vector object.
+  @param vec1: A 3d vector.
+  @type vec2: Vector object.
+  @param vec2: A 3d vector.
+  @rtype: Vector object.
+  @return: A new vector representing the cross product of
+  the two vectors.
+  """
+
+def DotVecs(vec1, vec2):
+  """
+  Return the dot product of two vectors.
+  @attention: B{DEPRECATED} use vector.dot(other) instead.
+  @type vec1: Vector object.
+  @param vec1: A 2d,3d or 4d vector.
+  @type vec2: Vector object.
+  @param vec2: A 2d,3d or 4d vector.
+  @rtype: float
+  @return: Return the scalar product of vector muliplication.
+  """
+
+def AngleBetweenVecs(vec1, vec2):
+  """
+  Return the angle between two vectors. Zero length vectors raise an error.
+  @type vec1: Vector object.
+  @param vec1: A 2d or 3d vector.
+  @type vec2: Vector object.
+  @param vec2: A 2d or 3d vector.
+  @rtype: float
+  @return: The angle between the vectors in degrees.
+  @raise AttributeError: When there is a zero-length vector as an argument.
+  """
+
+def MidpointVecs(vec1, vec2):
+  """
+  Return a vector to the midpoint between two vectors.
+  @type vec1: Vector object.
+  @param vec1: A 2d,3d or 4d vector.
+  @type vec2: Vector object.
+  @param vec2: A 2d,3d or 4d vector.
+  @rtype: Vector object
+  @return: The vector to the midpoint.
+  """
+
+def VecMultMat(vec, mat):
+  """
+  Multiply a vector and matrix (pre-multiply)
+  Vector size and matrix column size must equal.
+  @type vec: Vector object.
+  @param vec: A 2d,3d or 4d vector.
+  @type mat: Matrix object.
+  @param mat: A 2d,3d or 4d matrix.
+  @rtype: Vector object
+  @return: The row vector that results from the muliplication.
+  @attention: B{DEPRECATED} You should now multiply vector * matrix direcly
+  Example::
+      result = myVector * myMatrix
+  """
+
+def ProjectVecs(vec1, vec2):
+  """  
+  Return the projection of vec1 onto vec2.
+  @type vec1: Vector object.
+  @param vec1: A 2d,3d or 4d vector.
+  @type vec2: Vector object.
+  @param vec2: A 2d,3d or 4d vector.
+  @rtype: Vector object
+  @return: The parallel projection vector.
+  """
+
+def RotationMatrix(angle, matSize, axisFlag, axis):
+  """  
+  Create a matrix representing a rotation.
+  @type angle: float
+  @param angle: The angle of rotation desired.
+  @type matSize: int
+  @param matSize: The size of the rotation matrix to construct.
+  Can be 2d, 3d, or 4d.
+  @type axisFlag: string (optional)
+  @param axisFlag: Possible values:
+       - "x - x-axis rotation"
+       - "y - y-axis rotation"
+       - "z - z-axis rotation"
+       - "r - arbitrary rotation around vector"
+  @type axis: Vector object. (optional)
+  @param axis: The arbitrary axis of rotation used with "R"
+  @rtype: Matrix object.
+  @return: A new rotation matrix.
+  """
+
+def TranslationMatrix(vector):
+  """  
+  Create a matrix representing a translation
+  @type vector: Vector object
+  @param vector: The translation vector
+  @rtype: Matrix object.
+  @return: An identity matrix with a translation.
+  """
+
+def ScaleMatrix(factor, matSize, axis):
+  """  
+  Create a matrix representing a scaling.
+  @type factor: float
+  @param factor: The factor of scaling to apply.
+  @type matSize: int
+  @param matSize: The size of the scale matrix to construct.
+  Can be 2d, 3d, or 4d.
+  @type axis: Vector object.  (optional)
+  @param axis: Direction to influence scale.
+  @rtype: Matrix object.
+  @return: A new scale matrix.
+  """
+
+def OrthoProjectionMatrix(plane, matSize, axis):
+  """  
+  Create a matrix to represent an orthographic projection
+  @type plane: string
+  @param plane: Can be any of the following:
+       - "x - x projection (2D)"
+       - "y - y projection (2D)"
+       - "xy - xy projection"
+       - "xz - xz projection"
+       - "yz - yz projection"
+       - "r - arbitrary projection plane"
+  @type matSize: int
+  @param matSize: The size of the projection matrix to construct.
+  Can be 2d, 3d, or 4d.
+  @type axis: Vector object. (optional)
+  @param axis: Arbitrary perpendicular plane vector.
+  @rtype: Matrix object.
+  @return: A new projeciton matrix.
+  """
+
+def ShearMatrix(plane, factor, matSize):
+  """  
+  Create a matrix to represent an orthographic projection
+  @type plane: string
+  @param plane: Can be any of the following:
+       - "x - x shear (2D)"
+       - "y - y shear (2D)"
+       - "xy - xy shear"
+       - "xz - xz shear"
+       - "yz - yz shear"
+  @type factor: float
+  @param factor: The factor of shear to apply.
+  @type matSize: int
+  @param matSize: The size of the projection matrix to construct.
+  Can be 2d, 3d, or 4d.
+  @rtype: Matrix object.
+  @return: A new shear matrix.
+  """
+
+def CopyMat(matrix):
+  """
+  Create a copy of the Matrix object.
+  @type matrix: Matrix object.
+  @param matrix: A 2d,3d or 4d matrix to be copied.
+  @rtype: Matrix object.
+  @return: A new matrix object which is a copy of the one passed in.
+  @attention: B{DEPRECATED} Use the matrix copy funtion to make a copy.
+  Example::
+      newMat = myMat.copy()
+  """
+
+def MatMultVec(mat, vec):
+  """
+  Multiply a matrix and a vector (post-multiply)
+  Vector size and matrix row size must equal.
+  @type vec: Vector object.
+  @param vec: A 2d,3d or 4d vector.
+  @type mat: Matrix object.
+  @param mat: A 2d,3d or 4d matrix.
+  @rtype: Vector object
+  @return: The column vector that results from the muliplication.
+  @attention: B{DEPRECATED} You should use direct muliplication on the arguments
+  Example::
+      result = myMatrix * myVector
+  """
+
+def CopyQuat(quaternion):
+  """
+  Create a copy of the Quaternion object.
+  @type quaternion: Quaternion object.
+  @param quaternion: Quaternion to be copied.
+  @rtype: Quaternion object.
+  @return: A new quaternion object which is a copy of the one passed in.
+  @attention: B{DEPRECATED} You should use the Quaterion() constructor directly
+  to create copies of quaternions
+  Example::
+      newQuat = Quaternion(myQuat)
+  """
+
+def CrossQuats(quat1, quat2):
+  """
+  Return the cross product of two quaternions.
+  @attention: B{DEPRECATED} use quat.cross(other) instead.
+  @type quat1: Quaternion object.
+  @param quat1: Quaternion.
+  @type quat2: Quaternion object.
+  @param quat2: Quaternion.
+  @rtype: Quaternion object.
+  @return: A new quaternion representing the cross product of
+  the two quaternions.
+  """
+
+def DotQuats(quat1, quat2):
+  """
+  Return the dot product of two quaternions.
+  @attention: B{DEPRECATED} use quat.dot(other) instead.
+  @type quat1: Quaternion object.
+  @param quat1: Quaternion.
+  @type quat2: Quaternion object.
+  @param quat2: Quaternion.
+  @rtype: float
+  @return: Return the scalar product of quaternion muliplication.
+  """
+
+def DifferenceQuats(quat1, quat2):
+  """
+  Returns a quaternion represting the rotational difference.
+  @type quat1: Quaternion object.
+  @param quat1: Quaternion.
+  @type quat2: Quaternion object.
+  @param quat2: Quaternion.
+  @rtype: Quaternion object
+  @return: Return a quaternion which which represents the rotational
+  difference between the two quat rotations.
+  """
+
+def Slerp(quat1, quat2, factor):
+  """
+  Returns the interpolation of two quaternions.
+  @type quat1: Quaternion object.
+  @param quat1: Quaternion.
+  @type quat2: Quaternion object.
+  @param quat2: Quaternion.
+  @type factor: float
+  @param factor: The interpolation value
+  @rtype: Quaternion object
+  @return: The interpolated rotation.
+  """
+
+def CopyEuler(euler):
+  """
+  Create a new euler object.
+  @type euler: Euler object
+  @param euler: The euler to copy
+  @rtype: Euler object
+  @return: A copy of the euler object passed in.
+  @attention: B{DEPRECATED} You should use the Euler constructor directly
+  to make copies of Euler objects
+  Example::
+      newEuler = Euler(myEuler)
+  """
+
+def RotateEuler(euler, angle, axis):
+  """
+  Roatate a euler by an amount in degrees around an axis.
+  @type euler: Euler object
+  @param euler: Euler to rotate.
+  @type angle: float
+  @param angle: The amount of rotation in degrees
+  @type axis: string
+  @param axis: axis to rotate around:
+       - "x"
+       - "y"
+       - "z"
+  """
+
+class Vector:
+  """
+  The Vector object
+  =================
+    This object gives access to Vectors in Blender.
+  @group Axises: x, y, z, w
+  @ivar x: The x value.
+  @ivar y: The y value.
+  @ivar z: The z value (if any).
+  @ivar w: The w value (if any).
+  @ivar length: The magnitude of the vector.
+  @ivar magnitude: This is a synonym for length.
+  @ivar wrapped: Whether or not this item is wrapped data
+  @note: Comparison operators can be done on Vector classes:
+      - >, >=, <, <= test the vector magnitude
+      - ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length
+  @note: Math can be performed on Vector classes
+      - vec + vec
+      - vec - vec
+      - vec * float/int
+      - vec * matrix
+      - vec * vec
+      - vec * quat
+      - -vec
+  @note: You can access a vector object like a sequence
+      - x = vector[0]
+      - vec_a[:] vec_b
+      - vec2d[:] vec3d[:2]
+  @note: Vectors support 'swizzle' operations
+      - vec.xyz = vec.zyx
+      - vec.xy = vec.zw
+      - vec.xxy = vec.wzz
+      - vec.yzyz = vec.yxyx
+
+      See U{http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)}
+  
+  @attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list = None):
+    """
+    Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers.
+    @note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error.
+    
+
+    Example::
+      v = Vector(1,0,0)
+      v = Vector(myVec)
+      v = Vector(list)
+    @type list: PyList of float or int
+    @param list: The list of values for the Vector object. Can be a sequence or raw numbers.
+    Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w].
+    @rtype: Vector object.
+    @return: It depends wheter a parameter was passed:
+        - (list): Vector object initialized with the given values;
+        - ():     An empty 3 dimensional vector.
+    """
+
+  def copy():
+    """
+    Returns a copy of this vector
+    @return: a copy of itself
+    """
+
+  def zero():
+    """
+    Set all values to zero.
+    @return: an instance of itself
+    """
+
+  def normalize():
+    """
+    Normalize the vector, making the length of the vector always 1.0
+    @note: Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched.
+    @note: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).
+    @return: an instance of itself
+    """
+
+  def negate():
+    """
+    Set all values to their negative.
+    @return: an instance of its self
+    """
+
+  def resize2D():
+    """
+    Resize the vector to 2d.
+    @return: an instance of itself
+    """
+
+  def resize3D():
+    """
+    Resize the vector to 3d. New axis will be 0.0.
+    @return: an instance of itself
+    """
+
+  def resize4D():
+    """
+    Resize the vector to 4d. New axis will be 0.0.
+    The last component will be 1.0, to make multiplying 3d vectors by 4x4 matrices easier.
+    @return: an instance of itself
+    """
+
+  def toTrackQuat(track, up):
+    """
+    Return a quaternion rotation from the vector and the track and up axis.
+    @type track: String.
+    @param track: Possible values:
+		   - "x - x-axis up"
+		   - "y - y-axis up"
+		   - "z - z-axis up"
+		   - "-x - negative x-axis up"
+		   - "-y - negative y-axis up"
+		   - "-z - negative z-axis up"
+    @type up: String.
+    @param up: Possible values:
+		   - "x - x-axis up"
+		   - "y - y-axis up"
+		   - "z - z-axis up"
+    @rtype: Quaternion
+    @return: Return a quaternion rotation from the vector and the track and up axis.
+    """
+
+  def reflect(mirror):
+    """
+    Return the reflection vector from the mirror vector argument.
+    @type mirror: Vector object
+    @param mirror: This vector could be a normal from the reflecting surface.
+    @rtype: Vector object matching the size of this vector.
+    @return: The reflected vector.
+    """
+
+  def cross(other):
+    """
+    Return the cross product of this vector and another.
+    @note: both vectors must be 3D.
+    @type other: Vector object
+    @param other: The other vector to perform the cross product with.
+    @rtype: Vector
+    @return: The cross product.
+    """
+
+  def dot(other):
+    """
+    Return the dot product of this vector and another.
+    @note: both vectors must be the same size.
+    @type other: Vector object
+    @param other: The other vector to perform the dot product with.
+    @rtype: float
+    @return: The dot product.
+    """
+
+class Euler:
+  """
+  The Euler object
+  ================
+    This object gives access to Eulers in Blender.
+  @group Axises: x, y, z
+  @ivar x: The heading value in degrees.
+  @ivar y: The pitch value in degrees.
+  @ivar z: The roll value in degrees.
+  @ivar wrapped: Whether or not this object is wrapping data directly
+  @note: You can access a euler object like a sequence
+      - x = euler[0]
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list = None):
+    """
+    Create a new euler object.
+
+    Example::
+      euler = Euler(45,0,0)
+      euler = Euler(myEuler)
+      euler = Euler(sequence)
+    @type list: PyList of float/int
+    @param list: 3d list to initialize euler
+    @rtype: Euler object
+    @return: Euler representing heading, pitch, bank.
+    @note: Values are in degrees.
+    """
+
+  def zero():
+    """
+    Set all values to zero.
+    @return: an instance of itself
+    """
+
+  def copy():
+    """
+    @return: a copy of this euler.
+    """
+
+  def unique():
+    """
+    Calculate a unique rotation for this euler. Avoids gimble lock.
+    @return: an instance of itself
+    """
+
+  def toMatrix():
+    """
+    Return a matrix representation of the euler.
+    @rtype: Matrix object
+    @return: A 3x3 roation matrix representation of the euler.
+    """
+
+  def toQuat():
+    """
+    Return a quaternion representation of the euler.
+    @rtype: Quaternion object
+    @return: Quaternion representation of the euler.
+    """
+  def makeCompatible(eul_compat):
+    """
+    Make this euler compatible with another, so interpolating between them works as expected.
+    @rtype: Euler object
+    @return: an instance of itself
+    """
+
+class Quaternion:
+  """
+  The Quaternion object
+  =====================
+    This object gives access to Quaternions in Blender.
+  @group Axises: x, y, z, w
+  @ivar w: The w value.
+  @ivar x: The x value.
+  @ivar y: The y value.
+  @ivar z: The z value.
+  @ivar wrapped: Wether or not this object wraps data directly
+  @ivar magnitude: The magnitude of the quaternion.
+  @ivar axis: Vector representing the axis of rotation.
+  @ivar angle: A scalar representing the amount of rotation
+  in degrees.
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @note: Math can be performed on Quaternion classes
+      - quat + quat
+      - quat - quat 
+      - quat * float/int
+      - quat * vec
+      - quat * quat
+  @note: You can access a quaternion object like a sequence
+      - x = quat[0]
+  @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list, angle = None):
+    """  
+    Create a new quaternion object from initialized values.
+
+    Example::
+      quat = Quaternion(1,2,3,4)
+      quat = Quaternion(axis, angle)
+    quat = Quaternion()
+    quat = Quaternion(180, list)
+
+    @type list: PyList of int/float
+    @param list: A 3d or 4d list to initialize quaternion.
+        4d if intializing [w,x,y,z], 3d if used as an axis of rotation.
+    @type angle: float (optional)
+    @param angle: An arbitrary rotation amount around 'list'.
+        List is used as an axis of rotation in this case.
+    @rtype: New quaternion object.
+    @return: It depends wheter a parameter was passed:
+        - (list/angle): Quaternion object initialized with the given values;
+        - ():     An identity 4 dimensional quaternion.
+    """
+
+  def identity():
+    """
+    Set the quaternion to the identity quaternion.
+    @return: an instance of itself
+    """
+
+  def copy():
+    """
+    make a copy of the quaternion.
+    @return: a copy of itself
+    """
+
+  def negate():
+    """
+    Set the quaternion to its negative.
+    @return: an instance of itself
+    """
+
+  def conjugate():
+    """
+    Set the quaternion to its conjugate.
+    @return: an instance of itself
+    """
+
+  def inverse():
+    """
+    Set the quaternion to its inverse
+    @return: an instance of itself
+    """
+
+  def normalize():
+    """
+    Normalize the quaternion.
+    @return: an instance of itself
+    """
+
+  def toEuler(eul_compat):
+    """
+    Return Euler representation of the quaternion.
+    @type eul_compat: L{Euler}
+    @param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
+    @rtype: Euler object
+    @return: Euler representation of the quaternion.
+    """
+  
+  def toMatrix():
+    """
+    Return a matrix representation of the quaternion.
+    @rtype: Matrix object
+    @return: A 3x3 rotation matrix representation of the quaternion.
+    """
+
+  def cross(other):
+    """
+    Return the cross product of this quaternion and another.
+    @type other: Quaterion object
+    @param other: The other quaternion to perform the cross product with.
+    @rtype: Vector
+    @return: The cross product.
+    """
+
+  def dot(other):
+    """
+    Return the dot product of this quaternion and another.
+    @type other: Quaterion object
+    @param other: The other quaternion to perform the dot product with.
+    @rtype: float
+    @return: The dot product.
+    """
+
+class Matrix:
+  """
+  The Matrix Object
+  =================
+    This object gives access to Matrices in Blender.
+  @ivar rowSize: The row size of the matrix.
+  @ivar colSize: The column size of the matrix.
+  @ivar wrapped: Whether or not this object wrapps internal data
+  @note: Math can be performed on Matrix classes
+      - mat + mat 
+      - mat - mat 
+      - mat * float/int
+      - mat * vec
+      - mat * mat 
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @note: You can access a quaternion object like a 2d sequence
+      - x = matrix[0][1]
+      - vector = matrix[2]
+  @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
+    """  
+    Create a new matrix object from initialized values.
+
+    Example::
+      matrix = Matrix([1,1,1],[0,1,0],[1,0,0])
+      matrix = Matrix(mat)
+      matrix = Matrix(seq1, seq2, vector)
+
+    @type list1: PyList of int/float
+    @param list1: A 2d,3d or 4d list.
+    @type list2: PyList of int/float
+    @param list2: A 2d,3d or 4d list.
+    @type list3: PyList of int/float
+    @param list3: A 2d,3d or 4d list.
+    @type list4: PyList of int/float
+    @param list4: A 2d,3d or 4d list.
+    @rtype: New matrix object.
+    @return: It depends wheter a parameter was passed:
+        - (list1, etc.): Matrix object initialized with the given values;
+        - ():     An empty 3 dimensional matrix.
+    """
+
+  def zero():
+    """
+    Set all matrix values to 0.
+    @return: an instance of itself
+    """
+
+
+  def copy():
+    """
+    Returns a copy of this matrix
+    @return: a copy of itself
+    """
+
+  def identity():
+    """
+    Set the matrix to the identity matrix.
+    An object with zero location and rotation, a scale of 1, will have an identity matrix.
+
+    See U{http://en.wikipedia.org/wiki/Identity_matrix}
+    @return: an instance of itself
+    """
+
+  def transpose():
+    """
+    Set the matrix to its transpose.
+    
+    See U{http://en.wikipedia.org/wiki/Transpose}
+    @return: None
+    """
+
+  def determinant():
+    """
+    Return the determinant of a matrix.
+    
+    See U{http://en.wikipedia.org/wiki/Determinant}
+    @rtype: float
+    @return: Return a the determinant of a matrix.
+    """
+
+  def invert():
+    """
+    Set the matrix to its inverse.
+    
+    See U{http://en.wikipedia.org/wiki/Inverse_matrix}
+    @return: an instance of itself.
+    @raise ValueError: When matrix is singular.
+    """
+
+  def rotationPart():
+    """
+    Return the 3d submatrix corresponding to the linear term of the 
+    embedded affine transformation in 3d. This matrix represents rotation
+    and scale. Note that the (4,4) element of a matrix can be used for uniform
+    scaling, too.
+    @rtype: Matrix object.
+    @return: Return the 3d matrix for rotation and scale.
+    """
+
+  def translationPart():
+    """
+    Return a the translation part of a 4 row matrix.
+    @rtype: Vector object.
+    @return: Return a the translation of a matrix.
+    """
+
+  def scalePart():
+    """
+    Return a the scale part of a 3x3 or 4x4 matrix.
+    @note: This method does not return negative a scale on any axis because it is not possible to obtain this data from the matrix alone.
+    @rtype: Vector object.
+    @return: Return a the scale of a matrix.
+    """
+
+  def resize4x4():
+    """
+    Resize the matrix to by 4x4
+    @return: an instance of itself.
+    """
+  
+  def toEuler(eul_compat):
+    """
+    Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).
+    @type eul_compat: L{Euler}
+    @param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
+    @rtype: Euler object
+    @return: Euler representation of the rotation matrix.
+    """
+
+  def toQuat():
+    """
+    Return a quaternion representation of the rotation matrix
+    @rtype: Quaternion object
+    @return: Quaternion representation of the rotation matrix
+    """
+

source/blender/python/doc/epy/testbgl.py

@@ -0,0 +1,45 @@
+# Testing the BGL module
+
+import Blender
+from Blender.BGL import *
+from Blender import Draw
+
+R = G = B = 0
+A = 1
+
+instructions = "Hold mouse buttons to change the background color."
+quitting = " Press ESC or q to quit."
+
+def show_win():
+  glClearColor(R,G,B,A)                # define color used to clear buffers 
+  glClear(GL_COLOR_BUFFER_BIT)         # use it to clear the color buffer
+  glColor3f(1,1,1)                     # change default color
+  glRasterPos2i(50,100)                # move cursor to x = 50, y = 100
+  Draw.Text("Testing BGL  + Draw")     # draw this text there
+  glRasterPos2i(350,20)                # move cursor again
+  Draw.Text(instructions + quitting)   # draw another msg
+  glBegin(GL_LINE_LOOP)                # begin a vertex-data list
+  glVertex2i(46,92)
+  glVertex2i(120,92)
+  glVertex2i(120,115)
+  glVertex2i(46,115)
+  glEnd()                              # close this list
+  glColor3f(0.35,0.18,0.92)            # change default color again
+  glBegin(GL_POLYGON)                  # another list, for a polygon
+  glVertex2i(315, 292)
+  glVertex2i(412, 200)
+  glVertex2i(264, 256)
+  glEnd()
+  Draw.Redraw(1)                       # make changes visible.
+
+def ev(evt, val):                      # this is a callback for Draw.Register()
+  global R,G,B,A                       # it handles input events
+  if evt == Draw.ESCKEY or evt == Draw.QKEY:
+    Draw.Exit()                        # this quits the script
+  elif evt == Draw.LEFTMOUSE: R = 1 - R
+  elif evt == Draw.MIDDLEMOUSE: G = 1 - G
+  elif evt == Draw.RIGHTMOUSE: B = 1 - B
+  else:
+    Draw.Register(show_win, ev, None)
+
+Draw.Register(show_win, ev, None)      # start the main loop