Updated documentation

doc/api/gloo-shader.rst

@@ -9,12 +9,24 @@ Shaders
 
 **Content**
 
+* :any:`program-section`         — Shader program
 * :any:`shader-section`          — Generic shader methods
 * :any:`vertex-shader-section`   — Vertex shader
 * :any:`fragment-shader-section` — Fragment shader
 * :any:`geometry-shader-section` — Geometry shader
 
 
+
+.. ----------------------------------------------------------------------------
+.. _program-section:
+
+Program
+=======
+
+.. autoclass:: glumpy.gloo.Program
+   :show-inheritance:
+   :members:
+
 .. ----------------------------------------------------------------------------
 .. _shader-section:
 

doc/api/gloo.rst

@@ -9,6 +9,7 @@ through buffers, textures and programs.
 * :any:`gpudata-section`             — Memory tracked numpy array
 * :any:`shaders-section`
 
+  * :any:`program-section`         — Shader program
   * :any:`shader-section`          — Generic shader methods
   * :any:`vertex-shader-section`   — Vertex shader
   * :any:`fragment-shader-section` — Fragment shader

doc/faq.rst

@@ -5,14 +5,15 @@
 .. _numpy:     http://www.numpy.org
 .. _scipy:     http://www.scipy.org 
 .. _vispy:     http://vispy.org
+.. _Vispy:     http://vispy.org
 
 ==========================
 Frequently Asked Questions
 ==========================
 
 **What is the relation between vispy and glumpy ?**
 
-   Vispy has been created by Luke Campagnola (pyqtgraph_) , Almar Klein
+   Vispy_ has been created by Luke Campagnola (pyqtgraph_) , Almar Klein
    (visvis_), Cyrille Rossant (galry_) and myself (Nicolas P. Rougier). During
    this development, I was still using glumpy to experiment some ideas in order
    to later port them into vispy. However, at some point, it was easier for me

doc/tutorial/cube-nice.rst

@@ -2,3 +2,181 @@
 Color, light & texture
 ======================
 
