Docs: Geometry and cleanup

Author: einarf

docs/source/controls.rst

@@ -6,8 +6,8 @@ Basic Keyboard Controls
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 - ``ESC`` to exit
-- ``SPACE`` to pause the current time
-- ``X`` for taking a screenshot (see settings)
+- ``SPACE`` to pause the current time (tells the configured timer to pause)
+- ``X`` for taking a screenshot (output path is configurable in settings)
 
 Camera Controls
 ^^^^^^^^^^^^^^^

docs/source/effectmanagers.rst

@@ -8,6 +8,22 @@ An effect manager is responsible of:
 - Knowing what effect should be drawn based in some internal state
 - Reading keyboard events if this is needed (optional)
 
+You are fairly free to do what you want. Having control over
+effect instantiation also means you can make multiple instances
+of the same effect and assign different resources to them.
+
+The most important part in the end is how you implement ``draw()``.
+
+Some sane or insane examples to get started:
+
+- Simply hard code what should run at what time or state
+- A manger that cycles what effect is active based on a next/previous key
+- Cycle effects based on a duration property you assign to them
+- Load some external timer data describing what effect should run at what time. This can
+  easily be done with rocket (we are planning to make a manager for this)
+- You could just put all your draw code in the manager and not use effects
+- Treat the manager as the main loop of a simple game
+
 This is an example of the default ``SingleEffectManager``.
 
 .. code-block:: python

docs/source/effects.rst

@@ -2,18 +2,18 @@
 Effects
 =======
 
-In order to draw something to the screen using this framework you need to make one or
-multiple effects. what these effects are doing is entirely up to you. Some like to
+In order to actually draw something to the screen you need to make one or
+multiple effects. What these effects are doing is entirely up to you. Some like to
 put everything into one effect and switch what they draw by flipping some internal
 states, but this is probably not practical for more complex things.
 
-An effect is a class with references to resources and a method for drawing.
-An effect is an independent python package of specific format.
+An effect is a class with references to resources such as shaders, geometry, fbos and textures
+and a method for drawing. An effect is an independent python package of specific format.
 
 The Effect Package
 ^^^^^^^^^^^^^^^^^^
 
