[Bf-blender-cvs] [90eb93791f1] master: Cleanup: mathutils vector comments
Campbell Barton
noreply at git.blender.org
Sat Sep 9 02:42:08 CEST 2017
Commit: 90eb93791f1543174eb3d20b2e8a2a92edba6e95
Author: Campbell Barton
Date: Sat Sep 9 10:47:57 2017 +1000
Branches: master
https://developer.blender.org/rB90eb93791f1543174eb3d20b2e8a2a92edba6e95
Cleanup: mathutils vector comments
Use doxy markup & correct outdated info.
===================================================================
M source/blender/python/mathutils/mathutils_Vector.c
===================================================================
diff --git a/source/blender/python/mathutils/mathutils_Vector.c b/source/blender/python/mathutils/mathutils_Vector.c
index e48690a80fe..48f8d55f10a 100644
--- a/source/blender/python/mathutils/mathutils_Vector.c
+++ b/source/blender/python/mathutils/mathutils_Vector.c
@@ -38,6 +38,11 @@
# include "BLI_dynstr.h"
#endif
+/**
+ * Higher dimensions are supported, for many common operations
+ * (dealing with vector/matrix multiply or handling as 3D locations)
+ * stack memory is used with a fixed size - defined here.
+ */
#define MAX_DIMENSIONS 4
/* Swizzle axes get packed into a single value that is used as a closure. Each
@@ -52,7 +57,8 @@ static PyObject *Vector_deepcopy(VectorObject *self, PyObject *args);
static PyObject *Vector_to_tuple_ext(VectorObject *self, int ndigits);
static int row_vector_multiplication(float rvec[MAX_DIMENSIONS], VectorObject *vec, MatrixObject *mat);
-/* Supports 2D, 3D, and 4D vector objects both int and float values
+/**
+ * Supports 2D, 3D, and 4D vector objects both int and float values
* accepted. Mixed float and int values accepted. Ints are parsed to float
*/
static PyObject *Vector_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@@ -838,9 +844,11 @@ static PyObject *Vector_orthogonal(VectorObject *self)
}
-/*
- * Vector.reflect(mirror): return a reflected vector on the mirror normal
- * vec - ((2 * DotVecs(vec, mirror)) * mirror)
+/**
+ * Vector.reflect(mirror): return a reflected vector on the mirror normal.
+ * <pre>
+ * vec - ((2 * dot(vec, mirror)) * mirror)
+ * </pre>
*/
PyDoc_STRVAR(Vector_reflect_doc,
".. method:: reflect(mirror)\n"
@@ -1646,13 +1654,16 @@ static PyObject *Vector_isub(PyObject *v1, PyObject *v2)
* multiplication */
-/* COLUMN VECTOR Multiplication (Matrix X Vector)
+/**
+ * column vector multiplication (Matrix * Vector)
+ * <pre>
* [1][4][7] [a]
* [2][5][8] * [b]
* [3][6][9] [c]
+ * </pre>
*
- * note: vector/matrix multiplication IS NOT COMMUTATIVE!!!!
- * note: assume read callbacks have been done first.
+ * \note Vector/Matrix multiplication is not commutative.
+ * \note Assume read callbacks have been done first.
*/
int column_vector_multiplication(float r_vec[MAX_DIMENSIONS], VectorObject *vec, MatrixObject *mat)
{
@@ -2201,9 +2212,67 @@ static PyObject *Vector_length_squared_get(VectorObject *self, void *UNUSED(clos
return PyFloat_FromDouble(dot_vn_vn(self->vec, self->vec, self->size));
}
-/* Get a new Vector according to the provided swizzle. This function has little
- * error checking, as we are in control of the inputs: the closure is set by us
- * in Vector_createSwizzleGetSeter. */
+
+/**
+ * Python script used to make swizzle array:
+ *
+ * \code{.py}
+ * SWIZZLE_BITS_PER_AXIS = 3
+ * SWIZZLE_VALID_AXIS = 0x4
+ *
+ * axis_dict = {}
+ * axis_pos = {'x': 0, 'y': 1, 'z': 2, 'w': 3}
+ * axises = 'xyzw'
+ * while len(axises) >= 2:
+ * for axis_0 in axises:
+ * axis_0_pos = axis_pos[axis_0]
+ * for axis_1 in axises:
+ * axis_1_pos = axis_pos[axis_1]
+ * axis_dict[axis_0 + axis_1] = (
+ * '((%s | SWIZZLE_VALID_AXIS) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS))' %
+ * (axis_0_pos, axis_1_pos))
+ * if len(axises) > 2:
+ * for axis_2 in axises:
+ * axis_2_pos = axis_pos[axis_2]
+ * axis_dict[axis_0 + axis_1 + axis_2] = (
+ * '((%s | SWIZZLE_VALID_AXIS) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 2)))' %
+ * (axis_0_pos, axis_1_pos, axis_2_pos))
+ * if len(axises) > 3:
+ * for axis_3 in axises:
+ * axis_3_pos = axis_pos[axis_3]
+ * axis_dict[axis_0 + axis_1 + axis_2 + axis_3] = (
+ * '((%s | SWIZZLE_VALID_AXIS) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 2)) | '
+ * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 3))) ' %
+ * (axis_0_pos, axis_1_pos, axis_2_pos, axis_3_pos))
+ *
+ * axises = axises[:-1]
+ *
+ *
+ * items = list(axis_dict.items())
+ * items.sort(key=lambda a: a[0].replace('x', '0').replace('y', '1').replace('z', '2').replace('w', '3'))
+ *
+ * unique = set()
+ * for key, val in items:
+ * num = eval(val)
+ * set_str = 'Vector_swizzle_set' if (len(set(key)) == len(key)) else 'NULL'
+ * key_args = ', '.join(["'%s'" % c for c in key.upper()])
+ * print('\t{(char *)"%s", %s(getter)Vector_swizzle_get, (setter)%s, NULL, SWIZZLE%d(%s)},' %
+ * (key, (' ' * (4 - len(key))), set_str, len(key), key_args))
+ * unique.add(num)
+ *
+ * if len(unique) != len(items):
+ * print("ERROR, duplicate values found")
+ * \endcode
+ */
+
+/**
+ * Get a new Vector according to the provided swizzle bits.
+ */
static PyObject *Vector_swizzle_get(VectorObject *self, void *closure)
{
size_t axis_to;
@@ -2234,7 +2303,8 @@ static PyObject *Vector_swizzle_get(VectorObject *self, void *closure)
return Vector_CreatePyObject(vec, axis_to, Py_TYPE(self));
}
-/* Set the items of this vector using a swizzle.
+/**
+ * Set the items of this vector using a swizzle.
* - If value is a vector or list this operates like an array copy, except that
* the destination is effectively re-ordered as defined by the swizzle. At
* most min(len(source), len(dest)) values will be copied.
@@ -2242,8 +2312,8 @@ static PyObject *Vector_swizzle_get(VectorObject *self, void *closure)
* - If an axis appears more than once in the swizzle, the final occurrence is
* the one that determines its value.
*
- * Returns 0 on success and -1 on failure. On failure, the vector will be
- * unchanged. */
+ * \return 0 on success and -1 on failure. On failure, the vector will be unchanged.
+ */
static int Vector_swizzle_set(VectorObject *self, PyObject *value, void *closure)
{
size_t size_from;
@@ -2351,7 +2421,7 @@ static PyGetSetDef Vector_getseters[] = {
{(char *)"is_frozen", (getter)BaseMathObject_is_frozen_get, (setter)NULL, BaseMathObject_is_frozen_doc, NULL},
{(char *)"owner", (getter)BaseMathObject_owner_get, (setter)NULL, BaseMathObject_owner_doc, NULL},
- /* autogenerated swizzle attrs, see python script below */
+ /* autogenerated swizzle attrs, see Python script above */
{(char *)"xx", (getter)Vector_swizzle_get, (setter)NULL, NULL, SWIZZLE2(0, 0)},
{(char *)"xxx", (getter)Vector_swizzle_get, (setter)NULL, NULL, SWIZZLE3(0, 0, 0)},
{(char *)"xxxx", (getter)Vector_swizzle_get, (setter)NULL, NULL, SWIZZLE4(0, 0, 0, 0)},
@@ -2703,67 +2773,14 @@ static PyGetSetDef Vector_getseters[] = {
};
/**
- * Python script used to make swizzle array:
- *
- * \code{.py}
- * SWIZZLE_BITS_PER_AXIS = 3
- * SWIZZLE_VALID_AXIS = 0x4
- *
- * axis_dict = {}
- * axis_pos = {'x': 0, 'y': 1, 'z': 2, 'w': 3}
- * axises = 'xyzw'
- * while len(axises) >= 2:
- * for axis_0 in axises:
- * axis_0_pos = axis_pos[axis_0]
- * for axis_1 in axises:
- * axis_1_pos = axis_pos[axis_1]
- * axis_dict[axis_0 + axis_1] = (
- * '((%s | SWIZZLE_VALID_AXIS) | '
- * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS))' %
- * (axis_0_pos, axis_1_pos))
- * if len(axises) > 2:
- * for axis_2 in axises:
- * axis_2_pos = axis_pos[axis_2]
- * axis_dict[axis_0 + axis_1 + axis_2] = (
- * '((%s | SWIZZLE_VALID_AXIS) | '
- * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS) | '
- * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 2)))' %
- * (axis_0_pos, axis_1_pos, axis_2_pos))
- * if len(axises) > 3:
- * for axis_3 in axises:
- * axis_3_pos = axis_pos[axis_3]
- * axis_dict[axis_0 + axis_1 + axis_2 + axis_3] = (
- * '((%s | SWIZZLE_VALID_AXIS) | '
- * '((%s | SWIZZLE_VALID_AXIS) << SWIZZLE_BITS_PER_AXIS) | '
- * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 2)) | '
- * '((%s | SWIZZLE_VALID_AXIS) << (SWIZZLE_BITS_PER_AXIS * 3))) ' %
- * (axis_0_pos, axis_1_pos, axis_2_pos, axis_3_pos))
- *
- * axises = axises[:-1]
- *
- *
- * items = list(axis_dict.items())
- * items.sort(key=lambda a: a[0].replace('x', '0').replace('y', '1').replace('z', '2').replace('w', '3'))
- *
- * unique = set()
- * for key, val in items:
- * num = eval(val)
- * set_str = 'Vector_swizzle_set' if (len(set(key)) == len(key)) else 'NULL'
- * key_args = ', '.join(["'%s'" % c for c in key.upper()])
- * print('\t{(char *)"%s", %s(getter)Vector_swizzle_get, (setter)%s, NULL, SWIZZLE%d(%s)},' %
- * (key, (' ' * (4 - len(key))), set_str, len(key), key_args))
- * unique.add(num)
- *
- * if len(unique) != len(items):
- * print("ERROR, duplicate values found")
- * \endcode
- */
-
-/* ROW VECTOR Multiplication - Vector X Matrix
+ * Row vector multiplication - (Vector * Matrix)
+ * <pre>
* [x][y][z] * [1][4][7]
* [2][5][8]
* [3][6][9]
- * vector/matrix multiplication IS NOT COMMUTATIVE!!!! */
+ * </pre>
+ * \note vector/matrix multiplication is not commutative.
+ */
static int row_vector_multiplication(float r_vec[MAX_DIMENSIONS], VectorObject *vec, MatrixObject *mat)
{
float vec_cpy[MAX_DIMENSIONS];
@@ -2864,10 +2881,11 @@ static struct PyMethodDef Vector_methods[] = {
};
-/* Note
- * Py_TPFLAGS_CHECKTYPES allows us to avoid casting all types to Vector when coercing
- * but this m
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list