+Let's continue our OpenGL exploration using the same cube example as in previous
+section.
+
+.. image:: ../_static/color-cube.png
+   :align: left
+   :width: 45%
+
+.. image:: ../_static/outline-cube.png
+   :align: left
+   :width: 45%
+
+.. image:: ../_static/texture-cube.png
+   :align: left
+   :width: 45%
+
+.. image:: ../_static/light-cube.png
+   :align: left
+   :width: 45%
+
+
+Colored cube
+============
+
+Now we'll discover why glumpy is so useful. To add color per vertex to the
+cube, we simply define the vertex structure as:
+
+.. code::
+
+   V = np.zeros(8, [("a_position", np.float32, 3),
+                    ("a_color",    np.float32, 4)])
+   V["a_position"] = [[ 1, 1, 1], [-1, 1, 1], [-1,-1, 1], [ 1,-1, 1],
+                      [ 1,-1,-1], [ 1, 1,-1], [-1, 1,-1], [-1,-1,-1]]
+   V["a_color"]    = [[0, 1, 1, 1], [0, 0, 1, 1], [0, 0, 0, 1], [0, 1, 0, 1],
+                      [1, 1, 0, 1], [1, 1, 1, 1], [1, 0, 1, 1], [1, 0, 0, 1]]
+
+And we're done ! Well, actually, we also need to slightly modify the vertex
+shader since color is now an attribute (and not a constant).
+
+.. code::
+
+   vertex = """
+   uniform mat4   u_model;         // Model matrix
+   uniform mat4   u_view;          // View matrix
+   uniform mat4   u_projection;    // Projection matrix
+   attribute vec4 a_color;         // Vertex color
+   attribute vec3 a_position;      // Vertex position
+   varying vec4   v_color;         // Interpolated fragment color (out)
+   void main()
+   {
+       v_color = u_color;
+       gl_Position = u_projection * u_view * u_model * vec4(a_position,1.0);
+   } """
+
+   fragment = """
+   varying vec4   v_color;         // Interpolated fragment color (in)
+   void main()
+   {
+       gl_FragColor = v_color;
+   } """
+
+Furthermore, since our vertex buffer fields corresponds exactly to program
+attributes, we can directly bind it:
+
+.. code::
+
+   cube = gloo.Program(vertex, fragment)
+   cube.bind(V)
+
+.. note::
+
+   You could also have written
+
+   .. code::
+
+      cube = gloo.Program(vertex, fragment)
+      cube["a_position"] = V["a_position"]
+      cube["a_color"] = V["a_color"]
+      
+If you look closely at shader source, you'll see a new type of shader variable:
+
+.. code:: C
+
+   varying vec4 v_color; 
+
+
+This variable is a varying meaning it is interpolated between the vertex and
+the fragment stage. We just need to tell OpenGL the color of each vertex and it
+will compute the inteprolated color for each fragment, giving us a nice colored
+cube.
+
+For the lazy: `color-cube.py <https://github.com/glumpy/glumpy/blob/master/examples/tutorial/color-cube.py>`_
+
+
+Outlined cube
+=============
+
+We can make the cube a bit nicer by outlining it using black lines. To outline
+the cube, we need to draw lines between couple of vertices on each face. 4
+lines for the back and front face and 2 lines for the top and bottom faces. Why
+only 2 lines for top and bottom ? Because lines are shared between the
+faces. So overall we need 12 lines and we need to compute the corresponding
+indices (I did it for your):
+
+
+.. code:: python
+
+    O = [0,1, 1,2, 2,3, 3,0,
+         4,7, 7,6, 6,5, 5,4,
+         0,5, 1,6, 2,7, 3,4 ]
+    O = O.view(gloo.IndexBuffer)
+
+We then need to draw the cube twice. One time using triangles and the indices
+index buffer and one time using lines with the outline index buffer.  We need
+also to add some OpenGL black magic to make things nice. It's not very
+important to understand it at this point but roughly the idea to make sure lines
+are drawn "above" the cube because we paint a line on a surface.
+
+
+Textured cube
+=============
+
+
+.. code:: 
+
+   def cube():
+       vtype = [('a_position', np.float32, 3),
+                ('a_texcoord', np.float32, 2),
+                ('a_normal',   np.float32, 3),
+                ('a_color',    np.float32, 4)]
+       itype = np.uint32
+
+       # Vertices positions
+       p = np.array([[1, 1, 1], [-1, 1, 1], [-1, -1, 1], [1, -1, 1],
+                     [1, -1, -1], [1, 1, -1], [-1, 1, -1], [-1, -1, -1]], dtype=float)
+
+       # Face Normals
+       n = np.array([[0, 0, 1], [1, 0, 0], [0, 1, 0],
+                     [-1, 0, 1], [0, -1, 0], [0, 0, -1]])
+
+       # Vertice colors
+       c = np.array([[0, 1, 1, 1], [0, 0, 1, 1], [0, 0, 0, 1], [0, 1, 0, 1],
+                     [1, 1, 0, 1], [1, 1, 1, 1], [1, 0, 1, 1], [1, 0, 0, 1]])
+
+       # Texture coords
+       t = np.array([[0, 0], [0, 1], [1, 1], [1, 0]])
+
+       faces_p = [0, 1, 2, 3,  0, 3, 4, 5,   0, 5, 6, 1,
+                  1, 6, 7, 2,  7, 4, 3, 2,   4, 7, 6, 5]
+       faces_c = [0, 1, 2, 3,  0, 3, 4, 5,   0, 5, 6, 1,
+                  1, 6, 7, 2,  7, 4, 3, 2,   4, 7, 6, 5]
+       faces_n = [0, 0, 0, 0,  1, 1, 1, 1,   2, 2, 2, 2,
+                  3, 3, 3, 3,  4, 4, 4, 4,   5, 5, 5, 5]
+       faces_t = [0, 1, 2, 3,  0, 1, 2, 3,   0, 1, 2, 3,
+                  3, 2, 1, 0,  0, 1, 2, 3,   0, 1, 2, 3]
+
+       vertices = np.zeros(24, vtype)
+       vertices['a_position'] = p[faces_p]
+       vertices['a_normal']   = n[faces_n]
+       vertices['a_color']    = c[faces_c]
+       vertices['a_texcoord'] = t[faces_t]
+
+       filled = np.resize(
+          np.array([0, 1, 2, 0, 2, 3], dtype=itype), 6 * (2 * 3))
+       filled += np.repeat(4 * np.arange(6, dtype=itype), 6)
+
+       outline = np.resize(
+           np.array([0, 1, 1, 2, 2, 3, 3, 0], dtype=itype), 6 * (2 * 4))
+       outline += np.repeat(4 * np.arange(6, dtype=itype), 8)
+
+       vertices = vertices.view(gloo.VertexBuffer)
+       filled   = filled.view(gloo.IndexBuffer)
+       outline  = outline.view(gloo.IndexBuffer)
+       
+       return vertices, filled, outline
+
+
+Lighted cube
+============

doc/tutorial/cube-ugly.rst

@@ -84,6 +84,28 @@ useful for rotating an object around its center. To sum up, we need:
 * **Projection matrix** maps from camera to screen space
 
 
+Now, we can write out shaders:
+
+.. code:: python
+
+   vertex = """
+   uniform mat4   u_model;         // Model matrix
+   uniform mat4   u_view;          // View matrix
+   uniform mat4   u_projection;    // Projection matrix
+   attribute vec3 a_position;      // Vertex position
+   void main()
+   {
+       gl_Position = u_projection * u_view * u_model * vec4(a_position,1.0);
+   } """
+
+   fragment = """
+   void main()
+   {
+       gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
+   } """
+
+  
+
 Building a cube
 ===============
 
@@ -99,9 +121,9 @@ explicitly OpenGL what to draw with them:
 
 .. code:: python
             
