archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Merged changes in the trunk up to revision 26409.

Browse Source
This commit is contained in:
Tamito Kajiyama
2010-01-30 02:58:48 +00:00
parent 972650d983 ada9ca9687
commit 2d8ee7efa3
294 changed files with 6032 additions and 3786 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
source/blender/python/doc/epy/Mathutils.py
View File

@@ -33,15 +33,6 @@ 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
@@ -106,11 +97,6 @@ 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:
@@ -152,16 +138,6 @@ 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
@@ -215,10 +191,6 @@ 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

36
source/blender/python/generic/Mathutils.c
View File

@@ -137,9 +137,9 @@ static char M_Mathutils_RotationMatrix_doc[] =
" :arg size: The size of the rotation matrix to construct [2, 4].\n"
" :type size: int\n"
" :arg axis: a string in ['X', 'Y', 'Z'] or a 3D Vector Object (optional when size is 2).\n"
" :type axis: string or vector\n"
" :type axis: string or :class:`Vector`\n"
" :return: A new rotation matrix.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *M_Mathutils_RotationMatrix(PyObject * self, PyObject * args)
{
@@ -207,7 +207,11 @@ static PyObject *M_Mathutils_RotationMatrix(PyObject * self, PyObject * args)
angle = angle * (float) (Py_PI / 180);
#endif
if(axis == NULL && matSize == 2) {
/* check for valid vector/axis above */
if(vec) {
axis_angle_to_mat3( (float (*)[3])mat,vec->vec, angle);
}
else if(matSize == 2) {
//2D rotation matrix
mat[0] = (float) cos (angle);
mat[1] = (float) sin (angle);
@@ -234,9 +238,11 @@ static PyObject *M_Mathutils_RotationMatrix(PyObject * self, PyObject * args)
mat[3] = -((float) sin(angle));
mat[4] = (float) cos(angle);
mat[8] = 1.0f;
} else {
/* check for valid vector/axis above */
axis_angle_to_mat3( (float (*)[3])mat,vec->vec, angle);
}
else {
/* should never get here */
PyErr_SetString(PyExc_AttributeError, "Mathutils.RotationMatrix(): unknown error\n");
return NULL;
}
if(matSize == 4) {
@@ -260,9 +266,9 @@ static char M_Mathutils_TranslationMatrix_doc[] =
" Create a matrix representing a translation.\n"
"\n"
" :arg vector: The translation vector.\n"
" :type vector: Vector\n"
" :type vector: :class:`Vector`\n"
" :return: An identity matrix with a translation.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *M_Mathutils_TranslationMatrix(PyObject * self, VectorObject * vec)
{
@@ -301,9 +307,9 @@ static char M_Mathutils_ScaleMatrix_doc[] =
" :arg size: The size of the scale matrix to construct [2, 4].\n"
" :type size: int\n"
" :arg axis: Direction to influence scale. (optional).\n"
" :type axis: Vector\n"
" :type axis: :class:`Vector`\n"
" :return: A new scale matrix.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *M_Mathutils_ScaleMatrix(PyObject * self, PyObject * args)
{
@@ -391,10 +397,10 @@ static char M_Mathutils_OrthoProjectionMatrix_doc[] =
" :type plane: string\n"
" :arg size: The size of the projection matrix to construct [2, 4].\n"
" :type size: int\n"
" :arg axis: Arbitrary perpendicular plane vector.\n"
" :type axis: vector (optional)\n"
" :arg axis: Arbitrary perpendicular plane vector (optional).\n"
" :type axis: :class:`Vector`\n"
" :return: A new projection matrix.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *M_Mathutils_OrthoProjectionMatrix(PyObject * self, PyObject * args)
{
VectorObject *vec = NULL;
@@ -496,7 +502,7 @@ static char M_Mathutils_ShearMatrix_doc[] =
" :arg size: The size of the shear matrix to construct [2, 4].\n"
" :type size: int\n"
" :return: A new shear matrix.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *M_Mathutils_ShearMatrix(PyObject * self, PyObject * args)
{
@@ -655,6 +661,7 @@ int _BaseMathObject_WriteIndexCallback(BaseMathObject *self, int index)
}
/* BaseMathObject generic functions for all mathutils types */
char BaseMathObject_Owner_doc[] = "The item this is wrapping or None (readonly).";
PyObject *BaseMathObject_getOwner( BaseMathObject * self, void *type )
{
PyObject *ret= self->cb_user ? self->cb_user : Py_None;
@@ -662,6 +669,7 @@ PyObject *BaseMathObject_getOwner( BaseMathObject * self, void *type )
return ret;
}
char BaseMathObject_Wrapped_doc[] = "True when this object wraps external data (readonly). **type** boolean";
PyObject *BaseMathObject_getWrapped( BaseMathObject *self, void *type )
{
return PyBool_FromLong((self->wrapped == Py_WRAP) ? 1:0);

3
source/blender/python/generic/Mathutils.h
View File

@@ -41,6 +41,9 @@
/* Can cast different mathutils types to this, use for generic funcs */
extern char BaseMathObject_Wrapped_doc[];
extern char BaseMathObject_Owner_doc[];
typedef struct {
PyObject_VAR_HEAD
float *data; /*array of data (alias), wrapped status depends on wrapped status */

31
source/blender/python/generic/euler.c
View File

@@ -92,7 +92,7 @@ static char Euler_ToQuat_doc[] =
" Return a quaternion representation of the euler.\n"
"\n"
" :return: Quaternion representation of the euler.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Euler_ToQuat(EulerObject * self)
{
@@ -124,7 +124,7 @@ static char Euler_ToMatrix_doc[] =
" Return a matrix representation of the euler.\n"
"\n"
" :return: A 3x3 roation matrix representation of the euler.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *Euler_ToMatrix(EulerObject * self)
{
@@ -155,8 +155,9 @@ static char Euler_Unique_doc[] =
".. method:: unique()\n"
"\n"
" Calculate a unique rotation for this euler. Avoids gimble lock.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Euler\n";
" :rtype: :class:`Euler`\n";
static PyObject *Euler_Unique(EulerObject * self)
{
@@ -226,8 +227,9 @@ static char Euler_Zero_doc[] =
".. method:: zero()\n"
"\n"
" Set all values to zero.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Euler\n";
" :rtype: :class:`Euler`\n";
static PyObject *Euler_Zero(EulerObject * self)
{
@@ -293,9 +295,9 @@ static char Euler_MakeCompatible_doc[] =
" Make this euler compatible with another, so interpolating between them works as intended.\n"
"\n"
" :arg other: make compatible with this rotation.\n"
" :type other: Euler\n"
" :type other: :class:`Euler`\n"
" :return: an instance of itself.\n"
" :rtype: Euler\n";
" :rtype: :class:`Euler`\n";
static PyObject *Euler_MakeCompatible(EulerObject * self, EulerObject *value)
{
@@ -343,7 +345,7 @@ static char Euler_copy_doc[] =
" Returns a copy of this euler.\n"
"\n"
" :return: A copy of the euler.\n"
" :rtype: Euler\n"
" :rtype: :class:`Euler`\n"
"\n"
" .. note:: use this to get a copy of a wrapped euler with no reference to the original data.\n";
@@ -551,7 +553,6 @@ static PySequenceMethods Euler_SeqMethods = {
/*
* vector axis, vector.x/y/z/w
*/
static PyObject *Euler_getAxis( EulerObject * self, void *type )
{
return Euler_item(self, GET_INT_FROM_POINTER(type));
@@ -566,12 +567,12 @@ static int Euler_setAxis( EulerObject * self, PyObject * value, void * type )
/* Python attributes get/set structure: */
/*****************************************************************************/
static PyGetSetDef Euler_getseters[] = {
{"x", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler X axis", (void *)0},
{"y", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Y axis", (void *)1},
{"z", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Z axis", (void *)2},
{"x", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler X axis in radians. **type** float", (void *)0},
{"y", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Y axis in radians. **type** float", (void *)1},
{"z", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Z axis in radians. **type** float", (void *)2},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "True when this wraps blenders internal data", NULL},
{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, "Read only owner for vectors that depend on another object", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
{NULL,NULL,NULL,NULL,NULL} /* Sentinel */
};
@@ -590,6 +591,8 @@ static struct PyMethodDef Euler_methods[] = {
};
//------------------PY_OBECT DEFINITION--------------------------
static char euler_doc[] = "This object gives access to Eulers in Blender.";
PyTypeObject euler_Type = {
PyVarObject_HEAD_INIT(NULL, 0)
"euler", //tp_name
@@ -611,7 +614,7 @@ PyTypeObject euler_Type = {
0, //tp_setattro
0, //tp_as_buffer
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, //tp_flags
0, //tp_doc
euler_doc, //tp_doc
0, //tp_traverse
0, //tp_clear
(richcmpfunc)Euler_richcmpr, //tp_richcompare

49
source/blender/python/generic/matrix.c
View File

@@ -206,7 +206,7 @@ static char Matrix_toQuat_doc[] =
" Return a quaternion representation of the rotation matrix.\n"
"\n"
" :return: Quaternion representation of the rotation matrix.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Matrix_toQuat(MatrixObject * self)
{
@@ -235,9 +235,9 @@ static char Matrix_toEuler_doc[] =
" Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).\n"
"\n"
" :arg euler_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.\n"
" :type euler_compat: Euler\n"
" :type euler_compat: :class:`Euler`\n"
" :return: Euler representation of the matrix.\n"
" :rtype: Euler\n";
" :rtype: :class:`Euler`\n";
PyObject *Matrix_toEuler(MatrixObject * self, PyObject *args)
{
@@ -294,8 +294,9 @@ static char Matrix_Resize4x4_doc[] =
".. method:: resize4x4()\n"
"\n"
" Resize the matrix to 4x4.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Vector\n";
" :rtype: :class:`Vector`\n";
PyObject *Matrix_Resize4x4(MatrixObject * self)
{
@@ -358,8 +359,9 @@ static char Matrix_TranslationPart_doc[] =
".. method:: translation_part()\n"
"\n"
" Return a the translation part of a 4 row matrix.\n"
"\n"
" :return: Return a the translation of a matrix.\n"
" :rtype: Matrix\n"
" :rtype: :class:`Matrix`\n"
"\n"
" .. note:: Note that the (4,4) element of a matrix can be used for uniform scaling too.\n";
@@ -386,8 +388,9 @@ static char Matrix_RotationPart_doc[] =
".. method:: rotation_part()\n"
"\n"
" Return the 3d submatrix corresponding to the linear term of the embedded affine transformation in 3d. This matrix represents rotation and scale.\n"
"\n"
" :return: Return the 3d matrix for rotation and scale.\n"
" :rtype: Matrix\n"
" :rtype: :class:`Matrix`\n"
"\n"
" .. note:: Note that the (4,4) element of a matrix can be used for uniform scaling too.\n";
@@ -421,8 +424,9 @@ static char Matrix_scalePart_doc[] =
".. method:: scale_part()\n"
"\n"
" Return a the scale part of a 3x3 or 4x4 matrix.\n"
"\n"
" :return: Return a the scale of a matrix.\n"
" :rtype: Vector\n"
" :rtype: :class:`Vector`\n"
"\n"
" .. 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.\n";
@@ -459,8 +463,9 @@ static char Matrix_Invert_doc[] =
".. method:: invert()\n"
"\n"
" Set the matrix to its inverse.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Matrix\n"
" :rtype: :class:`Matrix`\n"
"\n"
" .. note:: :exc:`ValueError` exception is raised.\n"
"\n"
@@ -526,6 +531,7 @@ static char Matrix_Determinant_doc[] =
".. method:: determinant()\n"
"\n"
" Return the determinant of a matrix.\n"
"\n"
" :return: Return a the determinant of a matrix.\n"
" :rtype: float\n"
"\n"
@@ -548,8 +554,9 @@ static char Matrix_Transpose_doc[] =
".. method:: transpose()\n"
"\n"
" Set the matrix to its transpose.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Matrix\n"
" :rtype: :class:`Matrix`\n"
"\n"
" .. seealso:: <http://en.wikipedia.org/wiki/Transpose>\n";
@@ -586,8 +593,9 @@ static char Matrix_Zero_doc[] =
".. method:: zero()\n"
"\n"
" Set all the matrix values to zero.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
PyObject *Matrix_Zero(MatrixObject * self)
{
@@ -610,8 +618,9 @@ static char Matrix_Identity_doc[] =
".. method:: identity()\n"
"\n"
" Set the matrix to the identity matrix.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Matrix\n"
" :rtype: :class:`Matrix`\n"
"\n"
" .. note:: An object with zero location and rotation, a scale of one, will have an identity matrix.\n"
"\n"
@@ -650,8 +659,9 @@ static char Matrix_copy_doc[] =
".. method:: copy()\n"
"\n"
" Returns a copy of this matrix.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
PyObject *Matrix_copy(MatrixObject * self)
{
@@ -1225,12 +1235,11 @@ static PyObject *Matrix_getMedianScale( MatrixObject * self, void *type )
/* Python attributes get/set structure: */
/*****************************************************************************/
static PyGetSetDef Matrix_getseters[] = {
{"row_size", (getter)Matrix_getRowSize, (setter)NULL, "", NULL},
{"col_size", (getter)Matrix_getColSize, (setter)NULL, "", NULL},
{"median_scale", (getter)Matrix_getMedianScale, (setter)NULL, "", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "", NULL},
{"_owner",(getter)BaseMathObject_getOwner, (setter)NULL, "",
NULL},
{"row_size", (getter)Matrix_getRowSize, (setter)NULL, "The row size of the matrix (readonly). **type** int", NULL},
{"col_size", (getter)Matrix_getColSize, (setter)NULL, "The column size of the matrix (readonly). **type** int", NULL},
{"median_scale", (getter)Matrix_getMedianScale, (setter)NULL, "The average scale applied to each axis (readonly). **type** float", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
{"_owner",(getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
{NULL,NULL,NULL,NULL,NULL} /* Sentinel */
};
@@ -1253,6 +1262,8 @@ static struct PyMethodDef Matrix_methods[] = {
};
/*------------------PY_OBECT DEFINITION--------------------------*/
static char matrix_doc[] = "This object gives access to Matrices in Blender.";
PyTypeObject matrix_Type = {
PyVarObject_HEAD_INIT(NULL, 0)
"matrix", /*tp_name*/
@@ -1274,7 +1285,7 @@ PyTypeObject matrix_Type = {
0, /*tp_setattro*/
0, /*tp_as_buffer*/
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
0, /*tp_doc*/
matrix_doc, /*tp_doc*/
0, /*tp_traverse*/
0, /*tp_clear*/
(richcmpfunc)Matrix_richcmpr, /*tp_richcompare*/

56
source/blender/python/generic/quat.c
View File

@@ -39,9 +39,9 @@ static char Quaternion_ToEuler_doc[] =
" Return Euler representation of the quaternion.\n"
"\n"
" :arg euler_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.\n"
" :type euler_compat: Euler\n"
" :type euler_compat: :class:`Euler`\n"
" :return: Euler representation of the quaternion.\n"
" :rtype: Euler\n";
" :rtype: :class:`Euler`\n";
static PyObject *Quaternion_ToEuler(QuaternionObject * self, PyObject *args)
{
@@ -98,7 +98,7 @@ static char Quaternion_ToMatrix_doc[] =
" Return a matrix representation of the quaternion.\n"
"\n"
" :return: A 3x3 rotation matrix representation of the quaternion.\n"
" :rtype: Matrix\n";
" :rtype: :class:`Matrix`\n";
static PyObject *Quaternion_ToMatrix(QuaternionObject * self)
{
@@ -118,9 +118,9 @@ static char Quaternion_Cross_doc[] =
" Return the cross product of this quaternion and another.\n"
"\n"
" :arg other: The other quaternion to perform the cross product with.\n"
" :type other: Quaternion\n"
" :type other: :class:`Quaternion`\n"
" :return: The cross product.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Cross(QuaternionObject * self, QuaternionObject * value)
{
@@ -145,9 +145,9 @@ static char Quaternion_Dot_doc[] =
" Return the dot product of this quaternion and another.\n"
"\n"
" :arg other: The other quaternion to perform the dot product with.\n"
" :type other: Quaternion\n"
" :type other: :class:`Quaternion`\n"
" :return: The dot product.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Dot(QuaternionObject * self, QuaternionObject * value)
{
@@ -168,9 +168,9 @@ static char Quaternion_Difference_doc[] =
" Returns a quaternion representing the rotational difference.\n"
"\n"
" :arg other: second quaternion.\n"
" :type other: Quaternion\n"
" :type other: :class:`Quaternion`\n"
" :return: the rotational difference between the two quat rotations.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Difference(QuaternionObject * self, QuaternionObject * value)
{
@@ -207,11 +207,11 @@ static char Quaternion_Slerp_doc[] =
" Returns the interpolation of two quaternions.\n"
"\n"
" :arg other: value to interpolate with.\n"
" :type other: Quaternion\n"
" :type other: :class:`Quaternion`\n"
" :arg factor: The interpolation value in [0.0, 1.0].\n"
" :type factor: float\n"
" :return: The interpolated rotation.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Slerp(QuaternionObject *self, PyObject *args)
{
@@ -244,7 +244,7 @@ static char Quaternion_Normalize_doc[] =
" Normalize the quaternion.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Normalize(QuaternionObject * self)
{
@@ -264,7 +264,7 @@ static char Quaternion_Inverse_doc[] =
" Set the quaternion to its inverse.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Inverse(QuaternionObject * self)
{
@@ -284,7 +284,7 @@ static char Quaternion_Identity_doc[] =
" Set the quaternion to an identity quaternion.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Identity(QuaternionObject * self)
{
@@ -304,7 +304,7 @@ static char Quaternion_Negate_doc[] =
" Set the quaternion to its negative.\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Negate(QuaternionObject * self)
{
@@ -324,7 +324,7 @@ static char Quaternion_Conjugate_doc[] =
" Set the quaternion to its conjugate (negate x, y, z).\n"
"\n"
" :return: an instance of itself.\n"
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Quaternion_Conjugate(QuaternionObject * self)
{
@@ -344,7 +344,7 @@ static char Quaternion_copy_doc[] =
" Returns a copy of this quaternion.\n"
"\n"
" :return: A copy of the quaternion.\n"
" :rtype: Quaternion\n"
" :rtype: :class:`Quaternion`\n"
"\n"
" .. note:: use this to get a copy of a wrapped quaternion with no reference to the original data.\n";
@@ -847,19 +847,21 @@ static struct PyMethodDef Quaternion_methods[] = {
/* Python attributes get/set structure: */
/*****************************************************************************/
static PyGetSetDef Quaternion_getseters[] = {
{"w", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion W value", (void *)0},
{"x", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion X axis", (void *)1},
{"y", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Y axis", (void *)2},
{"z", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Z axis", (void *)3},
{"magnitude", (getter)Quaternion_getMagnitude, (setter)NULL, "Size of the quaternion", NULL},
{"angle", (getter)Quaternion_getAngle, (setter)NULL, "angle of the quaternion", NULL},
{"axis",(getter)Quaternion_getAxisVec, (setter)NULL, "quaternion axis as a vector", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "True when this wraps blenders internal data", NULL},
{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, "Read only owner for vectors that depend on another object", NULL},
{"w", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion W value. **type** float", (void *)0},
{"x", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion X axis. **type** float", (void *)1},
{"y", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Y axis. **type** float", (void *)2},
{"z", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Z axis. **type** float", (void *)3},
{"magnitude", (getter)Quaternion_getMagnitude, (setter)NULL, "Size of the quaternion (readonly). **type** float", NULL},
{"angle", (getter)Quaternion_getAngle, (setter)NULL, "angle of the quaternion (readonly). **type** float", NULL},
{"axis",(getter)Quaternion_getAxisVec, (setter)NULL, "quaternion axis as a vector (readonly). **type** :class:`Vector`", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
{NULL,NULL,NULL,NULL,NULL} /* Sentinel */
};
//------------------PY_OBECT DEFINITION--------------------------
static char quaternion_doc[] = "This object gives access to Quaternions in Blender.";
PyTypeObject quaternion_Type = {
PyVarObject_HEAD_INIT(NULL, 0)
"quaternion", //tp_name
@@ -881,7 +883,7 @@ PyTypeObject quaternion_Type = {
0, //tp_setattro
0, //tp_as_buffer
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, //tp_flags
0, //tp_doc
quaternion_doc, //tp_doc
0, //tp_traverse
0, //tp_clear
(richcmpfunc)Quaternion_richcmpr, //tp_richcompare

124
source/blender/python/generic/vector.c
View File

@@ -97,8 +97,9 @@ static char Vector_Zero_doc[] =
".. method:: zero()\n"
"\n"
" Set all values to zero.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Zero(VectorObject * self)
{
@@ -116,8 +117,9 @@ static char Vector_Normalize_doc[] =
".. method:: normalize()\n"
"\n"
" Normalize the vector, making the length of the vector always 1.0.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n"
" :rtype: :class:`Vector`\n"
"\n"
" .. warning:: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).\n"
"\n"
@@ -150,8 +152,9 @@ static char Vector_Resize2D_doc[] =
".. method:: resize2D()\n"
"\n"
" Resize the vector to 2D (x, y).\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Resize2D(VectorObject * self)
{
@@ -179,8 +182,9 @@ static char Vector_Resize3D_doc[] =
".. method:: resize3D()\n"
"\n"
" Resize the vector to 3D (x, y, z).\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Resize3D(VectorObject * self)
{
@@ -211,8 +215,9 @@ static char Vector_Resize4D_doc[] =
".. method:: resize4D()\n"
"\n"
" Resize the vector to 4D (x, y, z, w).\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Resize4D(VectorObject * self)
{
@@ -287,7 +292,7 @@ static char Vector_ToTrackQuat_doc[] =
" :arg up: Up axis in ['X', 'Y', 'Z'].\n"
" :type up: string\n"
" :return: rotation from the vector and the track and up axis."
" :rtype: Quaternion\n";
" :rtype: :class:`Quaternion`\n";
static PyObject *Vector_ToTrackQuat( VectorObject * self, PyObject * args )
{
@@ -404,9 +409,9 @@ static char Vector_Reflect_doc[] =
" Return the reflection vector from the *mirror* argument.\n"
"\n"
" :arg mirror: This vector could be a normal from the reflecting surface.\n"
" :type mirror: vector\n"
" :return: The reflected vector.\n"
" :rtype: Vector object matching the size of this vector.\n";
" :type mirror: :class:`Vector`\n"
" :return: The reflected vector matching the size of this vector.\n"
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Reflect( VectorObject * self, VectorObject * value )
{
@@ -443,9 +448,9 @@ static char Vector_Cross_doc[] =
" Return the cross product of this vector and another.\n"
"\n"
" :arg other: The other vector to perform the cross product with.\n"
" :type other: vector\n"
" :type other: :class:`Vector`\n"
" :return: The cross product.\n"
" :rtype: Vector\n"
" :rtype: :class:`Vector`\n"
"\n"
" .. note:: both vectors must be 3D\n";
@@ -477,9 +482,9 @@ static char Vector_Dot_doc[] =
" Return the dot product of this vector and another.\n"
"\n"
" :arg other: The other vector to perform the dot product with.\n"
" :type other: vector\n"
" :type other: :class:`Vector`\n"
" :return: The dot product.\n"
" :rtype: Vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Dot( VectorObject * self, VectorObject * value )
{
@@ -510,7 +515,7 @@ static char Vector_Angle_doc[] =
"\n"
" Return the angle between two vectors.\n"
"\n"
" :type other: vector\n"
" :type other: :class:`Vector`\n"
" :return angle: angle in radians\n"
" :rtype: float\n"
"\n"
@@ -560,14 +565,51 @@ static PyObject *Vector_Angle(VectorObject * self, VectorObject * value)
#endif
}
static char Vector_Difference_doc[] =
".. function:: difference(other)\n"
"\n"
" Returns a quaternion representing the rotational difference between this vector and another.\n"
"\n"
" :arg other: second vector.\n"
" :type other: :class:`Vector`\n"
" :return: the rotational difference between the two vectors.\n"
" :rtype: :class:`Quaternion`\n"
"\n"
" .. note:: 2D vectors raise an :exc:`AttributeError`.\n";;
static PyObject *Vector_Difference( VectorObject * self, VectorObject * value )
{
float quat[4], vec_a[3], vec_b[3];
if (!VectorObject_Check(value)) {
PyErr_SetString( PyExc_TypeError, "vec.difference(value): expected a vector argument" );
return NULL;
}
if(self->size < 3 || value->size < 3) {
PyErr_SetString(PyExc_AttributeError, "vec.difference(value): expects both vectors to be size 3 or 4\n");
return NULL;
}
if(!BaseMath_ReadCallback(self) || !BaseMath_ReadCallback(value))
return NULL;
normalize_v3_v3(vec_a, self->vec);
normalize_v3_v3(vec_b, value->vec);
rotation_between_vecs_to_quat(quat, vec_a, vec_b);
return newQuaternionObject(quat, Py_NEW, NULL);
}
static char Vector_Project_doc[] =
".. function:: project(other)\n"
"\n"
" Return the projection of this vector onto the *other*.\n"
"\n"
" :type other: vector\n"
" :type other: :class:`Vector`\n"
" :return projection: the parallel projection vector\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Project(VectorObject * self, VectorObject * value)
{
@@ -612,11 +654,11 @@ static char Vector_Lerp_doc[] =
" Returns the interpolation of two vectors.\n"
"\n"
" :arg other: value to interpolate with.\n"
" :type other: Vector\n"
" :type other: :class:`Vector`\n"
" :arg factor: The interpolation value in [0.0, 1.0].\n"
" :type factor: float\n"
" :return: The interpolated rotation.\n"
" :rtype: Vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Lerp(VectorObject * self, PyObject * args)
{
@@ -651,7 +693,7 @@ static char Vector_copy_doc[] =
" Returns a copy of this vector.\n"
"\n"
" :return: A copy of the vector.\n"
" :rtype: Vector\n"
" :rtype: :class:`Vector`\n"
"\n"
" .. note:: use this to get a copy of a wrapped vector with no reference to the original data.\n";
@@ -1587,38 +1629,14 @@ static int Vector_setSwizzle(VectorObject * self, PyObject * value, void *closur
/* Python attributes get/set structure: */
/*****************************************************************************/
static PyGetSetDef Vector_getseters[] = {
{"x",
(getter)Vector_getAxis, (setter)Vector_setAxis,
"Vector X axis",
(void *)0},
{"y",
(getter)Vector_getAxis, (setter)Vector_setAxis,
"Vector Y axis",
(void *)1},
{"z",
(getter)Vector_getAxis, (setter)Vector_setAxis,
"Vector Z axis",
(void *)2},
{"w",
(getter)Vector_getAxis, (setter)Vector_setAxis,
"Vector Z axis",
(void *)3},
{"length",
(getter)Vector_getLength, (setter)Vector_setLength,
"Vector Length",
NULL},
{"magnitude",
(getter)Vector_getLength, (setter)Vector_setLength,
"Vector Length",
NULL},
{"wrapped",
(getter)BaseMathObject_getWrapped, (setter)NULL,
"True when this wraps blenders internal data",
NULL},
{"_owner",
(getter)BaseMathObject_getOwner, (setter)NULL,
"Read only owner for vectors that depend on another object",
NULL},
{"x", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector X axis. **type** float", (void *)0},
{"y", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector Y axis. **type** float", (void *)1},
{"z", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector Z axis (3D Vectors only). **type** float", (void *)2},
{"w", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector W axis (4D Vectors only). **type** float", (void *)3},
{"length", (getter)Vector_getLength, (setter)Vector_setLength, "Vector Length. **type** float", NULL},
{"magnitude", (getter)Vector_getLength, (setter)Vector_setLength, "Vector Length. **type** float", NULL},
{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
/* autogenerated swizzle attrs, see python script below */
{"xx", (getter)Vector_getSwizzle, (setter)Vector_setSwizzle, NULL, SET_INT_IN_POINTER(((0|SWIZZLE_VALID_AXIS) | ((0|SWIZZLE_VALID_AXIS)<<SWIZZLE_BITS_PER_AXIS)))}, /* 36 */
@@ -2045,8 +2063,9 @@ static char Vector_Negate_doc[] =
".. method:: negate()\n"
"\n"
" Set all values to their negative.\n"
"\n"
" :return: an instance of itself\n"
" :rtype: vector\n";
" :rtype: :class:`Vector`\n";
static PyObject *Vector_Negate(VectorObject * self)
{
@@ -2076,6 +2095,7 @@ static struct PyMethodDef Vector_methods[] = {
{"cross", ( PyCFunction ) Vector_Cross, METH_O, Vector_Cross_doc},
{"dot", ( PyCFunction ) Vector_Dot, METH_O, Vector_Dot_doc},
{"angle", ( PyCFunction ) Vector_Angle, METH_O, Vector_Angle_doc},
{"difference", ( PyCFunction ) Vector_Difference, METH_O, Vector_Difference_doc},
{"project", ( PyCFunction ) Vector_Project, METH_O, Vector_Project_doc},
{"lerp", ( PyCFunction ) Vector_Lerp, METH_VARARGS, Vector_Lerp_doc},
{"copy", (PyCFunction) Vector_copy, METH_NOARGS, Vector_copy_doc},

2
source/blender/python/intern/bpy_interface.c
View File

@@ -220,7 +220,9 @@ static void bpy_init_modules( void )
/* bpy context */
{
bpy_context_module= ( BPy_StructRNA * ) PyObject_NEW( BPy_StructRNA, &pyrna_struct_Type );
RNA_pointer_create(NULL, &RNA_Context, NULL, &bpy_context_module->ptr);
bpy_context_module->freeptr= 0;
PyModule_AddObject(mod, "context", (PyObject *)bpy_context_module);
}

4
source/blender/python/intern/bpy_operator.c
View File

@@ -83,9 +83,7 @@ static PyObject *pyop_call( PyObject * self, PyObject * args)
error_val= -1;
}
else {
/* WM_operator_properties_create(&ptr, opname); */
/* Save another lookup */
RNA_pointer_create(NULL, ot->srna, NULL, &ptr);
WM_operator_properties_create_ptr(&ptr, ot);
if(kw && PyDict_Size(kw))
error_val= pyrna_pydict_to_props(&ptr, kw, 0, "Converting py args to operator properties: ");

77
source/blender/python/intern/bpy_rna.c
View File

@@ -371,11 +371,8 @@ static void pyrna_struct_dealloc( BPy_StructRNA *self )
{
if (self->freeptr && self->ptr.data) {
IDP_FreeProperty(self->ptr.data);
if (self->ptr.type != &RNA_Context)
{
MEM_freeN(self->ptr.data);
self->ptr.data= NULL;
}
MEM_freeN(self->ptr.data);
self->ptr.data= NULL;
}
/* Note, for subclassed PyObjects we cant just call PyObject_DEL() directly or it will crash */
@@ -785,11 +782,17 @@ int pyrna_py_to_prop(PointerRNA *ptr, PropertyRNA *prop, ParameterList *parms, v
StructRNA *ptype= RNA_property_pointer_type(ptr, prop);
int flag = RNA_property_flag(prop);
/* if property is an OperatorProperties pointer and value is a map, forward back to pyrna_pydict_to_props */
if (RNA_struct_is_a(ptype, &RNA_OperatorProperties) && PyDict_Check(value)) {
PointerRNA opptr = RNA_property_pointer_get(ptr, prop);
return pyrna_pydict_to_props(&opptr, value, 0, error_prefix);
}
if(!BPy_StructRNA_Check(value) && value != Py_None) {
PyErr_Format(PyExc_TypeError, "%.200s expected a %.200s type", error_prefix, RNA_struct_identifier(ptype));
return -1;
} else if((flag & PROP_NEVER_NULL) && value == Py_None) {
PyErr_Format(PyExc_TypeError, "%.200s does not suppory a 'None' assignment %.200s type", error_prefix, RNA_struct_identifier(ptype));
PyErr_Format(PyExc_TypeError, "%.200s does not support a 'None' assignment %.200s type", error_prefix, RNA_struct_identifier(ptype));
return -1;
} else {
BPy_StructRNA *param= (BPy_StructRNA*)value;
@@ -1354,6 +1357,8 @@ static int pyrna_prop_ass_subscript( BPy_PropertyRNA *self, PyObject *key, PyObj
PyErr_SetString(PyExc_AttributeError, "invalid key, key must be an int");
return -1;
}
RNA_property_update(BPy_GetContext(), &self->ptr, self->prop);
}
@@ -1892,43 +1897,49 @@ static PyObject *pyrna_struct_getattro( BPy_StructRNA *self, PyObject *pyname )
ret = pyrna_func_to_py((BPy_DummyPointerRNA *)self, func);
}
else if (self->ptr.type == &RNA_Context) {
PointerRNA newptr;
ListBase newlb;
int done;
bContext *C = self->ptr.data;
if(C==NULL) {
PyErr_Format( PyExc_AttributeError, "StructRNA Context is 'NULL', can't get \"%.200s\" from context", name);
ret= NULL;
}
else {
PointerRNA newptr;
ListBase newlb;
done= CTX_data_get(self->ptr.data, name, &newptr, &newlb);
int done= CTX_data_get(C, name, &newptr, &newlb);
if(done==1) { /* found */
if (newptr.data) {
ret = pyrna_struct_CreatePyObject(&newptr);
}
else if (newlb.first) {
CollectionPointerLink *link;
PyObject *linkptr;
if(done==1) { /* found */
if (newptr.data) {
ret = pyrna_struct_CreatePyObject(&newptr);
}
else if (newlb.first) {
CollectionPointerLink *link;
PyObject *linkptr;
ret = PyList_New(0);
ret = PyList_New(0);
for(link=newlb.first; link; link=link->next) {
linkptr= pyrna_struct_CreatePyObject(&link->ptr);
PyList_Append(ret, linkptr);
Py_DECREF(linkptr);
for(link=newlb.first; link; link=link->next) {
linkptr= pyrna_struct_CreatePyObject(&link->ptr);
PyList_Append(ret, linkptr);
Py_DECREF(linkptr);
}
}
else {
ret = Py_None;
Py_INCREF(ret);
}
}
else {
else if (done==-1) { /* found but not set */
ret = Py_None;
Py_INCREF(ret);
}
}
else if (done==-1) { /* found but not set */
ret = Py_None;
Py_INCREF(ret);
}
else { /* not found in the context */
/* lookup the subclass. raise an error if its not found */
ret = PyObject_GenericGetAttr((PyObject *)self, pyname);
}
else { /* not found in the context */
/* lookup the subclass. raise an error if its not found */
ret = PyObject_GenericGetAttr((PyObject *)self, pyname);
}
BLI_freelistN(&newlb);
BLI_freelistN(&newlb);
}
}
else {
#if 0

93
source/blender/python/sphinx_doc_gen.py
View File

@@ -27,6 +27,13 @@ This will generate python files in "./source/blender/python/doc/sphinx-in"
Generate html docs by running...
sphinx-build source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out
For PDF generation
sphinx-build -b latex source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out
cd source/blender/python/doc/sphinx-out
make
'''
@@ -130,8 +137,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
filepath = os.path.join(BASEPATH, module_name + ".rst")
file = open(filepath, "w")
print(filepath)
print(filepath)
fw = file.write
fw(title + "\n")
@@ -169,18 +175,29 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
if value.__doc__:
for l in value.__doc__.split("\n"):
fw(" %s\n" % l)
fw("\n")
fw("\n")
for key, descr in value.__dict__.items():
for key in sorted(value.__dict__.keys()):
if key.startswith("__"):
continue
descr = value.__dict__[key]
if type(descr) == GetSetDescriptorType:
if descr.__doc__:
fw(" .. attribute:: %s\n\n" % key)
for l in descr.__doc__.split("\n"):
fw(" %s\n" % l)
fw("\n")
descr_type = type(descr)
if descr_type in (MethodDescriptorType, ): # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
for key in sorted(value.__dict__.keys()):
if key.startswith("__"):
continue
descr = value.__dict__[key]
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
if descr.__doc__:
for l in descr.__doc__.split("\n"):
fw(" %s\n" % l)
fw("\n")
fw("\n\n")
file.close()
@@ -203,8 +220,12 @@ def rna2sphinx(BASEPATH):
fw("project = 'Blender 3D'\n")
# fw("master_doc = 'index'\n")
fw("copyright = u'Blender Foundation'\n")
fw("version = '2.5'\n")
fw("release = '2.5'\n")
fw("version = '%s'\n" % bpy.app.version_string)
fw("release = '%s'\n" % bpy.app.version_string)
fw("\n")
# needed for latex, pdf gen
fw("latex_documents = [ ('contents', 'contents.tex', 'Blender Index', 'Blender Foundation', 'manual'), ]\n")
fw("latex_paper_size = 'a4paper'\n")
file.close()
@@ -212,37 +233,70 @@ def rna2sphinx(BASEPATH):
file = open(filepath, "w")
fw = file.write
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw(" Blender Documentation contents\n")
fw("%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n")
fw("\n")
fw("This document is an API reference for Blender %s.\n" % bpy.app.version_string.split()[0])
fw("\n")
fw("An introduction to blender and python can be found at <http://wiki.blender.org/index.php/Dev:2.5/Py/API/Intro>\n")
fw("\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
#fw(" bpy.ops.*\n\n")
#fw(" bpy.types.*\n\n")
fw(" :maxdepth: 1\n\n")
fw(" bpy.ops.rst\n\n")
fw(" bpy.types.rst\n\n")
# py modules
fw(" bpy.utils\n\n")
fw(" bpy.app\n\n")
fw(" bpy.utils.rst\n\n")
fw(" bpy.app.rst\n\n")
# C modules
fw(" bpy.props\n\n")
fw(" bpy.props.rst\n\n")
fw(" Mathutils\n\n")
fw(" Mathutils.rst\n\n")
file.close()
# internal modules
filepath = os.path.join(BASEPATH, "bpy.ops.rst")
file = open(filepath, "w")
fw = file.write
fw("Blender Operators (bpy.ops)\n")
fw("===========================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.ops.*\n\n")
file.close()
filepath = os.path.join(BASEPATH, "bpy.types.rst")
file = open(filepath, "w")
fw = file.write
fw("Blender Types (bpy.types)\n")
fw("=========================\n\n")
fw(".. toctree::\n")
fw(" :glob:\n\n")
fw(" bpy.types.*\n\n")
file.close()
# python modules
from bpy import utils as module
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Blender Python Utilities")
pymodule2sphinx(BASEPATH, "bpy.utils", module, "Utilities (bpy.utils)")
from bpy import app as module
pymodule2sphinx(BASEPATH, "bpy.app", module, "Blender Python Application Constants")
pymodule2sphinx(BASEPATH, "bpy.app", module, "Application Data (bpy.app)")
from bpy import props as module
pymodule2sphinx(BASEPATH, "bpy.props", module, "Blender Python Property Definitions")
pymodule2sphinx(BASEPATH, "bpy.props", module, "Property Definitions (bpy.props)")
import Mathutils as module
pymodule2sphinx(BASEPATH, "Mathutils", module, "Module Mathutils")
pymodule2sphinx(BASEPATH, "Mathutils", module, "Math Types & Utilities (Mathutils)")
del module
if 0:
filepath = os.path.join(BASEPATH, "bpy.rst")
file = open(filepath, "w")
@@ -422,6 +476,7 @@ if __name__ == '__main__':
# os.system("rm source/blender/python/doc/sphinx-in/*.rst")
# os.system("rm -rf source/blender/python/doc/sphinx-out/*")
rna2sphinx('source/blender/python/doc/sphinx-in')
# os.system("rm source/blender/python/doc/sphinx-in/bpy.types.*.rst")
import sys
sys.exit()