From 444f1fd4237d68151cb0cb844ad25276102291bd Mon Sep 17 00:00:00 2001 From: Jacques Lucke Date: Tue, 13 Nov 2018 14:55:15 +0100 Subject: Py API Docs: Cleanup --- source/blender/python/gpu/gpu_py_batch.c | 18 ++--- source/blender/python/gpu/gpu_py_element.c | 16 ++--- source/blender/python/gpu/gpu_py_offscreen.c | 44 ++++++------ source/blender/python/gpu/gpu_py_shader.c | 85 +++++++++++------------- source/blender/python/gpu/gpu_py_vertex_buffer.c | 10 +-- 5 files changed, 82 insertions(+), 91 deletions(-) (limited to 'source/blender/python/gpu') diff --git a/source/blender/python/gpu/gpu_py_batch.c b/source/blender/python/gpu/gpu_py_batch.c index add813dd928..77dcfad2c9f 100644 --- a/source/blender/python/gpu/gpu_py_batch.c +++ b/source/blender/python/gpu/gpu_py_batch.c @@ -222,10 +222,10 @@ static PyObject *bpygpu_Batch_program_set(BPyGPUBatch *self, BPyGPUShader *py_sh PyDoc_STRVAR(bpygpu_Batch_draw_doc, ".. method:: draw(program=None)\n" "\n" -" Run the drawing program with the parameters assigned to the batch.\n" +" Run the drawing program with the parameters assigned to the batch. \n" "\n" -" :param program: program that performs the drawing operations. \n" -" If ``None`` is passed, the last program setted to this batch will run.\n" +" :param program: Program that performs the drawing operations. \n" +" If ``None`` is passed, the last program setted to this batch will run. \n" " :type program: :class:`gpu.types.GPUShader`\n" ); static PyObject *bpygpu_Batch_draw(BPyGPUBatch *self, PyObject *args) @@ -318,11 +318,11 @@ static void bpygpu_Batch_dealloc(BPyGPUBatch *self) } PyDoc_STRVAR(py_gpu_batch_doc, -"GPUBatch(type, buf, elem=None)\n" +".. class:: GPUBatch(type, buf, elem=None)\n" "\n" -"Contains VAOs + VBOs + Shader representing a drawable entity." +" Reusable container for drawable geometry. \n" "\n" -" :param type: One of these primitive types: {\n" +" :arg type: One of these primitive types: {\n" " `POINTS`,\n" " `LINES`,\n" " `TRIS`,\n" @@ -333,10 +333,10 @@ PyDoc_STRVAR(py_gpu_batch_doc, " `LINES_ADJ`,\n" " `TRIS_ADJ`,\n" " `LINE_STRIP_ADJ` }\n" -" :type type: :class:`str`\n" -" :param buf: Vertex buffer containing all or some of the attributes required for drawing.\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" -" :param elem: Optional index buffer.\n" +" :arg elem: An optional index buffer.\n" " :type elem: :class:`gpu.types.GPUIndexBuf`\n" ); PyTypeObject BPyGPUBatch_Type = { diff --git a/source/blender/python/gpu/gpu_py_element.c b/source/blender/python/gpu/gpu_py_element.c index c85d6dfbe3b..10990abc5e6 100644 --- a/source/blender/python/gpu/gpu_py_element.c +++ b/source/blender/python/gpu/gpu_py_element.c @@ -196,20 +196,20 @@ static void bpygpu_IndexBuf_dealloc(BPyGPUIndexBuf *self) } PyDoc_STRVAR(py_gpu_element_doc, -"GPUIndexBuf(type, seq)\n" +".. class:: GPUIndexBuf(type, seq)\n" "\n" -"Contains an index buffer." +" Contains an index buffer. \n" "\n" -" :param type:\n" -" One of these primitive types: {\n" +" :param type: One of these primitive types: {\n" " `POINTS`,\n" " `LINES`,\n" " `TRIS`,\n" " `LINE_STRIP_ADJ` }\n" -" :type type: :class:`str`\n" -" :param seq: Indices this index buffer will contain.\n" -" :type buf: 1D or 2D sequence, depending on the type. \n" -" Optionally the sequence can support the buffer protocol. \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" +" :type seq: 1D or 2D sequence \n" ); PyTypeObject BPyGPUIndexBuf_Type = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/source/blender/python/gpu/gpu_py_offscreen.c b/source/blender/python/gpu/gpu_py_offscreen.c index 3deeb562b3b..c04dbb48e7d 100644 --- a/source/blender/python/gpu/gpu_py_offscreen.c +++ b/source/blender/python/gpu/gpu_py_offscreen.c @@ -102,21 +102,21 @@ static int bpygpu_offscreen_valid_check(BPyGPUOffScreen *bpygpu_ofs) } \ } ((void)0) -PyDoc_STRVAR(bpygpu_offscreen_width_doc, "Texture width.\n\n:type: int"); +PyDoc_STRVAR(bpygpu_offscreen_width_doc, "Width of the texture.\n\n:type: `int`"); static PyObject *bpygpu_offscreen_width_get(BPyGPUOffScreen *self, void *UNUSED(type)) { BPY_GPU_OFFSCREEN_CHECK_OBJ(self); return PyLong_FromLong(GPU_offscreen_width(self->ofs)); } -PyDoc_STRVAR(bpygpu_offscreen_height_doc, "Texture height.\n\n:type: int"); +PyDoc_STRVAR(bpygpu_offscreen_height_doc, "Height of the texture.\n\n:type: `int`"); static PyObject *bpygpu_offscreen_height_get(BPyGPUOffScreen *self, void *UNUSED(type)) { BPY_GPU_OFFSCREEN_CHECK_OBJ(self); return PyLong_FromLong(GPU_offscreen_height(self->ofs)); } -PyDoc_STRVAR(bpygpu_offscreen_color_texture_doc, "Color texture.\n\n:type: int"); +PyDoc_STRVAR(bpygpu_offscreen_color_texture_doc, "OpenGL bindcode for the color texture.\n\n:type: `int`"); static PyObject *bpygpu_offscreen_color_texture_get(BPyGPUOffScreen *self, void *UNUSED(type)) { BPY_GPU_OFFSCREEN_CHECK_OBJ(self); @@ -125,12 +125,12 @@ static PyObject *bpygpu_offscreen_color_texture_get(BPyGPUOffScreen *self, void } PyDoc_STRVAR(bpygpu_offscreen_bind_doc, -"bind(save=True)\n" +".. method:: bind(save=True)\n" "\n" " Bind the offscreen object.\n" "\n" -" :param save: save OpenGL current states.\n" -" :type save: bool\n" +" :arg save: Save the current OpenGL state, so that it can be restored when unbinding.\n" +" :type save: `bool`\n" ); static PyObject *bpygpu_offscreen_bind(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds) { @@ -152,12 +152,12 @@ static PyObject *bpygpu_offscreen_bind(BPyGPUOffScreen *self, PyObject *args, Py } PyDoc_STRVAR(bpygpu_offscreen_unbind_doc, -"unbind(restore=True)\n" +".. method:: unbind(restore=True)\n" "\n" " Unbind the offscreen object.\n" "\n" -" :param restore: restore OpenGL previous states.\n" -" :type restore: bool\n" +" :arg restore: Restore the OpenGL state, can only be used when the state has been saved before.\n" +" :type restore: `bool`\n" ); static PyObject *bpygpu_offscreen_unbind(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds) { @@ -179,21 +179,21 @@ static PyObject *bpygpu_offscreen_unbind(BPyGPUOffScreen *self, PyObject *args, } PyDoc_STRVAR(bpygpu_offscreen_draw_view3d_doc, -"draw_view3d(scene, view3d, region, modelview_matrix, projection_matrix)\n" +".. method:: draw_view3d(scene, view3d, region, modelview_matrix, projection_matrix)\n" "\n" " Draw the 3d viewport in the offscreen object.\n" "\n" -" :param scene: Scene to draw.\n" +" :arg scene: Scene to draw.\n" " :type scene: :class:`bpy.types.Scene`\n" -" :param view_layer: View layer to draw.\n" +" :arg view_layer: View layer to draw.\n" " :type view_layer: :class:`bpy.types.ViewLayer`\n" -" :param view3d: 3D View to get the drawing settings from.\n" +" :arg view3d: 3D View to get the drawing settings from.\n" " :type view3d: :class:`bpy.types.SpaceView3D`\n" -" :param region: Region of the 3D View.\n" +" :arg region: Region of the 3D View (required as temporary draw target).\n" " :type region: :class:`bpy.types.Region`\n" -" :param view_matrix: View Matrix.\n" +" :arg view_matrix: View Matrix (e.g. ``camera.matrix_world.inverted()``).\n" " :type view_matrix: :class:`mathutils.Matrix`\n" -" :param projection_matrix: Projection Matrix.\n" +" :arg projection_matrix: Projection Matrix (e.g. ``camera.calc_matrix_camera(...)``).\n" " :type projection_matrix: :class:`mathutils.Matrix`\n" ); static PyObject *bpygpu_offscreen_draw_view3d(BPyGPUOffScreen *self, PyObject *args, PyObject *kwds) @@ -261,9 +261,9 @@ static PyObject *bpygpu_offscreen_draw_view3d(BPyGPUOffScreen *self, PyObject *a } PyDoc_STRVAR(bpygpu_offscreen_free_doc, -"free()\n" +".. method:: free()\n" "\n" -" Free the offscreen object\n" +" Free the offscreen object.\n" " The framebuffer, texture and render objects will no longer be accessible.\n" ); static PyObject *bpygpu_offscreen_free(BPyGPUOffScreen *self) @@ -298,15 +298,15 @@ static struct PyMethodDef bpygpu_offscreen_methods[] = { }; PyDoc_STRVAR(bpygpu_offscreen_doc, -"GPUOffScreen(width, height, samples=0)\n" +".. class:: GPUOffScreen(width, height, samples=0)\n" "\n" " This object gives access to off screen buffers.\n" "\n" -" :param width: Horizontal dimension of the buffer.\n" +" :arg width: Horizontal dimension of the buffer.\n" " :type width: `int`\n" -" :param height: Vertical dimension of the buffer.\n" +" :arg height: Vertical dimension of the buffer.\n" " :type height: `int`\n" -" :param samples: OpenGL samples to use for MSAA or zero to disable.\n" +" :arg samples: OpenGL samples to use for MSAA or zero to disable.\n" " :type samples: `int`\n" ); PyTypeObject BPyGPUOffScreen_Type = { diff --git a/source/blender/python/gpu/gpu_py_shader.c b/source/blender/python/gpu/gpu_py_shader.c index 4569e64eb62..19d6c8070f8 100644 --- a/source/blender/python/gpu/gpu_py_shader.c +++ b/source/blender/python/gpu/gpu_py_shader.c @@ -145,7 +145,7 @@ static PyObject *bpygpu_shader_new(PyTypeObject *UNUSED(type), PyObject *args, P PyDoc_STRVAR(bpygpu_shader_bind_doc, ".. method:: bind()\n" "\n" -" Bind the Shader object.\n" +" Bind the shader object. Required to be able to change uniforms of this shader. \n" ); static PyObject *bpygpu_shader_bind(BPyGPUShader *self) { @@ -159,7 +159,7 @@ PyDoc_STRVAR(bpygpu_shader_transform_feedback_enable_doc, " Start transform feedback operation.\n" "\n" " :return: true if transform feedback was succesfully enabled.\n" -" :rtype: bool\n" +" :rtype: `bool`\n" ); static PyObject *bpygpu_shader_transform_feedback_enable( BPyGPUShader *self, PyObject *arg) @@ -187,10 +187,10 @@ PyDoc_STRVAR(bpygpu_shader_uniform_from_name_doc, "\n" " 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" -" :return: the location of the uniform variable.\n" -" :rtype: int\n" +" :param name: Name of the uniform variable whose location is to be queried.\n" +" :type name: `str`\n" +" :return: Location of the uniform variable.\n" +" :rtype: `int`\n" ); static PyObject *bpygpu_shader_uniform_from_name( BPyGPUShader *self, PyObject *arg) @@ -215,10 +215,10 @@ PyDoc_STRVAR(bpygpu_shader_uniform_block_from_name_doc, "\n" " 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" -" :return: the location of the uniform block variable.\n" -" :rtype: int\n" +" :param name: Name of the uniform block variable whose location is to be queried.\n" +" :type name: `str`\n" +" :return: The location of the uniform block variable.\n" +" :rtype: `int`\n" ); static PyObject *bpygpu_shader_uniform_block_from_name( BPyGPUShader *self, PyObject *arg) @@ -273,12 +273,11 @@ PyDoc_STRVAR(bpygpu_shader_uniform_vector_float_doc, "\n" " Set the buffer to fill the uniform.\n" "\n" -" :param location: location of the uniform variable to be modified.\n" +" :param location: Location of the uniform variable to be modified.\n" " :type location: int\n" -" :param buffer: buffer object with format float.\n" -" :type buffer: buffer object\n" -" :param length:\n" -" size of the uniform data type:\n" +" :param buffer: The data that should be set. Can support the buffer protocol.\n" +" :type buffer: sequence of floats\n" +" :param length: Size of the uniform data type:\n" "\n" " - 1: float\n" " - 2: vec2 or float[2]\n" @@ -288,7 +287,7 @@ PyDoc_STRVAR(bpygpu_shader_uniform_vector_float_doc, " - 16: mat4\n" "\n" " :type length: int\n" -" :param count: specifies the number of elements, vector or matrices that are to be modified.\n" +" :param count: Specifies the number of elements, vector or matrices that are to be modified.\n" " :type count: int\n" ); static PyObject *bpygpu_shader_uniform_vector_float( @@ -347,9 +346,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_bool_doc, "\n" " Specify the value of a uniform variable for the current program object.\n" "\n" -" :param name: name of the uniform variable whose location is to be queried.\n" +" :param name: Name of the uniform variable whose value is to be changed.\n" " :type name: str\n" -" :param seq: values that will be used to update the specified uniform variable.\n" +" :param seq: Value that will be used to update the specified uniform variable.\n" " :type seq: sequence of bools\n" ); static PyObject *bpygpu_shader_uniform_bool( @@ -417,9 +416,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_float_doc, "\n" " Specify the value of a uniform variable for the current program object.\n" "\n" -" :param name: name of the uniform variable whose location is to be queried.\n" +" :param name: Name of the uniform variable whose value is to be changed.\n" " :type name: str\n" -" :param value: values that will be used to update the specified uniform variable.\n" +" :param value: Value that will be used to update the specified uniform variable.\n" " :type value: single number or sequence of numbers\n" ); static PyObject *bpygpu_shader_uniform_float( @@ -493,9 +492,9 @@ PyDoc_STRVAR(bpygpu_shader_uniform_int_doc, "\n" " Specify the value of a uniform variable for the current program object.\n" "\n" -" :param name: name of the uniform variable whose location is to be queried.\n" +" :param name: name of the uniform variable whose value is to be changed.\n" " :type name: str\n" -" :param seq: values that will be used to update the specified uniform variable.\n" +" :param seq: Value that will be used to update the specified uniform variable.\n" " :type seq: sequence of numbers\n" ); static PyObject *bpygpu_shader_uniform_int( @@ -569,9 +568,9 @@ PyDoc_STRVAR(bpygpu_shader_attr_from_name_doc, "\n" " Get attribute location by name.\n" "\n" -" :param name: the name of the attribute variable whose location is to be queried.\n" +" :param name: The name of the attribute variable whose location is to be queried.\n" " :type name: str\n" -" :return: the location of an attribute variable.\n" +" :return: The location of an attribute variable.\n" " :rtype: int\n" ); static PyObject *bpygpu_shader_attr_from_name( @@ -673,38 +672,30 @@ static void bpygpu_shader_dealloc(BPyGPUShader *self) PyDoc_STRVAR(bpygpu_shader_doc, -"GPUShader(vertexcode, fragcode, geocode=None, libcode=None, defines=None)\n" -"\n" -"GPUShader combines multiple GLSL shaders into a program used for drawing.\n" -"It must contain a vertex and fragment shaders, with an optional geometry shader.\n" -"\n" -"The GLSL #version directive is automatically included at the top of shaders, and set to 330.\n" -"\n" -"Some preprocessor directives are automatically added according to the Operating System or availability.\n" -"\n" -"These are::\n" +".. class:: GPUShader(vertexcode, fragcode, geocode=None, libcode=None, defines=None)\n" "\n" -" \"#define GPU_ATI\\n\"\n" -" \"#define GPU_NVIDIA\\n\"\n" -" \"#define GPU_INTEL\\n\"\n" +" GPUShader combines multiple GLSL shaders into a program used for drawing.\n" +" It must contain a vertex and fragment shaders, with an optional geometry shader.\n" "\n" -"The following extensions are enabled by default if supported by the GPU::\n" +" The GLSL #version directive is automatically included at the top of shaders, and set to 330.\n" +" Some preprocessor directives are automatically added according to the Operating System or availability:\n" +" ``GPU_ATI``, ``GPU_NVIDIA`` and ``GPU_INTEL``.\n" "\n" -" \"#extension GL_ARB_texture_gather: enable\\n\"\n" -" \"#extension GL_ARB_texture_query_lod: enable\\n\"\n" +" The following extensions are enabled by default if supported by the GPU:\n" +" ``GL_ARB_texture_gather`` and ``GL_ARB_texture_query_lod``.\n" "\n" -"To debug shaders, use the --debug-gpu-shaders command line option" -" to see full GLSL shader compilation and linking errors.\n" +" To debug shaders, use the --debug-gpu-shaders command line option" +" to see full GLSL shader compilation and linking errors.\n" "\n" -" :param vertexcode: vertex Shader Code.\n" +" :param vertexcode: Vertex shader code.\n" " :type vertexcode: str\n" -" :param fragcode: fragment Shader Code.\n" +" :param fragcode: Fragment shader code.\n" " :type value: str\n" -" :param geocode: geometry Shader Code.\n" +" :param geocode: Geometry shader code.\n" " :type value: str\n" -" :param libcode: code with functions and presets to be shared between shaders.\n" +" :param libcode: Code with functions and presets to be shared between shaders.\n" " :type value: str\n" -" :param defines: preprocessor directives.\n" +" :param defines: Preprocessor directives.\n" " :type value: str\n" ); PyTypeObject BPyGPUShader_Type = { diff --git a/source/blender/python/gpu/gpu_py_vertex_buffer.c b/source/blender/python/gpu/gpu_py_vertex_buffer.c index 1f888597b34..37357fa115c 100644 --- a/source/blender/python/gpu/gpu_py_vertex_buffer.c +++ b/source/blender/python/gpu/gpu_py_vertex_buffer.c @@ -246,7 +246,7 @@ static PyObject *bpygpu_VertBuf_new(PyTypeObject *UNUSED(type), PyObject *args, } PyDoc_STRVAR(bpygpu_VertBuf_attr_fill_doc, -"attr_fill(id, data)\n" +".. method:: attr_fill(id, data)\n" "\n" " Insert data into the buffer for a single attribute.\n" "\n" @@ -311,14 +311,14 @@ static void bpygpu_VertBuf_dealloc(BPyGPUVertBuf *self) } PyDoc_STRVAR(py_gpu_vertex_buffer_doc, -"GPUVertBuf(len, format)\n" +".. class:: GPUVertBuf(len, format)\n" "\n" -"Contains a VBO." +" Contains a VBO." "\n" -" :param len: number of elements to allocate\n" +" :param len: Amount of vertices that will fit into this buffer.\n" " :type type: `int`\n" " :param format: Vertex format.\n" -" :type buf: `gpu.types.GPUVertFormat`\n" +" :type buf: :class:`gpu.types.GPUVertFormat`\n" ); PyTypeObject BPyGPUVertBuf_Type = { PyVarObject_HEAD_INIT(NULL, 0) -- cgit v1.2.3