Commit: 3c8c9760865d14c8dffa3a4cd091e4027b1501e3 Author: Campbell Barton Date: Tue Nov 20 07:32:49 2018 +1100 Branches: blender2.8 https://developer.blender.org/rB3c8c9760865d14c8dffa3a4cd091e4027b1501e3
Cleanup: gpu docs =================================================================== M doc/python_api/examples/gpu.1.py M doc/python_api/examples/gpu.10.py M doc/python_api/examples/gpu.11.py M doc/python_api/examples/gpu.2.py M doc/python_api/examples/gpu.3.py M doc/python_api/examples/gpu.4.py M doc/python_api/examples/gpu.5.py M doc/python_api/examples/gpu.6.py M doc/python_api/examples/gpu.7.py M doc/python_api/examples/gpu.8.py M doc/python_api/examples/gpu.9.py M doc/python_api/examples/gpu.shader.py =================================================================== diff --git a/doc/python_api/examples/gpu.1.py b/doc/python_api/examples/gpu.1.py index c8ae3b01ee3..831349e5430 100644 --- a/doc/python_api/examples/gpu.1.py +++ b/doc/python_api/examples/gpu.1.py @@ -4,7 +4,8 @@ Geometry Batches Geometry is drawn in batches. A batch contains the necessary data to perform the drawing. -That includes an obligatory *Vertex Buffer* and an optional *Index Buffer*, each of which is described in more detail in the following sections. +That includes an obligatory *Vertex Buffer* and an optional *Index Buffer*, +each of which is described in more detail in the following sections. A batch also defines a draw type. Typical draw types are `POINTS`, `LINES` and `TRIS`. The draw type determines how the data will be interpreted and drawn. @@ -12,25 +13,29 @@ The draw type determines how the data will be interpreted and drawn. Vertex Buffers ++++++++++++++ -A *Vertex Buffer Object* (VBO) (:class:`gpu.types.GPUVertBuf`) is an array that contains the vertex attributes needed for drawing using a specific shader. +A *Vertex Buffer Object* (VBO) (:class:`gpu.types.GPUVertBuf`) +is an array that contains the vertex attributes needed for drawing using a specific shader. Typical vertex attributes are *location*, *normal*, *color*, and *uv*. -Every vertex buffer has a *Vertex Format* (:class:`gpu.types.GPUVertFormat`) and a length corresponding to the number of vertices in the buffer. +Every vertex buffer has a *Vertex Format* (:class:`gpu.types.GPUVertFormat`) +and a length corresponding to the number of vertices in the buffer. A vertex format describes the attributes stored per vertex and their types. The following code demonstrates the creation of a vertex buffer that contains 6 vertices. -For each vertex 2 attributes will be stored: The position and the normal:: +For each vertex 2 attributes will be stored: The position and the normal. - import gpu - vertex_positions = [(0, 0, 0), ...] - vertex_normals = [(0, 0, 1), ...] +.. code-block:: python - fmt = gpu.types.GPUVertFormat() - fmt.attr_add(id="pos", comp_type='F32', len=3, fetch_mode='FLOAT') - fmt.attr_add(id="normal", comp_type='F32', len=3, fetch_mode='FLOAT') + import gpu + vertex_positions = [(0, 0, 0), ...] + vertex_normals = [(0, 0, 1), ...] - vbo = gpu.types.GPUVertBuf(len=6, format=fmt) - vbo.attr_fill(id="pos", data=vertex_positions) - vbo.attr_fill(id="normal", data=vertex_normals) + fmt = gpu.types.GPUVertFormat() + fmt.attr_add(id="pos", comp_type='F32', len=3, fetch_mode='FLOAT') + fmt.attr_add(id="normal", comp_type='F32', len=3, fetch_mode='FLOAT') + + vbo = gpu.types.GPUVertBuf(len=6, format=fmt) + vbo.attr_fill(id="pos", data=vertex_positions) + vbo.attr_fill(id="normal", data=vertex_normals) This vertex buffer could be used to draw 6 points, 3 separate lines, 5 consecutive lines, 2 separate triangles, ... E.g. in the case of lines, each two consecutive vertices define a line. @@ -42,19 +47,24 @@ Index Buffers Often triangles and lines share one or more vertices. With only a vertex buffer one would have to store all attributes for the these vertices multiple times. This is very inefficient because in a connected triangle mesh every vertex is used 6 times on average. -A more efficient approach would be to use an *Index Buffer* (IBO) (:class:`gpu.types.GPUIndexBuf`), sometimes referred to as *Element Buffer*. +A more efficient approach would be to use an *Index Buffer* (IBO) (:class:`gpu.types.GPUIndexBuf`), +sometimes referred to as *Element Buffer*. An *Index Buffer* is an array that references vertices based on their index in the vertex buffer. -For instance, to draw a rectangle composed of two triangles, one could use an index buffer:: - positions = ( - (-1, 1), (1, 1), - (-1, -1), (1, -1)) +For instance, to draw a rectangle composed of two triangles, one could use an index buffer. + +.. code-block:: python + + positions = ( + (-1, 1), (1, 1), + (-1, -1), (1, -1)) - indices = ((0, 1, 2), (2, 1, 3)) + indices = ((0, 1, 2), (2, 1, 3)) - ibo = gpu.types.GPUIndexBuf(type='TRIS', seq=indices) + ibo = gpu.types.GPUIndexBuf(type='TRIS', seq=indices) -Here the first tuple in `indices` describes which vertices should be used for the first triangle (same for the second tuple). +Here the first tuple in `indices` describes which vertices should be used for the first triangle +(same for the second tuple). Note how the diagonal vertices 1 and 2 are shared between both triangles. Shaders @@ -66,7 +76,8 @@ The most important ones are *Vertex Shaders* and *Fragment Shaders*. Typically multiple shaders are linked together into a *Program*. However, in the Blender Python API the term *Shader* refers to an OpenGL Program. Every :class:`gpu.types.GPUShader` consists of a vertex shader, a fragment shader and an optional geometry shader. -For common drawing tasks there are some built-in shaders accessible from :class:`gpu.shader.from_builtin` with an identifier such as `2D_UNIFORM_COLOR` or `3D_FLAT_COLOR`. +For common drawing tasks there are some built-in shaders accessible from :class:`gpu.shader.from_builtin` +with an identifier such as `2D_UNIFORM_COLOR` or `3D_FLAT_COLOR`. Every shader defines a set of attributes and uniforms that have to be set in order to use the shader. Attributes are properties that are set using a vertex buffer and can be different for individual vertices. @@ -89,14 +100,18 @@ Offscreen Rendering +++++++++++++++++++ What one can see on the screen after rendering is called the *Front Buffer*. -When draw calls are issued, batches are drawn on a *Back Buffer* that will only be displayed when all drawing is done and the current back buffer will become the new front buffer. -Sometimes, one might want to draw the batches into a distinct buffer that could be used as texture to display on another object or to be saved as image on disk. +When draw calls are issued, batches are drawn on a *Back Buffer* that will only be displayed +when all drawing is done and the current back buffer will become the new front buffer. +Sometimes, one might want to draw the batches into a distinct buffer that could be used as +texture to display on another object or to be saved as image on disk. This is called Offscreen Rendering. In Blender Offscreen Rendering is done using the :class:`gpu.types.GPUOffScreen` type. .. warning:: - `GPUOffScreen` objects are bound to the OpenGL context they have been created in. - This means that once Blender discards this context (i.e. the window is closed), the offscreen instance will be freed. + + `GPUOffScreen` objects are bound to the OpenGL context they have been created in. + This means that once Blender discards this context (i.e. the window is closed), + the offscreen instance will be freed. Examples ++++++++ @@ -104,4 +119,4 @@ Examples To try these examples, just copy them into Blenders text editor and execute them. To keep the examples relatively small, they just register a draw function that can't easily be removed anymore. Blender has to be restarted in order to delete the draw handlers. -""" \ No newline at end of file +""" diff --git a/doc/python_api/examples/gpu.10.py b/doc/python_api/examples/gpu.10.py index aa5574c44bb..6e7a3f6db6f 100644 --- a/doc/python_api/examples/gpu.10.py +++ b/doc/python_api/examples/gpu.10.py @@ -3,7 +3,8 @@ Rendering the 3D View into a Texture ------------------------------------ The scene has to have a camera for this example to work. -You could also make this independent of a specific camera, but Blender does not expose good functions to create view and projection matrices yet. +You could also make this independent of a specific camera, +but Blender does not expose good functions to create view and projection matrices yet. """ import bpy import bgl @@ -15,6 +16,7 @@ HEIGHT = 256 offscreen = gpu.types.GPUOffScreen(WIDTH, HEIGHT) + def draw(): context = bpy.context scene = context.scene @@ -35,4 +37,5 @@ def draw(): bgl.glDisable(bgl.GL_DEPTH_TEST) draw_texture_2d(offscreen.color_texture, (10, 10), WIDTH, HEIGHT) -bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_PIXEL') \ No newline at end of file + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_PIXEL') diff --git a/doc/python_api/examples/gpu.11.py b/doc/python_api/examples/gpu.11.py index 61e7a842a59..2f255b7127d 100644 --- a/doc/python_api/examples/gpu.11.py +++ b/doc/python_api/examples/gpu.11.py @@ -3,8 +3,9 @@ Custom Shader for dotted 3D Line -------------------------------- In this example the arc length (distance to the first point on the line) is calculated in every vertex. -Between the vertex and fragment shader that value is automatically interpolated for all points that will be visible on the screen. -In the fragment shader the `sin` of the arc length is calculated. +Between the vertex and fragment shader that value is automatically interpolated +for all points that will be visible on the screen. +In the fragment shader the ``sin`` of the arc length is calculated. Based on the result a decision is made on whether the fragment should be drawn or not. """ import bpy @@ -47,9 +48,11 @@ for a, b in zip(coords[:-1], coords[1:]): arc_lengths.append(arc_lengths[-1] + (a - b).length) shader = gpu.types.GPUShader(vertex_shader, fragment_shader) -batch = batch_for_shader(shader, 'LINE_STRIP', - {"position" : coords, - "arcLength" : arc_lengths}) +batch = batch_for_shader( + shader, 'LINE_STRIP', + {"position": coords, "arcLength": arc_lengths}, +) + def draw(): shader.bind() @@ -58,4 +61,5 @@ def draw(): shader.uniform_float("u_Scale", 10) batch.draw(shader) -bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') \ No newline at end of file + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') diff --git a/doc/python_api/examples/gpu.2.py b/doc/python_api/examples/gpu.2.py index 8188110d096..d1e8ac32589 100644 --- a/doc/python_api/examples/gpu.2.py +++ b/doc/python_api/examples/gpu.2.py @@ -8,12 +8,13 @@ from gpu_extras.batch import batch @@ Diff output truncated at 10240 characters. @@ _______________________________________________ Bf-blender-cvs mailing list Bf-blender-cvs@blender.org https://lists.blender.org/mailman/listinfo/bf-blender-cvs