From a4bfccc439792be10df92541595f8f3ef0ca7fe7 Mon Sep 17 00:00:00 2001
From: Jacques Lucke <mail@jlucke.com>
Date: Fri, 9 Nov 2018 19:20:34 +0100
Subject: Py API Docs: More gpu module documentation

---
 doc/python_api/examples/gpu.1.py | 67 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/python_api/examples/gpu.1.py b/doc/python_api/examples/gpu.1.py
index c23df30e28a..1ffa0a58856 100644
--- a/doc/python_api/examples/gpu.1.py
+++ b/doc/python_api/examples/gpu.1.py
@@ -11,7 +11,10 @@ This makes them much faster than using the legacy `glBegin` and `glEnd` method,
 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.
+Which attributes the vertex buffer of a batch contains, depends on the shader that will be used to process the batch. The best way to create a new batch is to use the :class:`gpu_extras.batch.batch_for_shader` function.
+
+Furthermore, when creating a new batch, you have to specify the draw type.
+The most used types are ``POINTS``, ``LINES`` and ``TRIS``.
 
 Shaders
 +++++++
@@ -38,6 +41,68 @@ The attributes and uniforms used by built-in shaders are listed here: :class:`gp
 
 A batch can only be processed/drawn by a shader when it provides all the attributes that the shader specifies.
 
+Vertex Buffers
+++++++++++++++
+
+A vertex buffer is an array that contains the attributes for every vertex.
+To create a new vertex buffer (:class:`gpu.types.GPUVertBuf`) you have to provide two things: 1) the amount of vertices in the buffer and 2) the format of the buffer.
+
+The format (:class:`gpu.types.GPUVertFormat`) describes which attributes are stored in the buffer.
+E.g. to create a vertex buffer that contains 6 vertices, each with a position and a normal could look like so::
+
+    import gpu
+    vertex_positions = [(0, 0, 0), ...]
+    vertex_normals = [(0, 0, 1), ...]
+
+    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)
+
+    batch = gpu.types.GPUBatch(type='TRIS', buf=vbo)
+
+This batch contains two triangles now.
+Vertices 0-2 describe the first and vertices 3-5 the second triangle.
+
+.. note::
+    The recommended way to create batches is to use the :class:`gpu_extras.batch.batch_for_shader` function. It makes sure that you provide all the vertex attributes that are necessary to be able to use a specific shader.
+
+Index Buffers
++++++++++++++
+
+The main reason why index buffers exist is to reduce the amount of memory required to store and send geometry.
+E.g. often the same vertex is used by multiple triangles in a mesh.
+Instead of vertex attributes multiple times to the gpu, an index buffer can be used.
+An index buffer is an array of integers that describes in which order the vertex buffer should be read.
+E.g. when you have a vertex buffer ``[a, b, c]`` and an index buffer ``[0, 2, 1, 2, 1, 0]`` it is like if you just had the vertex buffer ``[a, c, b, c, b, a]``.
+Using an index buffer saves memory because usually a single integer is smaller than all attributes for one vertex combined.
+
+Index buffers can be used like so::
+
+    indices = [(0, 1), (2, 0), (2, 3), ...]
+    ibo = gpu.types.GPUIndexBuf(type='LINES', seq=indices)
+    batch = gpu.types.GPUBatch(type='LINES', buf=vbo, elem=ibo)
+
+.. note::
+    Instead of creating index buffers object manually, you can also just use the optional `indices` parameter of the :class:`gpu_extras.batch.batch_for_shader` function.
+
+Offscreen Rendering
++++++++++++++++++++
+
+Everytime something is drawn, the result is written into a framebuffer.
+Usually this buffer will later be displayed on the screen.
+However, sometimes you might want to draw into a separate "texture" and use it further.
+E.g. you could use the render result as a texture on another object or save the rendered result on disk.
+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 also means that once Blender discards this context (i.e. a window is closed) the offscreen instance will also be freed.
+
+
 Examples
 ++++++++
 
-- 
cgit v1.2.3