blender
/
blender
135
403
Fork 585
Code Issues 6.3k Pull Requests 759 Projects 19 Wiki Activity

Python GPU: Improve the Python GPU API documentation 

This fixes some errors of continuity and consistency of formatting on
https://docs.blender.org/api/current/gpu.html

This also details the description of some parameters.

Differential Revision: https://developer.blender.org/D10531
This commit is contained in:
Germano Cavalcante 2021-03-16 12:48:00 -03:00
parent 6b6bcbe60c
commit b71b1ae384
11 changed files with 88 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
source/blender/python/gpu/gpu_py_batch.c
View File

@ -295,18 +295,10 @@ PyDoc_STRVAR(
"\n"
" Reusable container for drawable geometry.\n"
"\n"
" :arg type: One of these primitive types: {\n"
" `POINTS`,\n"
" `LINES`,\n"
" `TRIS`,\n"
" `LINE_STRIP`,\n"
" `LINE_LOOP`,\n"
" `TRI_STRIP`,\n"
" `TRI_FAN`,\n"
" `LINES_ADJ`,\n"
" `TRIS_ADJ`,\n"
" `LINE_STRIP_ADJ` }\n"
" :type type: `str`\n"
" :arg type: The primitive type of geometry to be drawn.\n"
" Possible values are `POINTS`, `LINES`, `TRIS`, `LINE_STRIP`, `LINE_LOOP`, `TRI_STRIP`, "
"`TRI_FAN`, `LINES_ADJ`, `TRIS_ADJ` and `LINE_STRIP_ADJ`.\n"
" :type type: str\n"
" :arg buf: Vertex buffer containing all or some of the attributes required for drawing.\n"
" :type buf: :class:`gpu.types.GPUVertBuf`\n"
" :arg elem: An optional index buffer.\n"

30
source/blender/python/gpu/gpu_py_buffer.c
View File

@ -589,23 +589,19 @@ static PyBufferProcs pygpu_buffer__tp_as_buffer = {
};
#endif
PyDoc_STRVAR(pygpu_buffer__tp_doc,
".. class:: Buffer(format, dimensions, data)\n"
"\n"
" For Python access to GPU functions requiring a pointer.\n"
"\n"
" :arg format: One of these primitive types: {\n"
" `FLOAT`,\n"
" `INT`,\n"
" `UINT`,\n"
" `UBYTE`,\n"
" `UINT_24_8`,\n"
" `10_11_11_REV`,\n"
" :type type: `str`\n"
" :arg dimensions: Array describing the dimensions.\n"
" :type dimensions: `int`\n"
" :arg data: Optional data array.\n"
" :type data: `array`\n");
PyDoc_STRVAR(
pygpu_buffer__tp_doc,
".. class:: Buffer(format, dimensions, data)\n"
"\n"
" For Python access to GPU functions requiring a pointer.\n"
"\n"
" :arg format: Format type to interpret the buffer.\n"
" Possible values are `FLOAT`, `INT`, `UINT`, `UBYTE`, `UINT_24_8` and `10_11_11_REV`.\n"
" :type type: str\n"
" :arg dimensions: Array describing the dimensions.\n"
" :type dimensions: int\n"
" :arg data: Optional data array.\n"
" :type data: sequence\n");
PyTypeObject BPyGPU_BufferType = {
PyVarObject_HEAD_INIT(NULL, 0).tp_name = "Buffer",
.tp_basicsize = sizeof(BPyGPUBuffer),

9
source/blender/python/gpu/gpu_py_element.c
View File

@ -184,12 +184,9 @@ PyDoc_STRVAR(pygpu_IndexBuf__tp_doc,
"\n"
" Contains an index buffer.\n"
"\n"
" :param type: One of these primitive types: {\n"
" `POINTS`,\n"
" `LINES`,\n"
" `TRIS`,\n"
" `LINE_STRIP_ADJ` }\n"
" :type type: `str`\n"
" :arg type: The primitive type this index buffer is composed of.\n"
" Possible values are `POINTS`, `LINES`, `TRIS` and `LINE_STRIP_ADJ`.\n"
" :type type: str\n"
" :param seq: Indices this index buffer will contain.\n"
" Whether a 1D or 2D sequence is required depends on the type.\n"
" Optionally the sequence can support the buffer protocol.\n"

10
source/blender/python/gpu/gpu_py_framebuffer.c
View File

@ -356,9 +356,9 @@ PyDoc_STRVAR(pygpu_framebuffer_clear_doc,
" :arg color: float sequence each representing ``(r, g, b, a)``.\n"
" :type color: sequence of 3 or 4 floats\n"
" :arg depth: depth value.\n"
" :type depth: `float`\n"
" :type depth: float\n"
" :arg stencil: stencil value.\n"
" :type stencil: `int`\n");
" :type stencil: int\n");
static PyObject *pygpu_framebuffer_clear(BPyGPUFrameBuffer *self, PyObject *args, PyObject *kwds)
{
PYGPU_FRAMEBUFFER_CHECK_OBJ(self);
@ -417,7 +417,7 @@ PyDoc_STRVAR(pygpu_framebuffer_viewport_set_doc,
"\n"
" :param x, y: lower left corner of the viewport_set rectangle, in pixels.\n"
" :param xsize, ysize: width and height of the viewport_set.\n"
" :type x, y, xsize, ysize: `int`\n");
" :type x, y, xsize, ysize: int\n");
static PyObject *pygpu_framebuffer_viewport_set(BPyGPUFrameBuffer *self,
PyObject *args,
void *UNUSED(type))
@ -510,10 +510,10 @@ PyDoc_STRVAR(pygpu_framebuffer__tp_doc,
"\n"
" :arg depth_slot: GPUTexture to attach or a `dict` containing keywords: "
"'texture', 'layer' and 'mip'.\n"
" :type depth_slot: :class:`gpu.types.GPUTexture`, `dict` or `Nonetype`\n"
" :type depth_slot: :class:`gpu.types.GPUTexture`, dict or Nonetype\n"
" :arg color_slots: Tuple where each item can be a GPUTexture or a `dict` "
"containing keywords: 'texture', 'layer' and 'mip'.\n"
" :type color_slots: `tuple` or `Nonetype`\n");
" :type color_slots: tuple or Nonetype\n");
PyTypeObject BPyGPUFrameBuffer_Type = {
PyVarObject_HEAD_INIT(NULL, 0).tp_name = "GPUFrameBuffer",
.tp_basicsize = sizeof(BPyGPUFrameBuffer),

6
source/blender/python/gpu/gpu_py_offscreen.c
View File

@ -184,7 +184,7 @@ PyDoc_STRVAR(pygpu_offscreen_unbind_doc,
"\n"
" :arg restore: Restore the OpenGL state, can only be used when the state has been "
"saved before.\n"
" :type restore: `bool`\n");
" :type restore: bool\n");
static PyObject *pygpu_offscreen_unbind(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds)
{
bool restore = true;
@ -412,9 +412,9 @@ PyDoc_STRVAR(pygpu_offscreen__tp_doc,
" This object gives access to off screen buffers.\n"
"\n"
" :arg width: Horizontal dimension of the buffer.\n"
" :type width: `int`\n"
" :type width: int\n"
" :arg height: Vertical dimension of the buffer.\n"
" :type height: `int`\n");
" :type height: int\n");
PyTypeObject BPyGPUOffScreen_Type = {
PyVarObject_HEAD_INIT(NULL, 0).tp_name = "GPUOffScreen",
.tp_basicsize = sizeof(BPyGPUOffScreen),

10
source/blender/python/gpu/gpu_py_shader.c
View File

@ -130,9 +130,9 @@ PyDoc_STRVAR(pygpu_shader_uniform_from_name_doc,
" Get uniform location by name.\n"
"\n"
" :param name: Name of the uniform variable whose location is to be queried.\n"
" :type name: `str`\n"
" :type name: str\n"
" :return: Location of the uniform variable.\n"
" :rtype: `int`\n");
" :rtype: int\n");
static PyObject *pygpu_shader_uniform_from_name(BPyGPUShader *self, PyObject *arg)
{
const char *name = PyUnicode_AsUTF8(arg);
@ -157,9 +157,9 @@ PyDoc_STRVAR(
" Get uniform block location by name.\n"
"\n"
" :param name: Name of the uniform block variable whose location is to be queried.\n"
" :type name: `str`\n"
" :type name: str\n"
" :return: The location of the uniform block variable.\n"
" :rtype: `int`\n");
" :rtype: int\n");
static PyObject *pygpu_shader_uniform_block_from_name(BPyGPUShader *self, PyObject *arg)
{
const char *name = PyUnicode_AsUTF8(arg);
@ -559,7 +559,7 @@ PyDoc_STRVAR(pygpu_shader_calc_format_doc,
" Build a new format based on the attributes of the shader.\n"
"\n"
" :return: vertex attribute format for the shader\n"
" :rtype: GPUVertFormat\n");
" :rtype: :class:`gpu.types.GPUVertFormat`\n");
static PyObject *pygpu_shader_calc_format(BPyGPUShader *self, PyObject *UNUSED(arg))
{
BPyGPUVertFormat *ret = (BPyGPUVertFormat *)BPyGPUVertFormat_CreatePyObject(NULL);

73
source/blender/python/gpu/gpu_py_state.c
View File

@ -78,24 +78,27 @@ static const struct PyC_StringEnumItems pygpu_state_faceculling_items[] = {
/** \name Manage Stack
* \{ */
PyDoc_STRVAR(pygpu_state_blend_set_doc,
".. function:: blend_set(mode)\n"
"\n"
" Defines the fixed pipeline blending equation.\n"
"\n"
" :param mode: One of these modes: {\n"
" `NONE`,\n"
" `ALPHA`,\n"
" `ALPHA_PREMULT`,\n"
" `ADDITIVE`,\n"
" `ADDITIVE_PREMULT`,\n"
" `MULTIPLY`,\n"
" `SUBTRACT`,\n"
" `INVERT`,\n"
//" `OIT`,\n"
//" `BACKGROUND`,\n"
//" `CUSTOM`,\n"
" :type mode: `str`\n");
PyDoc_STRVAR(
pygpu_state_blend_set_doc,
".. function:: blend_set(mode)\n"
"\n"
" Defines the fixed pipeline blending equation.\n"
"\n"
" :param mode: The type of blend mode.\n"
" * ``NONE`` No blending.\n"
" * ``ALPHA`` The original color channels are interpolated according to the alpha value.\n"
" * ``ALPHA_PREMULT`` The original color channels are interpolated according to the alpha "
"value with the new colors pre-multiplied by this value.\n"
" * ``ADDITIVE`` The original color channels are added by the corresponding ones.\n"
" * ``ADDITIVE_PREMULT`` The original color channels are added by the corresponding ones "
"that are pre-multiplied by the alpha value.\n"
" * ``MULTIPLY`` The original color channels are multiplied by the corresponding ones.\n"
" * ``SUBTRACT`` The original color channels are subtracted by the corresponding ones.\n"
" * ``INVERT`` The original color channels are replaced by its complementary color.\n"
//" * ``OIT``.\n"
//" * ``BACKGROUND`` .\n"
//" * ``CUSTOM`` .\n"
" :type mode: str\n");
static PyObject *pygpu_state_blend_set(PyObject *UNUSED(self), PyObject *value)
{
struct PyC_StringEnum pygpu_blend = {pygpu_state_blend_items};
@ -122,15 +125,10 @@ PyDoc_STRVAR(pygpu_state_depth_test_set_doc,
"\n"
" Defines the depth_test equation.\n"
"\n"
" :param mode: One of these modes: {\n"
" `NONE`,\n"
" `ALWAYS`,\n"
" `LESS`,\n"
" `LESS_EQUAL`,\n"
" `EQUAL`,\n"
" `GREATER`,\n"
" `GREATER_EQUAL`,\n"
" :type mode: `str`\n");
" :param mode: The depth test equation name.\n"
" Possible values are `NONE`, `ALWAYS`, `LESS`, `LESS_EQUAL`, `EQUAL`, "
"`GREATER` and `GREATER_EQUAL`.\n"
" :type mode: str\n");
static PyObject *pygpu_state_depth_test_set(PyObject *UNUSED(self), PyObject *value)
{
struct PyC_StringEnum pygpu_depth_test = {pygpu_state_depthtest_items};
@ -158,7 +156,7 @@ PyDoc_STRVAR(pygpu_state_depth_mask_set_doc,
" Write to depth component.\n"
"\n"
" :param value: True for writing to the depth component.\n"
" :type near: `bool`\n");
" :type near: bool\n");
static PyObject *pygpu_state_depth_mask_set(PyObject *UNUSED(self), PyObject *value)
{
bool write_to_depth;
@ -186,7 +184,7 @@ PyDoc_STRVAR(pygpu_state_viewport_set_doc,
"\n"
" :param x, y: lower left corner of the viewport_set rectangle, in pixels.\n"
" :param width, height: width and height of the viewport_set.\n"
" :type x, y, xsize, ysize: `int`\n");
" :type x, y, xsize, ysize: int\n");
static PyObject *pygpu_state_viewport_set(PyObject *UNUSED(self), PyObject *args)
{
int x, y, xsize, ysize;
@ -222,7 +220,7 @@ PyDoc_STRVAR(pygpu_state_line_width_set_doc,
" Specify the width of rasterized lines.\n"
"\n"
" :param size: New width.\n"
" :type mode: `float`\n");
" :type mode: float\n");
static PyObject *pygpu_state_line_width_set(PyObject *UNUSED(self), PyObject *value)
{
float width = (float)PyFloat_AsDouble(value);
@ -250,7 +248,7 @@ PyDoc_STRVAR(pygpu_state_point_size_set_doc,
" Specify the diameter of rasterized points.\n"
"\n"
" :param size: New diameter.\n"
" :type mode: `float`\n");
" :type mode: float\n");
static PyObject *pygpu_state_point_size_set(PyObject *UNUSED(self), PyObject *value)
{
float size = (float)PyFloat_AsDouble(value);
@ -268,7 +266,7 @@ PyDoc_STRVAR(pygpu_state_color_mask_set_doc,
" Enable or disable writing of frame buffer color components.\n"
"\n"
" :param r, g, b, a: components red, green, blue, and alpha.\n"
" :type r, g, b, a: `bool`\n");
" :type r, g, b, a: bool\n");
static PyObject *pygpu_state_color_mask_set(PyObject *UNUSED(self), PyObject *args)
{
int r, g, b, a;
@ -285,11 +283,8 @@ PyDoc_STRVAR(pygpu_state_face_culling_set_doc,
"\n"
" Specify whether none, front-facing or back-facing facets can be culled.\n"
"\n"
" :param mode: One of these modes: {\n"
" `NONE`,\n"
" `FRONT`,\n"
" `BACK`,\n"
" :type mode: `str`\n");
" :param mode: `NONE`, `FRONT` or `BACK`.\n"
" :type mode: str\n");
static PyObject *pygpu_state_face_culling_set(PyObject *UNUSED(self), PyObject *value)
{
struct PyC_StringEnum pygpu_faceculling = {pygpu_state_faceculling_items};
@ -307,7 +302,7 @@ PyDoc_STRVAR(pygpu_state_front_facing_set_doc,
" Specifies the orientation of front-facing polygons.\n"
"\n"
" :param invert: True for clockwise polygons as front-facing.\n"
" :type mode: `bool`\n");
" :type mode: bool\n");
static PyObject *pygpu_state_front_facing_set(PyObject *UNUSED(self), PyObject *value)
{
bool invert;
@ -326,7 +321,7 @@ PyDoc_STRVAR(pygpu_state_program_point_size_set_doc,
"shader builtin gl_PointSize.\n"
"\n"
" :param enable: True for shader builtin gl_PointSize.\n"
" :type enable: `bool`\n");
" :type enable: bool\n");
static PyObject *pygpu_state_program_point_size_set(PyObject *UNUSED(self), PyObject *value)
{
bool enable;

38
source/blender/python/gpu/gpu_py_texture.c
View File

@ -272,21 +272,17 @@ static PyObject *pygpu_texture_format_get(BPyGPUTexture *self, void *UNUSED(type
return PyUnicode_FromString(PyC_StringEnum_FindIDFromValue(pygpu_textureformat_items, format));
}
PyDoc_STRVAR(pygpu_texture_clear_doc,
".. method:: clear(format='FLOAT', value=(0.0, 0.0, 0.0, 1.0))\n"
"\n"
" Fill texture with specific value.\n"
"\n"
" :param format: One of these primitive types: {\n"
" `FLOAT`,\n"
" `INT`,\n"
" `UINT`,\n"
" `UBYTE`,\n"
" `UINT_24_8`,\n"
" `10_11_11_REV`,\n"
" :type type: `str`\n"
" :arg value: sequence each representing the value to fill.\n"
" :type value: sequence of 1, 2, 3 or 4 values\n");
PyDoc_STRVAR(
pygpu_texture_clear_doc,
".. method:: clear(format='FLOAT', value=(0.0, 0.0, 0.0, 1.0))\n"
"\n"
" Fill texture with specific value.\n"
"\n"
" :param format: The format that describes the content of a single item.\n"
" Possible values are `FLOAT`, `INT`, `UINT`, `UBYTE`, `UINT_24_8` and `10_11_11_REV`.\n"
" :type type: str\n"
" :arg value: sequence each representing the value to fill.\n"
" :type value: sequence of 1, 2, 3 or 4 values\n");
static PyObject *pygpu_texture_clear(BPyGPUTexture *self, PyObject *args, PyObject *kwds)
{
BPYGPU_TEXTURE_CHECK_OBJ(self);
@ -447,12 +443,12 @@ PyDoc_STRVAR(
" This object gives access to off GPU textures.\n"
"\n"
" :arg size: Dimensions of the texture 1D, 2D, 3D or cubemap.\n"
" :type size: `tuple` or `int`\n"
" :type size: tuple or int\n"
" :arg layers: Number of layers in texture array or number of cubemaps in cubemap array\n"
" :type layers: `int`\n"
" :type layers: int\n"
" :arg is_cubemap: Indicates the creation of a cubemap texture.\n"
" :type is_cubemap: `int`\n"
" :arg format: One of these primitive types: {\n"
" :type is_cubemap: int\n"
" :arg format: Internal data format inside GPU memory. Possible values are:\n"
" `RGBA8UI`,\n"
" `RGBA8I`,\n"
" `RGBA8`,\n"
@ -497,9 +493,9 @@ PyDoc_STRVAR(
" `DEPTH_COMPONENT32F`,\n"
" `DEPTH_COMPONENT24`,\n"
" `DEPTH_COMPONENT16`,\n"
" :type format: `str`\n"
" :type format: str\n"
" :arg data: Buffer object to fill the texture.\n"
" :type data: `Buffer`\n");
" :type data: :class:`gpu.types.Buffer`\n");
PyTypeObject BPyGPUTexture_Type = {
PyVarObject_HEAD_INIT(NULL, 0).tp_name = "GPUTexture",
.tp_basicsize = sizeof(BPyGPUTexture),

2
source/blender/python/gpu/gpu_py_uniformbuffer.c
View File

@ -161,7 +161,7 @@ PyDoc_STRVAR(pygpu_uniformbuffer__tp_doc,
" This object gives access to off uniform buffers.\n"
"\n"
" :arg data: Buffer object.\n"
" :type data: `Buffer`\n");
" :type data: :class:`gpu.types.Buffer`\n");
PyTypeObject BPyGPUUniformBuf_Type = {
PyVarObject_HEAD_INIT(NULL, 0).tp_name = "GPUUniformBuf",
.tp_basicsize = sizeof(BPyGPUUniformBuf),

2
source/blender/python/gpu/gpu_py_vertex_buffer.c
View File

@ -271,7 +271,7 @@ PyDoc_STRVAR(pygpu_vertbuf_attr_fill_doc,
" :param id: Either the name or the id of the attribute.\n"
" :type id: int or str\n"
" :param data: Sequence of data that should be stored in the buffer\n"
" :type data: sequence of values or tuples\n");
" :type data: sequence of floats, ints, vectors or matrices\n");
static PyObject *pygpu_vertbuf_attr_fill(BPyGPUVertBuf *self, PyObject *args, PyObject *kwds)
{
PyObject *data;

4
source/blender/python/gpu/gpu_py_vertex_format.c
View File

@ -85,7 +85,7 @@ PyDoc_STRVAR(
" :type id: str\n"
" :param comp_type: The data type that will be used store the value in memory.\n"
" Possible values are `I8`, `U8`, `I16`, `U16`, `I32`, `U32`, `F32` and `I10`.\n"
" :type comp_type: `str`\n"
" :type comp_type: str\n"
" :param len: How many individual values the attribute consists of\n"
" (e.g. 2 for uv coordinates).\n"
" :type len: int\n"
@ -94,7 +94,7 @@ PyDoc_STRVAR(
" reduced precision. E.g. you can store a float in only 1 byte but it will be\n"
" converted to a normal 4 byte float when used.\n"
" Possible values are `FLOAT`, `INT`, `INT_TO_FLOAT_UNIT` and `INT_TO_FLOAT`.\n"
" :type fetch_mode: `str`\n");
" :type fetch_mode: str\n");
static PyObject *pygpu_vertformat_attr_add(BPyGPUVertFormat *self, PyObject *args, PyObject *kwds)
{
const char *id;