Basic effect docs

Author: einarf

demosys/effects/effect.py

@@ -3,7 +3,15 @@
 
 
 def bind_target(func):
-    """Decorator auto binding and releasing the incoming FBO"""
+    """
+    Decorator auto binding and releasing the incoming FBO in ``draw()``.
+
+    literal blocks::
+
+       @bind_target
+        def draw(...):
+            # draw stuff
+    """
     def func_wrapper(*args, **kwargs):
         args[3].bind()
         func(*args, **kwargs)
@@ -12,6 +20,15 @@ def func_wrapper(*args, **kwargs):
 
 
 class Effect:
+    """Effect base class.
+
+    The following attributes are injected by demosys before initialization:
+
+    * window_width (int): Window width in pixels
+    * window_height (int): Window height in pixels
+    * window_aspect (float): Aspect ratio of the resolution
+    * sys_camera (demosys.scene.camera.Camera): The system camera responding to inputs
+    """
     # Window properties set by controller on initialization
     name = ""
     window_width = 0
@@ -21,22 +38,61 @@ class Effect:
 
     # Methods to override
     def draw(self, time, frametime, target):
+        """Draw function called by the system every frame.
+
+        :param time: The current time in seconds (float)
+        :param frametime: The number of milliseconds the frame is expected to take
+        :param target: The target FBO for the effect
+        """
         raise NotImplemented
 
     # Methods for getting resources
 
     def get_shader(self, path):
+        """
+        Get a shader or schedule the shader for loading.
+        If the resource is not loaded yet, an empty shader object
+        is returned that will be populated later.
+
+        :param path: Path to the shader in the virtual shader directory
+        :return: Shader object
+        """
         return resources.shaders.get(path, create=True)
 
     def get_texture(self, path):
+        """
+        Get a shader or schedule the texture for loading.
+        If the resource is not loaded yet, an empty texture object
+        is returned that will be populated later.
+
+        :param path: Path to the texture in the virtual texture directory
+        :return: Texture object
+        """
         return resources.textures.get(path, create=True)
 
     def get_track(self, name):
+        """
+        Get or create a rocket track. This only makes sense when using rocket timers.
+        If the resource is not loaded yet, an empty track object
+        is returned that will be populated later.
+
+        :param name: The rocket track name
+        :return: Track object
+        """
         return resources.tracks.get(name)
 
     # Utility methods for matrices
 
     def create_projection(self, fov=75.0, near=1.0, far=100.0, ratio=None):
+        """
+        Create a projection matrix with the following parameters.
+
+        :param fov: Field of view (float)
+        :param near: Camera near value
+        :param far: Camrea far value
+        :param ratio: Aspect ratio of the window
+        :return: The projection matrix
+        """
         return matrix44.create_perspective_projection_matrix(
             fov,
             ratio or self.window_aspect,
@@ -64,7 +120,13 @@ def create_transformation(self, rotation=None, translation=None):
         return mat
 
     def create_normal_matrix(self, modelview):
-        """Convert to mat3 and return inverse transpose"""
+        """
+        Convert to mat3 and return inverse transpose.
+        These are normally needed when dealing with normals in shaders.
+
+        :param modelview: The modelview matrix
+        :return: Normal matrix
+        """
         normal_m = Matrix33.from_matrix44(modelview)
         normal_m = normal_m.inverse
         normal_m = normal_m.transpose()

docs/source/conf.py

@@ -21,10 +21,15 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
 import sphinx.environment
 from docutils.utils import get_source_line
 
 
+# Define a settings module
+os.environ['DEMOSYS_SETTINGS_MODULE'] = 'demosys.conf.default_settings'
+
+
 # Monkey patch sphinx to ignore: WARNING: nonlocal image URI
 def _warn_node(self, msg, node, **kwargs):
     if not msg.startswith('nonlocal image URI found:'):
@@ -65,9 +70,9 @@ def _warn_node(self, msg, node, **kwargs):
 # built documents.
 #
 # The short X.Y version.
-version = '0.3.5'
+version = '0.3.6'
 # The full version, including alpha/beta/rc tags.
-release = '0.3.5'
+release = '0.3.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/effects.rst

@@ -0,0 +1,10 @@
+
+Effects
+=======
+
+Effect documentation
+
+.. autoclass:: demosys.effects.effect.Effect
+   :members: draw, get_shader, get_texture, get_track, create_projection, create_transformation, create_normal_matrix
+
+.. autofunction:: demosys.effects.effect.bind_target

docs/source/index.rst

@@ -30,6 +30,7 @@ time creating all the tooling to get things up and running.
    quickstart
    controls
    settings
+   effects
    tempnotes
 
 Indices and tables