-   V = np.zeros(8, [("position", np.float32, 3)])
-   V["position"] = [[ 1, 1, 1], [-1, 1, 1], [-1,-1, 1], [ 1,-1, 1],
-                    [ 1,-1,-1], [ 1, 1,-1], [-1, 1,-1], [-1,-1,-1]]
+   V = np.zeros(8, [("a_position", np.float32, 3)])
+   V["a_position"] = [[ 1, 1, 1], [-1, 1, 1], [-1,-1, 1], [ 1,-1, 1],
+                      [ 1,-1,-1], [ 1, 1,-1], [-1, 1,-1], [-1,-1,-1]]
 
 These describe vertices of a cube cented on (0,0,0) that goes from (-1,-1,-1)
 to (+1,+1,+1). Then we compute (mentally) what are the triangles for each face, i.e. we
@@ -121,7 +143,7 @@ We now need to upload these data to the GPU. Using gloo, the easiest way is to u
    I = I.view(gloo.IndexBuffer)
 
    cube = gloo.Program(vertex, fragment)
-   cube["position"] = V
+   cube["a_position"] = V
 
 We'll use the indices buffer when rendering the cube.
 
@@ -147,9 +169,9 @@ important):
    model = np.eye(4,dtype=np.float32)
    projection = np.eye(4,dtype=np.float32)
    glm.translate(view, 0,0,-5)
-   cube['model'] = model
-   cube['view'] = view
-   cube['projection'] = projection
+   cube['u_model'] = model
+   cube['u_view'] = view
+   cube['u_projection'] = projection
    phi, theta = 0,0
 
 It is now important to update the projection matrix whenever the window is
@@ -160,7 +182,7 @@ resized (because aspect ratio may have changed):
    @window.event
    def on_resize(width, height):
       ratio = width / float(height)
-      cube['projection'] = glm.perspective(45.0, ratio, 2.0, 100.0)
+      cube['u_projection'] = glm.perspective(45.0, ratio, 2.0, 100.0)
 
 
 Rendering
@@ -188,7 +210,7 @@ around the z axis (theta), then around the y axis (phi):
        model = np.eye(4, dtype=np.float32)
        glm.rotate(model, theta, 0, 0, 1)
        glm.rotate(model, phi, 0, 1, 0)
-       cube['model'] = model
+       cube['u_model'] = model
 
 We're now alsmost ready to render the whole scene but we need first to modify
 the initialization a little bit to enable depth testing:

doc/tutorial/easyway.rst

@@ -64,6 +64,8 @@ Glumpy takes care of building the buffer because we specified the vertex count
 value and will also bind the relevant attributes and uniforms to the program.
 You should obtain the same output as in previous section.
 
+`Full source code <https://github.com/glumpy/glumpy/blob/master/examples/tutorial/quad-simple.py>`_ is available on github
+
 
 A step further
 ==============

doc/tutorial/hardway.rst

@@ -246,3 +246,4 @@ Ok, we're done, we can now rewrite the display function:
 The 0, 4 arguments in the `glDrawArrays` tells OpenGL we want to display 4
 vertices from our array and we start at vertex 0.
 
+`Full source code <https://github.com/glumpy/glumpy/blob/master/examples/tutorial/quad-glut.py>`_ is available on github

doc/tutorial/resources.rst

@@ -0,0 +1,40 @@
+================
+Online resources
+================
+
+Learning
+========
+
+* This `page <http://www.songho.ca/opengl/index.html>`_ contains fundamental
+  OpenGL tutorials and notes.All example programs are written by C++ with
+  Code::Blocks and Orwell Dev-C++, as well as makefiles for Linux and Mac.
+
+* A new OpenGL `introduction
+  <http://duriansoftware.com/joe/An-intro-to-modern-OpenGL.-Table-of-Contents.html>`_
+  that walks through the parts that are still relevant today.
+
+* `Shadertoy <https://www.shadertoy.com>`_ is a great resources to experiment
+  and learn fragment shaders.
+
+
+References
+==========
+
+* `The OpenGL Registry <http://www.opengl.org/registry/>`_ contains
+  specifications, header files, and related documentation for OpenGL and
+  related APIs including GLU, GLX, and WGL.
+* `Quick reference <http://www.shaderific.com/glsl-functions/>`_ for the
+  built-in functions of the OpenGL ES Shading Language.
+* The `Graphics Codex <http://casual-effects.com/graphicscodex/>`_ is an app
+  for 3D graphics students, engineers, teachers, and artists. It provides
+  consistent, correct, and easy-to-understand definitions for technical
+  material.
+
+Blogs
+=====
+
+* `Iñigo Quílez <http://www.iquilezles.org/www/index.htm>`_
+* `Florian Boesch <http://codeflow.org>`_
+* `The Little Grasshoper <http://github.prideout.net>`_
+* `John Chapman <http://john-chapman-graphics.blogspot.fr/2013/01/ssao-tutorial.html>`_
+