Doc update: effect pacakges and performance

Author: einarf

docs/user_guide/effects.rst

@@ -2,15 +2,13 @@
 Effects
 =======
 
-In order to actually draw something to the screen you need to make one or
+In order to actually render 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.
+Effects have methods for fetching loaded resources and existing effect instances.
+Effects can also create new instances of effects if needed. This would
+happend during initialization.
 
-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.
+Effect examples can be found in the ``examples`` directory in the root of the repository.
 
 The Effect Package
 ------------------
@@ -21,133 +19,67 @@ named "cube").
 .. code-block:: bash
 
     cube
-    ├── effect.py
-    ├── shaders
-    │   └── cube
-    │       └── ...
-    └── textures
-        └── cube
-            └── ...
+    ├── effects.py
+    ├── dependencies.py
+    └── resources
+        └── programs
+            └── cube
+                └── cube.glsl
+        └── textures
+        └── scenes
+        └── data
 
-The ``effect.py`` module is the actual code for the effect. Directories at the
-same level are for local resources for the effect.
+The ``effects.py`` module can contain one or multiple effects.
+The effect package can also have no effects and all and only
+provide resources for other effects to use. The ``effects.py``
+module is still required to be present.
 
-.. Note:: Notice that the resource directories contains another sub-directory
-   with the same name as the effect directory/package. This is because these
-   folders are by default added to a project wide search path
-   (for each resource type),
-   so we should place it in a directory to reduce the chance of a name collisions.
+Dependencies
+------------
 
-We can also decide not to have any effect-local resources and configure
-a project-global resource directory. More about this `settings`.
+The ``dependencies.py`` module is required to be present. It describes
+its own resources and what effect packages it may depend on.
 
-Registry
---------
+Example::
 
-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 is located inside a ``myproject`` project package we need to add
-the string ``myproject.cube``. See `settings`.
+    from demosys.resources.meta import ProgramDescription
 
-You can always run a single effect by using the ``runeffect`` command.
+    effect_packages = 
+        'full.python.path.to.another.package',
+    ]
 
-.. code-block:: bash
-
-    ./manage.py runeffect myproject.cube
+    resources = [
+        ProgramDescription(label='cube_plain', path='cube_plain.glsl'),
+    ]
 
-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 are given labels and effects can fetch them by this label.
+When adding effect package dependencies we make the system aware
+of this package so their resources are also loaded. The effects
+in the depending package will also be registered in the system
+and can be instantiated.
 
 Resources
 ---------
 
-Resource loading is baked into the ``Effect`` base class. Methods are inherited
-from the base ``Effect`` class such as ``get_shader`` and ``get_texture``.
-
-Methods fetching resources can take additional parameters to override defaults.
-
-.. code-block:: python
-
-    # Generate mipmaps for the texture
-    self.get_texture("cube/texture.png", mipmap=True)
-
-The Effect Module
------------------
-
-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 is a good idea.
-
-There are two important methods in an effect:
-
-- ``__init__()``
-- ``draw()``
-
-The **initializer** is called before resources are loaded. This way the
-effects can register the resources they need. An opengl context should
-exist.
-
-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 ``resources`` directory contains fixed directory names where resources
+of specific types are supposed to be located. When an effect package is loaded
+paths to these directories are added so the system can find them.
 
-The standard effect example:
-
-.. code-block:: python
-
-    import moderngl as mgl
-    from demosys.effects import effect
-    from demosys import geometry
-    # from pyrr import matrix44
-
-
-    class SimpleCubeEffect(effect.Effect):
-        """Generated default effect"""
-        def __init__(self):
-            self.shader = self.get_shader("cube_plain.glsl", local=True)
-            self.cube = geometry.cube(4.0, 4.0, 4.0)
-
-        @effect.bind_target
-        def draw(self, time, frametime, target):
-            self.ctx.enable(mgl.DEPTH_TEST)
-
-            # Rotate and translate
-            m_mv = self.create_transformation(rotation=(time * 1.2, time * 2.1, time * 0.25),
-                                            translation=(0.0, 0.0, -8.0))
-
-            # Apply the rotation and translation from the system camera
-            # m_mv = matrix44.multiply(m_mv, self.sys_camera.view_matrix)
-
-            # Create normal matrix from model-view
-            m_normal = self.create_normal_matrix(m_mv)
-
-            # Draw the cube
-            self.shader.uniform("m_proj", self.sys_camera.projection.tobytes())
-            self.shader.uniform("m_mv", m_mv.astype('f4').tobytes())
-            self.shader.uniform("m_normal", m_normal.astype('f4').tobytes())
-            self.shader.uniform("time", time)
-            self.cube.draw(self.shader)
-
-The parameters in the draw effect is:
-
-- ``time``: The current time reported by our configured ``Timer`` in seconds.
-- ``frametime``: The time a frame is expected to take in seconds.
-- ``target`` is the target FBO of the effect
+.. Note:: Notice that the resource directories contains another sub-directory
+   with the same name as the effect package. This is because these
+   folders are by default added to a project wide search path
+   (for each resource type),
+   so we should place it in a directory to reduce the chance of a name collisions.
 
-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.
+Having resources in the effect package itself is entirely optional.
+Resources can be located anywhere you want as long as you tell the system
+where they can be found. This is covered in :doc:`/settings`.
 
-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 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 or do post processing.
+Reasons to have resources in effect packages is to create an independent
+resuable effect package you could even distribute. Also when a project
+grows with lots of effect packages it can be nice to keep the effect
+specific resources in the effect package they belong to instead of
+putting all resources for the entire project in the same location.
 
-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.
+The Effect base class have methods avaiable for fetching loaded resources.
+See the :py:class:`demosys.effects.Effect`

docs/user_guide/performance.rst

@@ -11,31 +11,28 @@ This is ignoring delays or blocks caused by OpenGL calls.
 
     How important performance is will of course depend on the project.
     Visualization for a scientific application doing some heavy
-    calculations would probably not need to run at 60 fps.
+    calculations would probably not need to run at 60+ fps.
     It's also not illegal to not care about performance.
 
 Probably the biggest enemy to performance in python is **memory allocation**.
-
-Try to avoid creating new objects every frame if possible. This includes
-all mutable data types such as lists, sets, dicts.
-
-Another area is updating buffer object data such as VBOs and
-Textures. If these are of a fairly small size it might not be a problem,
-but do not expect pure Python code to be able to efficiently feed CPU-generated data
-to OpenGL. If this data comes from a library though ctypes and we
-can avoid re-allocating memory for each frame we might be good,
-but this is not always easy to determine and will needs testing.
+Try to avoid creating new objects when possible.
 
 Try to do as much as possible on the GPU. Use features like transform
 feedback to alter buffer data and use your creativity to find efficient
 solutions.
 
+When doing many draw calls, do as little as possible between those
+draw calls. Doing matrix math in python even with numpy or pyrr
+is **extremely slow**. Try to calculate them ahead of time. Also
+moving the matrix calculations inside the shader programs can
+help greatly. You can easily do 1000 draw calls using the same
+cube and still run 60+ fps even on older hardware. The minute
+you throw in some matrix calculation in that loop you might
+be able to draw 50 before the framerate tanks.
+
 Performance in rendering is not straight forward to measure in any language.
 Simply adding timers in the code will not really tell us much unless
 we also query OpenGL about the performance.
 
-We could also try to compile your project with pypy, but we have not tested
-this (yet).
-
 We can also strive to do more with less. Rendering, in the end, is really just
 about creating illusions.