API Docs: Fix corrupted document of gpu.select.load_id
[blender.git] / source / blender / python / generic / bl_math_py_api.c
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 /**
18  * \file
19  * \ingroup pygen
20  *
21  * This file defines the 'bl_math' module, a module for math utilities.
22  */
23
24 #include <Python.h>
25
26 #include "BLI_math.h"
27 #include "BLI_utildefines.h"
28
29 #include "py_capi_utils.h"
30
31 #include "bl_math_py_api.h"
32
33 /* -------------------------------------------------------------------- */
34 /** \name Module Doc String
35  * \{ */
36
37 PyDoc_STRVAR(M_bl_math_doc, "Miscellaneous math utilities module");
38
39 /** \} */
40
41 /* -------------------------------------------------------------------- */
42 /** \name Python Functions
43  * \{ */
44
45 PyDoc_STRVAR(py_bl_math_clamp_doc,
46              ".. function:: clamp(value, min=0, max=1)\n"
47              "\n"
48              "   Clamps the float value between minimum and maximum. To avoid\n"
49              "   confusion, any call must use either one or all three arguments.\n"
50              "\n"
51              "   :arg value: The value to clamp.\n"
52              "   :type value: float\n"
53              "   :arg min: The minimum value, defaults to 0.\n"
54              "   :type min: float\n"
55              "   :arg max: The maximum value, defaults to 1.\n"
56              "   :type max: float\n"
57              "   :return: The clamped value.\n"
58              "   :rtype: float\n");
59 static PyObject *py_bl_math_clamp(PyObject *UNUSED(self), PyObject *args)
60 {
61   double x, minv = 0.0, maxv = 1.0;
62
63   if (PyTuple_Size(args) <= 1) {
64     if (!PyArg_ParseTuple(args, "d:clamp", &x)) {
65       return NULL;
66     }
67   }
68   else {
69     if (!PyArg_ParseTuple(args, "ddd:clamp", &x, &minv, &maxv)) {
70       return NULL;
71     }
72   }
73
74   CLAMP(x, minv, maxv);
75
76   return PyFloat_FromDouble(x);
77 }
78
79 PyDoc_STRVAR(py_bl_math_lerp_doc,
80              ".. function:: lerp(from, to, factor)\n"
81              "\n"
82              "   Linearly interpolate between two float values based on factor.\n"
83              "\n"
84              "   :arg from: The value to return when factor is 0.\n"
85              "   :type from: float\n"
86              "   :arg to: The value to return when factor is 1.\n"
87              "   :type to: float\n"
88              "   :arg factor: The interpolation value, normally in [0.0, 1.0].\n"
89              "   :type factor: float\n"
90              "   :return: The interpolated value.\n"
91              "   :rtype: float\n");
92 static PyObject *py_bl_math_lerp(PyObject *UNUSED(self), PyObject *args)
93 {
94   double a, b, x;
95   if (!PyArg_ParseTuple(args, "ddd:lerp", &a, &b, &x)) {
96     return NULL;
97   }
98
99   return PyFloat_FromDouble(a * (1.0 - x) + b * x);
100 }
101
102 PyDoc_STRVAR(
103     py_bl_math_smoothstep_doc,
104     ".. function:: smoothstep(from, to, value)\n"
105     "\n"
106     "   Performs smooth interpolation between 0 and 1 as value changes between from and to.\n"
107     "   Outside the range the function returns the same value as the nearest edge.\n"
108     "\n"
109     "   :arg from: The edge value where the result is 0.\n"
110     "   :type from: float\n"
111     "   :arg to: The edge value where the result is 1.\n"
112     "   :type to: float\n"
113     "   :arg factor: The interpolation value.\n"
114     "   :type factor: float\n"
115     "   :return: The interpolated value in [0.0, 1.0].\n"
116     "   :rtype: float\n");
117 static PyObject *py_bl_math_smoothstep(PyObject *UNUSED(self), PyObject *args)
118 {
119   double a, b, x;
120   if (!PyArg_ParseTuple(args, "ddd:smoothstep", &a, &b, &x)) {
121     return NULL;
122   }
123
124   double t = (x - a) / (b - a);
125
126   CLAMP(t, 0.0, 1.0);
127
128   return PyFloat_FromDouble(t * t * (3.0 - 2.0 * t));
129 }
130
131 /** \} */
132
133 /* -------------------------------------------------------------------- */
134 /** \name Module Definition
135  * \{ */
136
137 static PyMethodDef M_bl_math_methods[] = {
138     {"clamp", (PyCFunction)py_bl_math_clamp, METH_VARARGS, py_bl_math_clamp_doc},
139     {"lerp", (PyCFunction)py_bl_math_lerp, METH_VARARGS, py_bl_math_lerp_doc},
140     {"smoothstep", (PyCFunction)py_bl_math_smoothstep, METH_VARARGS, py_bl_math_smoothstep_doc},
141     {NULL, NULL, 0, NULL},
142 };
143
144 static struct PyModuleDef M_bl_math_module_def = {
145     PyModuleDef_HEAD_INIT,
146     "bl_math",         /* m_name */
147     M_bl_math_doc,     /* m_doc */
148     0,                 /* m_size */
149     M_bl_math_methods, /* m_methods */
150     NULL,              /* m_reload */
151     NULL,              /* m_traverse */
152     NULL,              /* m_clear */
153     NULL,              /* m_free */
154 };
155
156 PyMODINIT_FUNC BPyInit_bl_math(void)
157 {
158   PyObject *submodule = PyModule_Create(&M_bl_math_module_def);
159   return submodule;
160 }
161
162 /** \} */