From a8e9959e07a05f08cbe28a3b37c0b24874f6f76f Mon Sep 17 00:00:00 2001 From: Jacques Lucke Date: Mon, 5 Nov 2018 19:26:53 +0100 Subject: API Docs: gpu api introduction + examples --- doc/python_api/examples/gpu.1.py | 47 +++++++++++++++++++++++++++++++++ doc/python_api/examples/gpu.2.py | 19 ++++++++++++++ doc/python_api/examples/gpu.3.py | 44 +++++++++++++++++++++++++++++++ doc/python_api/examples/gpu.4.py | 28 ++++++++++++++++++++ doc/python_api/examples/gpu.5.py | 33 +++++++++++++++++++++++ doc/python_api/examples/gpu.6.py | 24 +++++++++++++++++ doc/python_api/examples/gpu.7.py | 49 +++++++++++++++++++++++++++++++++++ doc/python_api/examples/gpu.shader.py | 35 +++++++++++++++++++++++++ 8 files changed, 279 insertions(+) create mode 100644 doc/python_api/examples/gpu.1.py create mode 100644 doc/python_api/examples/gpu.2.py create mode 100644 doc/python_api/examples/gpu.3.py create mode 100644 doc/python_api/examples/gpu.4.py create mode 100644 doc/python_api/examples/gpu.5.py create mode 100644 doc/python_api/examples/gpu.6.py create mode 100644 doc/python_api/examples/gpu.7.py create mode 100644 doc/python_api/examples/gpu.shader.py (limited to 'doc') diff --git a/doc/python_api/examples/gpu.1.py b/doc/python_api/examples/gpu.1.py new file mode 100644 index 00000000000..c23df30e28a --- /dev/null +++ b/doc/python_api/examples/gpu.1.py @@ -0,0 +1,47 @@ +""" +Geometry Batches +++++++++++++++++ + +To draw geometry using the gpu module you need to create a :class:`gpu.types.GPUBatch` object. +Batches contain a sequence of points, lines or triangles and associated geometry attributes. + +A batch can be drawn multiple times, so they should be cached whenever possible. +This makes them much faster than using the legacy `glBegin` and `glEnd` method, which would recreate the geometry data every time. + +Every batch has a so called `Vertex Buffer`. +It contains the attributes for every vertex. +Typical attributes are `position`, `color` and `uv`. +Which attributes the vertex buffer of a batch contains, depends on the shader that will be used to process the batch. + +Shaders ++++++++ + +A shader is a small program that tells the GPU how to draw batch geometry. +There are a couple of built-in shaders for the most common tasks. +Built-in shaders can be accessed with :class:`gpu.shader.from_builtin`. +Every built-in shader has an identifier (e.g. `2D_UNIFORM_COLOR` and `3D_FLAT_COLOR`). + +Custom shaders can be used as well. +The :class:`gpu.types.GPUShader` takes the shader code as input and compiles it. +Every shader has at least a vertex and a fragment shader. +Optionally a geometry shader can be used as well. + +.. note:: + A `GPUShader` is actually a `program` in OpenGL terminology. + +Shaders define a set of `uniforms` and `attributes`. +**Uniforms** are properties that are constant for every vertex in a batch. +They have to be set before the batch but after the shader has been bound. +**Attributes** are properties that can be different for every vertex. + +The attributes and uniforms used by built-in shaders are listed here: :class:`gpu.shader` + +A batch can only be processed/drawn by a shader when it provides all the attributes that the shader specifies. + +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.2.py b/doc/python_api/examples/gpu.2.py new file mode 100644 index 00000000000..8188110d096 --- /dev/null +++ b/doc/python_api/examples/gpu.2.py @@ -0,0 +1,19 @@ +""" +3D Lines with Single Color +-------------------------- +""" +import bpy +import gpu +from gpu_extras.batch import batch_for_shader + +coords = [(1, 1, 1), (-2, 0, 0), (-2, -1, 3), (0, 1, 1)] +shader = gpu.shader.from_builtin('3D_UNIFORM_COLOR') +batch = batch_for_shader(shader, 'LINES', {"pos" : coords}) + +def draw(): + shader.bind() + shader.uniform_float("color", (1, 1, 0, 1)) + batch.draw(shader) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') + diff --git a/doc/python_api/examples/gpu.3.py b/doc/python_api/examples/gpu.3.py new file mode 100644 index 00000000000..30f340c30ff --- /dev/null +++ b/doc/python_api/examples/gpu.3.py @@ -0,0 +1,44 @@ +""" +Triangle with Custom Shader +--------------------------- +""" +import bpy +import gpu +from gpu_extras.batch import batch_for_shader + +vertex_shader = ''' + uniform mat4 viewProjectionMatrix; + + in vec3 position; + out vec3 pos; + + void main() + { + pos = position; + gl_Position = viewProjectionMatrix * vec4(position, 1.0f); + } +''' + +fragment_shader = ''' + uniform float brightness; + + in vec3 pos; + + void main() + { + gl_FragColor = vec4(pos * brightness, 1.0); + } +''' + +coords = [(1, 1, 1), (2, 0, 0), (-2, -1, 3)] +shader = gpu.types.GPUShader(vertex_shader, fragment_shader) +batch = batch_for_shader(shader, 'TRIS', {"position" : coords}) + +def draw(): + shader.bind() + matrix = bpy.context.region_data.perspective_matrix + shader.uniform_float("viewProjectionMatrix", matrix) + shader.uniform_float("brightness", 0.5) + batch.draw(shader) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') \ No newline at end of file diff --git a/doc/python_api/examples/gpu.4.py b/doc/python_api/examples/gpu.4.py new file mode 100644 index 00000000000..392f010e7c2 --- /dev/null +++ b/doc/python_api/examples/gpu.4.py @@ -0,0 +1,28 @@ +""" +Wireframe Cube using Index Buffer +--------------------------------- +""" +import bpy +import gpu +from gpu_extras.batch import batch_for_shader + +coords = ( + (-1, -1, -1), ( 1, -1, -1), + (-1, 1, -1), ( 1, 1, -1), + (-1, -1, 1), ( 1, -1, 1), + (-1, 1, 1), ( 1, 1, 1)) + +indices = ( + (0, 1), (0, 2), (1, 3), (2, 3), + (4, 5), (4, 6), (5, 7), (6, 7), + (0, 4), (1, 5), (2, 6), (3, 7)) + +shader = gpu.shader.from_builtin('3D_UNIFORM_COLOR') +batch = batch_for_shader(shader, 'LINES', {"pos" : coords}, indices=indices) + +def draw(): + shader.bind() + shader.uniform_float("color", (1, 0, 0, 1)) + batch.draw(shader) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') \ No newline at end of file diff --git a/doc/python_api/examples/gpu.5.py b/doc/python_api/examples/gpu.5.py new file mode 100644 index 00000000000..7af3a518457 --- /dev/null +++ b/doc/python_api/examples/gpu.5.py @@ -0,0 +1,33 @@ +""" +Mesh with Random Vertex Colors +------------------------------ +""" +import bpy +import gpu +import numpy as np +from random import random +from gpu_extras.batch import batch_for_shader + +mesh = bpy.context.active_object.data +mesh.calc_loop_triangles() + +vertices = np.empty((len(mesh.vertices), 3), 'f') +indices = np.empty((len(mesh.loop_triangles), 3), 'i') + +mesh.vertices.foreach_get("co", + np.reshape(vertices, len(mesh.vertices) * 3)) +mesh.loop_triangles.foreach_get("vertices", + np.reshape(indices, len(mesh.loop_triangles) * 3)) + +vertex_colors = [(random(), random(), random(), 1) for _ in range(len(mesh.vertices))] + +shader = gpu.shader.from_builtin('3D_SMOOTH_COLOR') +batch = batch_for_shader(shader, 'TRIS', + {"pos" : vertices, + "color" : vertex_colors}, + indices=indices) + +def draw(): + batch.draw(shader) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW') \ No newline at end of file diff --git a/doc/python_api/examples/gpu.6.py b/doc/python_api/examples/gpu.6.py new file mode 100644 index 00000000000..df28d801960 --- /dev/null +++ b/doc/python_api/examples/gpu.6.py @@ -0,0 +1,24 @@ +""" +2D Rectangle +------------ +""" +import bpy +import gpu +from gpu_extras.batch import batch_for_shader + +vertices = ( + (100, 100), (300, 100), + (100, 200), (300, 200)) + +indices = ( + (0, 1, 2), (2, 1, 3)) + +shader = gpu.shader.from_builtin('2D_UNIFORM_COLOR') +batch = batch_for_shader(shader, 'TRIS', {"pos" : vertices}, indices=indices) + +def draw(): + shader.bind() + shader.uniform_float("color", (0, 0.5, 0.5, 1.0)) + batch.draw(shader) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_PIXEL') \ No newline at end of file diff --git a/doc/python_api/examples/gpu.7.py b/doc/python_api/examples/gpu.7.py new file mode 100644 index 00000000000..9f5fb4f5459 --- /dev/null +++ b/doc/python_api/examples/gpu.7.py @@ -0,0 +1,49 @@ +""" +2D Image +-------- +""" +import bpy +import gpu +import bgl +from gpu_extras.batch import batch_for_shader + +IMAGE_NAME = "Untitled" +image = bpy.data.images[IMAGE_NAME] + +coords = [ + (100, 100), (200, 100), + (100, 200), (200, 200)] + +uvs = [(0, 0), (1, 0), (0, 1), (1, 1)] + +indices = [(0, 1, 2), (2, 1, 3)] + +shader = gpu.shader.from_builtin('2D_IMAGE') +batch = batch_for_shader(shader, 'TRIS', + {"pos" : coords, + "texCoord" : uvs}, + indices=indices) + +# send image to gpu if it isn't there already +if image.gl_load(): + raise Exception() + +# texture identifier on gpu +texture_id = image.bindcode + +def draw(): + # in case someone disabled it before + bgl.glEnable(bgl.GL_TEXTURE_2D) + + # bind texture to image unit 0 + bgl.glActiveTexture(bgl.GL_TEXTURE0) + bgl.glBindTexture(bgl.GL_TEXTURE_2D, texture_id) + + shader.bind() + # tell shader to use the image that is bound to image unit 0 + shader.uniform_int("image", 0) + batch.draw(shader) + + bgl.glDisable(bgl.GL_TEXTURE_2D) + +bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_PIXEL') \ No newline at end of file diff --git a/doc/python_api/examples/gpu.shader.py b/doc/python_api/examples/gpu.shader.py new file mode 100644 index 00000000000..7ffd3fe85c8 --- /dev/null +++ b/doc/python_api/examples/gpu.shader.py @@ -0,0 +1,35 @@ +""" +Built-in shaders +++++++++++++++++ + +All built-in shaders have the ``mat4 ModelViewProjectionMatrix`` uniform. +The value of it can only be modified using the :class:`gpu.matrix` module. +""" + +2D_UNIFORM_COLOR: + attributes: vec3 pos + uniforms: vec4 color + +2D_FLAT_COLOR: + attributes: vec3 pos, vec4 color + uniforms: - + +2D_SMOOTH_COLOR: + attributes: vec3 pos, vec4 color + uniforms: - + +2D_IMAGE: + attributes: vec3 pos, vec2 texCoord + uniforms: sampler2D image + +3D_UNIFORM_COLOR: + attributes: vec3 pos + uniforms: vec4 color + +3D_FLAT_COLOR: + attributes: vec3 pos, vec4 color + uniforms: - + +3D_SMOOTH_COLOR: + attributes: vec3 pos, vec4 color + uniforms: - -- cgit v1.2.3