-The effect package should have the following structure (assuming our effect is named "cube".
+The effect package should have the following structure (assuming our effect is named "cube").
 
 .. code-block:: bash
 
@@ -26,20 +26,29 @@ The effect package should have the following structure (assuming our effect is n
         └── cube
             └── ...
 
-The ``effect.py`` module is where the draw logic for the effect resides. Directories at the
-same level are for resources for the effect. Notice that the resource directories contains
-another directory with the name of the effect. This is because these folders are added to
-a virtual directory (for each resource type) so we should place it in a directory to
-reduce the change of name collisions. Two effects with the texture ``texture.png`` in
-the root of their local ``textures/`` directory will cause the first effect to
+The ``effect.py`` module is the actual code for the effect. Directories at the
+same level are for local resources for the effect.
+
+.. Note:: Notice that the resource directories contains another sub-directory with
+   the same name as the effect. This is because these folders are added to
+   a **virtual directory** (for each resource type), so we should place it in a directory to
+   reduce the chance of a name collisions.
+
+.. Note:: Two effects with the texture name ``texture.png`` in
+   the root of their local ``textures/`` directory will cause a name collision were
+   the texture from the first registered effect will be used in both effects.
+   This can be used to override resources intentionally.
+
+We can also decide not to have any effect-local resources and configure
+a project-global resource directory. More about this in :doc:`settings`.
 
 Registry
 ^^^^^^^^
 
-For an effect to be recognised by the system it has to be registered
+For an effect to be recognised by the system, it has to be registered
 in the ``EFFECTS`` tuple/list in your settings module.
 Simply add the full python path to the package. If our cube example
-above resides inside a ``myproject`` project package we need to add
+above is located inside a ``myproject`` project package we need to add
 the string ``myproject.cube``. See :doc:`settings`.
 
 You can always run a single effect by using the ``runeffect`` command.
@@ -48,7 +57,7 @@ You can always run a single effect by using the ``runeffect`` command.
 
     ./manage.py runeffect myproject.cube
 
-If you have multiple effects you need to crate or use an existing :doc:`effectmanagers`
+If you have multiple effects, you need to crate or use an existing :doc:`effectmanagers`
 that will decide what effect would be active at what time or state.
 
 Resources
@@ -64,24 +73,24 @@ resource finders in :doc:`settings`.
 The Effect Module
 ^^^^^^^^^^^^^^^^^
 
-The effect module in an effect package needs to be named ``effect.py`` and
-reside in the root of the package. It can only contain a single effect
+The effect module needs to be named ``effect.py`` and
+located in the root of the effect package. It can only contain a single effect
 class. The name of the class doesn't matter right now, but we are
 considering allowing multiple effects in the future, so giving it
-at least a descriptive name of that it represents is a good idea.
+at least a descriptive name is a good idea.
 
 There are two important methods in an effect:
+
 - ``__init__()``
-- draw()
+- ``draw()``
 
-The **initializer** is called before resources are loaded. This is so the
-effects can register the what resources they need. The resource
+The **initializer** is called before resources are loaded. This way the
+effects can register the resources they need. The resource
 managers will return an empty object that will be populated when
 loading starts.
 
-The **draw** method is called by the framework or from a your custom
-:doc:`effectmanagers` ever frame, or at least every frame the manager
-decides the effect should be active at least.
+The ``draw`` method is called by the configured `EffectManager`` (see :doc:`effectmanagers`)
+ever frame, or at least every frame the manager decides the effect should be active.
 
 The standard effect example:
 
@@ -121,20 +130,24 @@ The standard effect example:
 
 The parameters in the draw effect is:
 
-- ``time``: The current time reported by our configured Timer in seconds.
+- ``time``: The current time reported by our configured ``Timer`` in seconds.
 - ``frametime``: The time a frame is expected to take in seconds.
-  This is useful when you cannot use ``time``. Should be avoided.
+  This is useful when you cannot use time. Should be avoided.
 - ``target`` is the target FBO of the effect
 
-Time can potentially move at any speed or direction so it's good practice
+Time can potentially move at any speed or direction, so it's good practice
 to make sure the effect can run when time is moving in any direction.
 
 The ``bind_target`` decorator is useful when you want to ensure
 that an FBO passed to the effect is bound on entry and released on exit.
-By default a fake FBO is passed in representing the window framebuffer.
+By default a fake FBO is passed in representing the window frame buffer.
 EffectManagers can be used to pass in your own FBOs or another effect
 can call ``draw(..)`` requesting the result to end up in the FBO it passes in
-and then use this FBO as a texture on a cube.
+and then use this FBO as a texture on a cube or do post processing.
+
+As we can see in the example, the ``Effect`` base class have a couple
+of convenient methods for doing basic matrix math, but generally you
+are expected do to these calculations yourself.
 
 Effect Base Class
 ^^^^^^^^^^^^^^^^^

docs/source/geometry.rst

@@ -2,14 +2,156 @@
 Geometry
 ========
 
-Write stuff here.
+The ``demosys.opengl.geometry`` module currently provides some simple functions to generate VAOs.
 
-The geometry Module
-^^^^^^^^^^^^^^^^^^^
+- Quad: Full screen quads for drawing offscreen buffers
+- Cube: Cube with normals, uvs and texture coordinates
+- Plane: A plane with a dimension and resolution
+- Points: Random points in 3D
 
-Write stuff here.
+.. Nore:: We definitely need more here. Please make pull requests or make an issue on github.
 
 Creating Custom Geometry
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Write stuff here.
+To efficiently generate geometry in Python we must avoid as much memory allocation as possible.
+As mentioned in other sections we use PyOpenGL's VBO class that takes numpy arrays.
+We also use pyrr for vector and matrix math and representation.
+
+.. Note:: This is a "best practices" guide to efficiently generate geometry
+   with python code that will scale well even for large amounts of data.
+   This was benchmarked generating various vertex formats with 1M vertices.
+   For fairly small data sizes doesn't matter that much.
+
+The naive way to generate geometry would probably look something like this:
+
+.. code-block:: python
+
+   from OpenGL import GL
+   from OpenGL.arrays.vbo import VBO
+   import numpy
+   from pyrr import Vector3
+
+   def random_points(count):
+       points = []
+       for p in range(count):
+           # Let's pretend we calculated random values for x, y, z
+           points.append(Vector3([x, y, x]))
+
+       # Create VBO enforcing float32 values with numpy
+       points_vbo = VBO(numpy.array(points, dtype=numpy.float32))
+
+       vao = VAO("random_points", mode=GL.GL_POINTS)
+       vao.map_array_buffer(GL.GL_FLOAT, points_vbo)
+       vao.map_buffer(points_vbo, "in_position", 3))
+       vao.build()
+       return vao
+
+This works perfectly fine, but we allocate a new list for every iteration
+and pyrr internally creates a numpy array of this. The ``points`` list will also
+have to dynamically expand. This exponentially more ugly as the ``count``
+value increases.
+
+We move on to version 2:
+
+.. code-block:: python
+
+   def random_points(count):
+       # Pre-allocate a list containing zeros of length count
+       # We multiply by 3 to make room for a x, y and z value
+       points = [0] * count * 3
+       # Loop count time incrementing by 3 every frame
+       for p in range(0, count * 3, 3):
+           # Let's pretend we calculated random values for x, y, z
+           points[p] = x
+           points[p + 1] = y
+           points[p + 2] = z
+
+     points_vbo = VBO(numpy.array(points, dtype=numpy.float32))
+
+This version is orders of magnitude faster because we don't allocate memory
+in the loop. It has one glaring flaw though. It's not a very pleasant read
+even for such simple task, and it will not get any better if we add more complexity.
+
+Let's move on to version 3:
+
+.. code-block:: python
+
+   def random_points(count):
+       def generate():
+           for p in range(count):
+               # Let's pretend we calculated random values for x, y, z
+               yield x
+               yield y
+               yield z
+
+       points_vbo = VBO(numpy.fromiter(generate(), count=count * 3, dtype=numpy.float32)
+
+Using generators in python like this is much cleaner way. We also take advantage
+of numpy's ``fromiter()`` that basically slurps up all the numbers we emit with
+yield into its internal buffers. By also telling numpy what the final size of the
+buffer will be using the ``count`` parameter, it will pre-allocate this not having
+to dynamically increase it's internal buffer.
+
+Generators are extremely simple and powerful. If things get complex we can easily
+split things up in several functions because Pythons ``yield from`` can forward
+generators.
+
+Imagine generating a single VBO with interleaved position, normal and uv data:
+
+.. code-block:: python
+
+   def generate_stuff(count):
+       # Returns a distorted position of x, y, z
+       def pos(x, y, z):
+           # Calculate..
+           yield x
+           yield y
+           yield x
+
+       def normal(x, y, z):
+           # Calculate
+           yield x
+           yield y
+           yield z
+
+       def uv(x, y, x):
+           # Calculate
+           yield u
+           yield v
+
+       def generate(count):
+           for i in range(count):
+               # resolve current x, y, z pos
+               yield from pos(x, y, z)
+               yield from normal(x, y, z)
+               yield from uv(x, y, z)
+
+       interleaved_vbo = VBO(numpy.fromiter(generate(), count=count * 3, dtype=numpy.float32)
+
+
+The geometry Module
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: demosys.opengl.geometry.cube
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+.. automodule:: demosys.opengl.geometry.plane
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+.. automodule:: demosys.opengl.geometry.points
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+.. automodule:: demosys.opengl.geometry.quad
+    :members:
+    :undoc-members:
+    :show-inheritance: