Started relocation of code, images & movies

Author: rougier

01-preface.rst

@@ -127,8 +127,8 @@ If you want to contribute to this book, you can:
 * Suggest improvements (https://github.com/rougier/python+opengl/pulls)
 * Correct English (https://github.com/rougier/python+opengl/issues)
 * Star the project (https://github.com/rougier/python+opengl)
-* Suggest a more responvise design for the HTML Book
-* Design a nice latex template for a PDF version
+* Suggest a more responsive design for the HTML Book
+* Spread the word about this book (Reddit, Hacker News, etc.)
 
 Publishing
 ++++++++++
@@ -158,6 +158,17 @@ Alike 4.0 International License <https://creativecommons.org/licenses/by-nc-sa/4
 
 The licensor cannot revoke these freedoms as long as you follow the license terms.
 
+Under the following terms:
+
+* **Attribution** — You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made. You may do so in any reasonable
+  manner, but not in any way that suggests the licensor endorses you or your
+  use.
+* **NonCommercial** — You may not use the material for commercial purposes.
+* **ShareAlike** — If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same license as the original.
+
+
 Code
 ++++
 
@@ -177,7 +188,7 @@ mainly) a researcher with several students to supervise, researches to do,
 grants to write, talks to prepare, etc.
 
 Consequently, if you really want to have a PDF version, you'll have to
-explicitely express your interest by contributing a small amount of
+explicitly express your interest by contributing a small amount of
 money. Then,
 
 * if the total reach **5,000 euros**, I'll produce the PDF
@@ -188,7 +199,7 @@ reached. In such case, consider your payment as a donation to the online
 version. If you find this unfair, remember you have the choice to give or not
 and the online version is free and open source...
 
-.. image:: crowdfunding.png
+.. image:: images/chapter-01/crowdfunding.png
    :width: 100%
 
 

02-introduction.rst

@@ -21,7 +21,7 @@ OpenGL is 25 years old! Since the first release in 1992, a lot has happened
 (and is still happening actually, with the newly released Vulkan_ API and the
 4.6 GL release) and consequently, before diving into the book, it is important
 to understand OpenGL API evolution over the years. If the first API (1.xx) has
-not changed too much in the first twelve years, a big change occured in 2004
+not changed too much in the first twelve years, a big change occurred in 2004
 with the introduction of the dynamic pipeline (OpenGL 2.x), i.e. the use of
 shaders that allow to have direct access to the GPU. Before this version,
 OpenGL was using a fixed pipeline that made it easy to rapidly prototype some
@@ -130,8 +130,8 @@ API).
 .. note::
 
   The number of functions and constants have been computed using the
-  `<code/registry.py>`_ program that parses the gl.xml_ file that defines the
-  OpenGL and OpenGL API Registry
+  `<code/chapter-02/registry.py>`_ program that parses the gl.xml_ file that
+  defines the OpenGL and OpenGL API Registry
 
 ======== ========= ========= === ============ ========= =========
 Version  Constants Functions     Version      Constants Functions
@@ -167,7 +167,7 @@ The graphic pipeline
 .. Note::
 
    The shader language is called glsl.  There are many versions that goes from 1.0
-   to 1.5 and subsequents version get the number of OpenGL version. Last version
+   to 1.5 and subsequent version get the number of OpenGL version. Last version
    is 4.6 (June 2017).
 
 If you want to understand modern OpenGL, you have to understand the graphic
@@ -178,7 +178,7 @@ depending on the version of OpenGL you're using), they will act at different
 stage of the rendering pipeline. To simplify this tutorial, we'll use only
 **vertex** and **fragment** shaders as shown below:
 
-.. image:: data/gl-pipeline.png
+.. image:: images/chapter-02/gl-pipeline.png
    :width: 100%
 
 A vertex shader acts on vertices and is supposed to output the vertex
@@ -207,7 +207,7 @@ output the null vertex (`gl_Position` is a special variable) while the second
 will only output the black color for any fragment (`gl_FragColor` is also a
 special variable). We'll see later how to make them to do more useful things.
 
-One question remains: when are those shaders exectuted exactly ? The vertex
+One question remains: when are those shaders executed exactly ? The vertex
 shader is executed for each vertex that is given to the rendering pipeline
 (we'll see what does that mean exactly later) and the fragment shader is
 executed on each fragment (= pixel) that is generated after the vertex
@@ -246,7 +246,7 @@ structured array using numpy_:
 
 We just created a CPU buffer with 4 vertices, each of them having a
 `position` (3 floats for x,y,z coordinates) and a `color` (4 floats for
-red, blue, green and alpha channels). Note that we explicitely chose to have 3
+red, blue, green and alpha channels). Note that we explicitly chose to have 3
 coordinates for `position` but we may have chosen to have only 2 if were to
 work in two-dimensions. Same holds true for `color`. We could have used
 only 3 channels (r,g,b) if we did not want to use transparency. This would save
@@ -263,8 +263,8 @@ using 2 floats for position and 4 floats for color:
 
 .. code:: python
 
-  data = numpy.zeros(4, dtype = [ ("position", np.float32, 2),
-                                  ("color",    np.float32, 4)] )
+   data = numpy.zeros(4, dtype = [ ("position", np.float32, 2),
+                                   ("color",    np.float32, 4)] )
 
 We need to tell the vertex shader that it will have to handle vertices where a
 position is a tuple of 2 floats and color is a tuple of 4 floats. This is
@@ -273,19 +273,19 @@ vertex shader:
 
 .. code:: glsl
 
-  attribute vec2 position;
-  attribute vec4 color;
-  void main()
-  {
-      gl_Position = vec4(position, 0.0, 1.0);
-  }
+   attribute vec2 position;
+   attribute vec4 color;
+   void main()
+   {
+       gl_Position = vec4(position, 0.0, 1.0);
+   }
 
 This vertex shader now expects a vertex to possess 2 attributes, one named
 `position` and one named `color` with specified types (vec3 means tuple of
 3 floats and vec4 means tuple of 4 floats). It is important to note that even
 if we labeled the first attribute `position`, this attribute is not yet bound
 to the actual `position` in the numpy array. We'll need to do it explicitly
-at some point in our program and there is no omagic that will bind the numpy
+at some point in our program and there is no magic that will bind the numpy
 array field to the right attribute, you'll have to do it yourself, but we'll
 see that later.
 
@@ -296,44 +296,44 @@ we would thus write:
 
 .. code:: glsl
 
-  uniform float scale;
-  attribute vec2 position;
-  attribute vec4 color;
-  void main()
-  {
-      gl_Position = vec4(position*scale, 0.0, 1.0);
-  }
+   uniform float scale;
+   attribute vec2 position;
+   attribute vec4 color;
+   void main()
+   {
+       gl_Position = vec4(position*scale, 0.0, 1.0);
+   }
 
 Last type is the varying type that is used to pass information between the
 vertex stage and the fragment stage. So let us suppose (again) we want to pass
 the vertex color to the fragment shader, we now write:
 
 .. code:: glsl
 
-  uniform float scale;
-  attribute vec2 position;
-  attribute vec4 color;
-  varying vec4 v_color;
+   uniform float scale;
+   attribute vec2 position;
+   attribute vec4 color;
+   varying vec4 v_color;
 
-  void main()
-  {
-      gl_Position = vec4(position*scale, 0.0, 1.0);
-      v_color = color;
-  }
+   void main()
+   {
+       gl_Position = vec4(position*scale, 0.0, 1.0);
+       v_color = color;
+   }
 
 and then in the fragment shader, we write:
 
 .. code:: glsl
 
-  varying vec4 v_color;
+   varying vec4 v_color;
 
-  void main()
-  {
-      gl_FragColor = v_color;
-  }
+   void main()
+   {
+       gl_FragColor = v_color;
+   }
 
 The question is what is the value of `v_color` inside the fragment shader ?
-If you look at the figure that introduced the gl pipleline, we have 3 vertices
+If you look at the figure that introduced the gl pipeline, we have 3 vertices
 and 21 fragments. What is the color of each individual fragment ?
 
 The answer is *the interpolation of all 3 vertices color*. This interpolation
@@ -350,7 +350,7 @@ State of the union
 Last, but not least, we need to access the OpenGL library from within Python
 and we have mostly two solutions at our disposal. Either we use pure bindings
 and we have to program everything (see next chapter) or we use an engine that
-provide a lot oc convenient functions that ease the development. We'll first
+provide a lot of convenient functions that ease the development. We'll first
 use the PyOpenGL bindings before using the glumpy_ library that offers a tight
 integration with numpy.
 
@@ -476,6 +476,6 @@ Libraries
 .. _gl.xml:
        https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/gl.xml
 .. _registry.py:
-       code/registry.py
+       code/chapter-02/registry.py
 
 .. ----------------------------------------------------------------------------

03-quickstart.rst

@@ -1,4 +1,3 @@
-
 Quickstart
 ===============================================================================
 
@@ -29,7 +28,7 @@ simple colored quad (i.e. a red square).
 Normalize Device Coordinates
 ++++++++++++++++++++++++++++
 
-.. figure:: data/NDC.png
+.. figure:: images/chapter-03/NDC.png
    :figwidth: 40%
    :figclass: left
 
@@ -58,7 +57,7 @@ some problems, especially when you're dealing with the mouse pointer whose
 Triangulation
 +++++++++++++
 
-.. figure:: data/triangulation.png
+.. figure:: images/chapter-03/triangulation.png
    :figwidth: 35%
    :figclass: left
 
@@ -104,7 +103,7 @@ is exactly what we need to tell OpenGL.
 GL Primitives
 +++++++++++++
 
-.. figure:: data/gl-primitives.png
+.. figure:: images/chapter-03/gl-primitives.png
    :figwidth: 40%
    :figclass: left
 
@@ -143,7 +142,7 @@ structure.
 Interpolation
 +++++++++++++
 
-.. figure:: data/interpolation.png
+.. figure:: images/chapter-03/interpolation.png
    :figwidth: 40%
    :figclass: left
 
@@ -457,7 +456,7 @@ We're done, we can now rewrite the display function:
        gl.glDrawArrays(gl.GL_TRIANGLE_STRIP, 0, 4)
        glut.glutSwapBuffers()
 
-.. figure:: data/glumpy-quad-solid.png
+.. figure:: images/chapter-03/glumpy-quad-solid.png
    :figwidth: 30%
    :figclass: left
 
@@ -469,7 +468,7 @@ 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 current active buffer and we start at vertex 0. You should
 obtain the figure on the right with the same red (boring) color. The whole
-source ia available from `<code/glut-quad-solid.py>`_.
+source ia available from `<code/chapter-03/glut-quad-solid.py>`_.
 
 All these operations are necessary for displaying a single colored quad on
 screen and complexity can escalate pretty badly if you add more objects,
@@ -483,7 +482,7 @@ Python applications.
 Uniform color
 +++++++++++++
 
-.. figure:: data/glumpy-quad-uniform-color.png
+.. figure:: images/chapter-03/glumpy-quad-uniform-color.png
    :figwidth: 30%
    :figclass: left
 
@@ -527,7 +526,7 @@ Varying color
 +++++++++++++
 
 
-.. figure:: data/glumpy-quad-varying-color.png
+.. figure:: images/chapter-03/glumpy-quad-varying-color.png
    :figwidth: 30%
    :figclass: left
 
@@ -812,7 +811,7 @@ the rendering is now a matter of writing the proper shader. We'll get a first
 taste in the three exercises below but we'll see much more powerful shader
 tricks in the next chapters.
 
-.. figure:: data/quad-scale.mp4
+.. figure:: movies/chapter-03/quad-scale.mp4
    :loop:
    :autoplay:
    :controls:
@@ -831,11 +830,11 @@ order for the quad to be animated and to scale with time as shown in the figure
 on the right. You will need to update the scale factor within the Python
 program, for example in the `draw` function.
 
-Solution: `<code/quad-scale.py>`_
+Solution: `<code/chapter-03/quad-scale.py>`_
 
 ----
 
-.. figure:: data/quad-rotate.mp4
+.. figure:: movies/chapter-03/quad-rotate.mp4
    :loop:
    :autoplay:
    :controls:

04-maths.rst

@@ -1,4 +1,3 @@
-
 Basic Mathematics
 ===============================================================================
 
@@ -49,7 +48,7 @@ Let us consider for example a simple set of point `[-1.0, -0.5, 0.0, +0.5,
 is discared and won't be visible into the final projection) The question now is
 how do we project the points onto the screen?
 
-.. figure:: data/1D-H-Coordinates.png
+.. figure:: images/chapter-04/1D-H-Coordinates.png
    :figwidth: 50%
    :figclass: right
 
@@ -70,7 +69,7 @@ in our unidimensional Euclidean space. From this conversion, we can see
 immediately that there exist actually an infinite set of homogenous coordinates
 that correspond to a single Cartesian coordinate as illustrated on the figure.
 
-.. figure:: data/1D-Projection.png
+.. figure:: images/chapter-04/1D-Projection.png
    :figwidth: 100%
 
    Figure
@@ -135,7 +134,7 @@ by Sam Hocevar:
 Transformations
 -------------------------------------------------------------------------------
 
-.. figure:: data/composition.png
+.. figure:: images/chapter-04/composition.png
    :figwidth: 50%
    :figclass: right