Python API

Mathutils support for subclassing Vector, Quat, Euler and Matrix types.

Removed C docstrings, prefer to make sure our epydocs are well maintained rather then duplicate, vague doc strings.
Will convert scripts to detect missing docs from the BGE.

1 files changed, 38 insertions, 51 deletions

diff --git a/source/blender/python/generic/matrix.c b/source/blender/python/generic/matrix.c
index 311a14fbb0a..41411559fe0 100644
--- a/source/blender/python/generic/matrix.c
+++ b/source/blender/python/generic/matrix.c
@@ -97,18 +97,6 @@ Mathutils_Callback mathutils_matrix_vector_cb = {
 /* matrix vector callbacks, this is so you can do matrix[i][j] = val  */
 
 /*-------------------------DOC STRINGS ---------------------------*/
-static char Matrix_Zero_doc[] = "() - set all values in the matrix to 0";
-static char Matrix_Identity_doc[] = "() - set the square matrix to it's identity matrix";
-static char Matrix_Transpose_doc[] = "() - set the matrix to it's transpose";
-static char Matrix_Determinant_doc[] = "() - return the determinant of the matrix";
-static char Matrix_Invert_doc[] =  "() - set the matrix to it's inverse if an inverse is possible";
-static char Matrix_TranslationPart_doc[] = "() - return a vector encompassing the translation of the matrix";
-static char Matrix_RotationPart_doc[] = "() - return a vector encompassing the rotation of the matrix";
-static char Matrix_scalePart_doc[] = "() - convert matrix to a 3D vector";
-static char Matrix_Resize4x4_doc[] = "() - resize the matrix to a 4x4 square matrix";
-static char Matrix_toEuler_doc[] = "(eul_compat) - convert matrix to a euler angle rotation, optional euler argument that the new euler will be made compatible with.";
-static char Matrix_toQuat_doc[] = "() - convert matrix to a quaternion rotation";
-static char Matrix_copy_doc[] = "() - return a copy of the matrix";
 
 static PyObject *Matrix_Zero( MatrixObject * self );
 static PyObject *Matrix_Identity( MatrixObject * self );
@@ -125,19 +113,19 @@ static PyObject *Matrix_copy( MatrixObject * self );
 
 /*-----------------------METHOD DEFINITIONS ----------------------*/
 static struct PyMethodDef Matrix_methods[] = {
-	{"zero", (PyCFunction) Matrix_Zero, METH_NOARGS, Matrix_Zero_doc},
-	{"identity", (PyCFunction) Matrix_Identity, METH_NOARGS, Matrix_Identity_doc},
-	{"transpose", (PyCFunction) Matrix_Transpose, METH_NOARGS, Matrix_Transpose_doc},
-	{"determinant", (PyCFunction) Matrix_Determinant, METH_NOARGS, Matrix_Determinant_doc},
-	{"invert", (PyCFunction) Matrix_Invert, METH_NOARGS, Matrix_Invert_doc},
-	{"translationPart", (PyCFunction) Matrix_TranslationPart, METH_NOARGS, Matrix_TranslationPart_doc},
-	{"rotationPart", (PyCFunction) Matrix_RotationPart, METH_NOARGS, Matrix_RotationPart_doc},
-	{"scalePart", (PyCFunction) Matrix_scalePart, METH_NOARGS, Matrix_scalePart_doc},
-	{"resize4x4", (PyCFunction) Matrix_Resize4x4, METH_NOARGS, Matrix_Resize4x4_doc},
-	{"toEuler", (PyCFunction) Matrix_toEuler, METH_VARARGS, Matrix_toEuler_doc},
-	{"toQuat", (PyCFunction) Matrix_toQuat, METH_NOARGS, Matrix_toQuat_doc},
-	{"copy", (PyCFunction) Matrix_copy, METH_NOARGS, Matrix_copy_doc},
-	{"__copy__", (PyCFunction) Matrix_copy, METH_NOARGS, Matrix_copy_doc},
+	{"zero", (PyCFunction) Matrix_Zero, METH_NOARGS, NULL},
+	{"identity", (PyCFunction) Matrix_Identity, METH_NOARGS, NULL},
+	{"transpose", (PyCFunction) Matrix_Transpose, METH_NOARGS, NULL},
+	{"determinant", (PyCFunction) Matrix_Determinant, METH_NOARGS, NULL},
+	{"invert", (PyCFunction) Matrix_Invert, METH_NOARGS, NULL},
+	{"translationPart", (PyCFunction) Matrix_TranslationPart, METH_NOARGS, NULL},
+	{"rotationPart", (PyCFunction) Matrix_RotationPart, METH_NOARGS, NULL},
+	{"scalePart", (PyCFunction) Matrix_scalePart, METH_NOARGS, NULL},
+	{"resize4x4", (PyCFunction) Matrix_Resize4x4, METH_NOARGS, NULL},
+	{"toEuler", (PyCFunction) Matrix_toEuler, METH_VARARGS, NULL},
+	{"toQuat", (PyCFunction) Matrix_toQuat, METH_NOARGS, NULL},
+	{"copy", (PyCFunction) Matrix_copy, METH_NOARGS, NULL},
+	{"__copy__", (PyCFunction) Matrix_copy, METH_NOARGS, NULL},
 	{NULL, NULL, 0, NULL}
 };
 
@@ -158,7 +146,7 @@ static PyObject *Matrix_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 		PyErr_SetString(PyExc_AttributeError, "Mathutils.Matrix(): expects 0-4 numeric sequences of the same size\n");
 		return NULL;
 	} else if (argSize == 0) { //return empty 4D matrix
-		return (PyObject *) newMatrixObject(NULL, 4, 4, Py_NEW);
+		return (PyObject *) newMatrixObject(NULL, 4, 4, Py_NEW, NULL);
 	}else if (argSize == 1){
 		//copy constructor for matrix objects
 		argObject = PyTuple_GET_ITEM(args, 0);
@@ -167,11 +155,7 @@ static PyObject *Matrix_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 			if(!BaseMath_ReadCallback(mat))
 				return NULL;
 
-			argSize = mat->rowSize; //rows
-			seqSize = mat->colSize; //col
-			for(i = 0; i < (seqSize * argSize); i++){
-				matrix[i] = mat->contigPtr[i];
-			}
+			memcpy(matrix, mat->contigPtr, sizeof(float) * mat->rowSize * mat->colSize);
 		}
 	}else{ //2-4 arguments (all seqs? all same size?)
 		for(i =0; i < argSize; i++){
@@ -216,7 +200,7 @@ static PyObject *Matrix_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 			}
 		}
 	}
-	return newMatrixObject(matrix, argSize, seqSize, Py_NEW);
+	return newMatrixObject(matrix, argSize, seqSize, Py_NEW, NULL);
 }
 
 /*-----------------------------METHODS----------------------------*/
@@ -239,14 +223,16 @@ static PyObject *Matrix_toQuat(MatrixObject * self)
 		Mat4ToQuat((float (*)[4])*self->matrix, quat);
 	}
 	
-	return newQuaternionObject(quat, Py_NEW);
+	return newQuaternionObject(quat, Py_NEW, NULL);
 }
 /*---------------------------Matrix.toEuler() --------------------*/
 PyObject *Matrix_toEuler(MatrixObject * self, PyObject *args)
 {
 	float eul[3], eul_compatf[3];
 	EulerObject *eul_compat = NULL;
+#ifdef USE_MATHUTILS_DEG
 	int x;
+#endif
 	
 	if(!BaseMath_ReadCallback(self))
 		return NULL;
@@ -288,7 +274,7 @@ PyObject *Matrix_toEuler(MatrixObject * self, PyObject *args)
 		eul[x] *= (float) (180 / Py_PI);
 	}
 #endif
-	return newEulerObject(eul, Py_NEW);
+	return newEulerObject(eul, Py_NEW, NULL);
 }
 /*---------------------------Matrix.resize4x4() ------------------*/
 PyObject *Matrix_Resize4x4(MatrixObject * self)
@@ -364,7 +350,7 @@ PyObject *Matrix_TranslationPart(MatrixObject * self)
 	vec[1] = self->matrix[3][1];
 	vec[2] = self->matrix[3][2];
 
-	return newVectorObject(vec, 3, Py_NEW);
+	return newVectorObject(vec, 3, Py_NEW, NULL);
 }
 /*---------------------------Matrix.rotationPart() ---------------*/
 PyObject *Matrix_RotationPart(MatrixObject * self)
@@ -390,7 +376,7 @@ PyObject *Matrix_RotationPart(MatrixObject * self)
 	mat[7] = self->matrix[2][1];
 	mat[8] = self->matrix[2][2];
 
-	return newMatrixObject(mat, 3, 3, Py_NEW);
+	return newMatrixObject(mat, 3, 3, Py_NEW, Py_TYPE(self));
 }
 /*---------------------------Matrix.scalePart() --------------------*/
 PyObject *Matrix_scalePart(MatrixObject * self)
@@ -419,7 +405,7 @@ PyObject *Matrix_scalePart(MatrixObject * self)
 	scale[0]= tmat[0][0];
 	scale[1]= tmat[1][1];
 	scale[2]= tmat[2][2];
-	return newVectorObject(scale, 3, Py_NEW);
+	return newVectorObject(scale, 3, Py_NEW, NULL);
 }
 /*---------------------------Matrix.invert() ---------------------*/
 PyObject *Matrix_Invert(MatrixObject * self)
@@ -589,7 +575,7 @@ PyObject *Matrix_copy(MatrixObject * self)
 	if(!BaseMath_ReadCallback(self))
 		return NULL;
 	
-	return (PyObject*)(MatrixObject*)newMatrixObject((float (*))*self->matrix, self->rowSize, self->colSize, Py_NEW);
+	return (PyObject*)newMatrixObject((float (*))*self->matrix, self->rowSize, self->colSize, Py_NEW, Py_TYPE(self));
 }
 
 /*----------------------------print object (internal)-------------*/
@@ -674,8 +660,7 @@ static PyObject* Matrix_richcmpr(PyObject *objectA, PyObject *objectB, int compa
 		Py_RETURN_FALSE;
 	}
 }
-/*------------------------tp_doc*/
-static char MatrixObject_doc[] = "This is a wrapper for matrix objects.";
+
 /*---------------------SEQUENCE PROTOCOLS------------------------
   ----------------------------len(object)------------------------
   sequence length*/
@@ -882,7 +867,7 @@ static PyObject *Matrix_add(PyObject * m1, PyObject * m2)
 		}
 	}
 
-	return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW);
+	return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW, NULL);
 }
 /*------------------------obj - obj------------------------------
   subtraction*/
@@ -915,7 +900,7 @@ static PyObject *Matrix_sub(PyObject * m1, PyObject * m2)
 		}
 	}
 
-	return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW);
+	return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW, NULL);
 }
 /*------------------------obj * obj------------------------------
   mulplication*/
@@ -954,7 +939,7 @@ static PyObject *Matrix_mul(PyObject * m1, PyObject * m2)
 			}
 		}
 		
-		return newMatrixObject(mat, mat1->rowSize, mat2->colSize, Py_NEW);
+		return newMatrixObject(mat, mat1->rowSize, mat2->colSize, Py_NEW, NULL);
 	}
 	
 	if(mat1==NULL){
@@ -965,7 +950,7 @@ static PyObject *Matrix_mul(PyObject * m1, PyObject * m2)
 					mat[((x * mat2->colSize) + y)] = scalar * mat2->matrix[x][y];
 				}
 			}
-			return newMatrixObject(mat, mat2->rowSize, mat2->colSize, Py_NEW);
+			return newMatrixObject(mat, mat2->rowSize, mat2->colSize, Py_NEW, NULL);
 		}
 		
 		PyErr_SetString(PyExc_TypeError, "Matrix multiplication: arguments not acceptable for this operation");
@@ -984,7 +969,7 @@ static PyObject *Matrix_mul(PyObject * m1, PyObject * m2)
 						mat[((x * mat1->colSize) + y)] = scalar * mat1->matrix[x][y];
 					}
 				}
-				return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW);
+				return newMatrixObject(mat, mat1->rowSize, mat1->colSize, Py_NEW, NULL);
 			}
 		}
 		PyErr_SetString(PyExc_TypeError, "Matrix multiplication: arguments not acceptable for this operation");
@@ -1128,8 +1113,8 @@ PyTypeObject matrix_Type = {
 	0,								/*tp_getattro*/
 	0,								/*tp_setattro*/
 	0,								/*tp_as_buffer*/
-	Py_TPFLAGS_DEFAULT,				/*tp_flags*/
-	MatrixObject_doc,				/*tp_doc*/
+	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
+	0,								/*tp_doc*/
 	0,								/*tp_traverse*/
 	0,								/*tp_clear*/
 	(richcmpfunc)Matrix_richcmpr,	/*tp_richcompare*/
@@ -1173,7 +1158,7 @@ self->matrix[1][1] = self->contigPtr[4] */
  (i.e. it was allocated elsewhere by MEM_mallocN())
   pass Py_NEW - if vector is not a WRAPPER and managed by PYTHON
  (i.e. it must be created here with PyMEM_malloc())*/
-PyObject *newMatrixObject(float *mat, int rowSize, int colSize, int type)
+PyObject *newMatrixObject(float *mat, int rowSize, int colSize, int type, PyTypeObject *base_type)
 {
 	MatrixObject *self;
 	int x, row, col;
@@ -1184,7 +1169,9 @@ PyObject *newMatrixObject(float *mat, int rowSize, int colSize, int type)
 		return NULL;
 	}
 
-	self = PyObject_NEW(MatrixObject, &matrix_Type);
+	if(base_type)	self = (MatrixObject *)base_type->tp_alloc(base_type, 0);
+	else			self = PyObject_NEW(MatrixObject, &matrix_Type);
+
 	self->rowSize = rowSize;
 	self->colSize = colSize;
 	
@@ -1242,7 +1229,7 @@ PyObject *newMatrixObject(float *mat, int rowSize, int colSize, int type)
 
 PyObject *newMatrixObject_cb(PyObject *cb_user, int rowSize, int colSize, int cb_type, int cb_subtype)
 {
-	MatrixObject *self= (MatrixObject *)newMatrixObject(NULL, rowSize, colSize, Py_NEW);
+	MatrixObject *self= (MatrixObject *)newMatrixObject(NULL, rowSize, colSize, Py_NEW, NULL);
 	if(self) {
 		Py_INCREF(cb_user);
 		self->cb_user=			cb_user;
@@ -1287,5 +1274,5 @@ static PyObject *column_vector_multiplication(MatrixObject * mat, VectorObject*
 		vecNew[z++] = (float)dot;
 		dot = 0.0f;
 	}
-	return newVectorObject(vecNew, vec->size, Py_NEW);
+	return newVectorObject(vecNew, vec->size, Py_NEW, NULL);
 }