Update documentation

glumpy · Dec 24, 2015 · 0441b77 · 0441b77
1 parent dbfedff
commit 0441b77
Show file tree

Hide file tree

Showing 13 changed files with 117 additions and 32 deletions.
diff --git a/doc/examples-app.rst b/doc/examples-app.rst
@@ -9,8 +9,11 @@
 .. _app-two-windows.py:  https://github.com/glumpy/glumpy/blob/master/examples/app-two-windows.py
 .. _app-two-programs.py: https://github.com/glumpy/glumpy/blob/master/examples/app-two-programs.py
 
+.. ----------------------------------------------------------------------------
+.. _section-examples-app:
+
 =================
-Application (app)
+Application layer
 =================
 
 The ``glumpy.app`` layer is responsible for opening a window and handling

diff --git a/doc/examples-candy.rst b/doc/examples-candy.rst
@@ -1,10 +1,33 @@
-=========
-Eye-candy
-=========
-
-* Spiral galaxy
-* Fireworks
-* Voronoi
-* Quiver plot
-* Realtime signals
-* Tiger
+.. _galaxy.py:     https://github.com/glumpy/glumpy/blob/master/examples/galaxy.py
+.. _fireworks.py:  https://github.com/glumpy/glumpy/blob/master/examples/fireworks.py
+.. _voronoi.py:    https://github.com/glumpy/glumpy/blob/master/examples/voronoi.py
+.. _tiger.py:      https://github.com/glumpy/glumpy/blob/master/examples/tiger.py
+.. _spherical-harmonics.py: https://github.com/glumpy/glumpy/blob/master/examples/spherical-harmonics.py
+.. _mandelbrot.py: https://github.com/glumpy/glumpy/blob/master/examples/mandelbrot.py
+
+.. ----------------------------------------------------------------------------
+.. _section-examples-candy:
+
+========================
+Eye-candy demonstrations
+========================
+
+* galaxy.py_
+    Simulation of a spiral galaxy adapted from `Ingo Berg
+    <http://articles.beltoforion.de/article.php?a=spiral_galaxy_renderer&hl=en>`_ blog post.
+
+* fireworks.py_
+    Exploding fireworks adapted from the OpenGL ES 2.0 programming guide
+
+* voronoi.py_
+    Voronoi diagram made of cones viewed from above (see `Kennet Hoff's
+    homepage <http://gamma.cs.unc.edu/VORONOI/>`_)
+
+* tiger.py_
+    The famous postscript tiger rendered using two collections.
+
+* spherical-harmonics.py_
+    Morphing spherical harmonics computed on the GPU.
+
+* mandelbrot.py_
+    The mandatory mandelbrot set computed on the GPU.
diff --git a/doc/examples-collection.rst b/doc/examples-collection.rst
@@ -1,10 +1,40 @@
+.. _collection-point.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-point.py
+.. _collection-segment.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-segment.py
+.. _collection-path.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-path.py
+.. _collection-glyph.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-glyph.py
+.. _collection-markers.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-markers.py
+.. _collection-triangles.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-triangles.py
+.. _collection-update.py: https://github.com/glumpy/glumpy/blob/master/examples/collection-update.py
+
+.. ----------------------------------------------------------------------------
+.. _section-examples-collection:
+
 ===========
 Collections
 ===========
 
-* Points
-* Lines
-* Triangles
-* Markers
-* Antialiased solid lines
-* Antialiased dashed lines
+* collection-point.py_
+    This examples show a growing collection (up to 100000) of random colored
+    antialiased points.
+
+* collection-segment.py_
+    This examples show antialiased line segments with (float) thickness varying
+    from 1 to 8 pixels.
+
+* collection-path.py_
+    This examples shows 2500 antialiased stars with proper line joins.
+
+* collection-glyph.py_
+    This examples displays a text in 3D (use mouse to manipulate)
+
+* collection-markers.py_
+    This examples displays a shrinking collection of hearts. When the
+    collection is empty, the program exits.
+
+* collection-triangles.py_
+    This examples uses two collection (path and triangles) to display filled
+    stars.
+
+* collection-update.py_
+    This examples uses a custom collection to display 320 signals of 1000 point
+    each. Each signal can be zoomed individually using the mouse.
diff --git a/doc/examples-computation.rst b/doc/examples-computation.rst
@@ -3,6 +3,9 @@
 .. _smoke.py:        https://github.com/glumpy/glumpy/blob/master/examples/smoke/smoke.py
 .. _GPGPU:           http://gpgpu.org
 
+.. ----------------------------------------------------------------------------
+.. _section-examples-computation:
+
 ===========
 Computation
 ===========

diff --git a/doc/examples-filter.rst b/doc/examples-filter.rst
@@ -2,6 +2,9 @@
 .. _filter-blur.py:     https://github.com/glumpy/glumpy/blob/master/examples/filter-blur.py
 .. _filter-compose.py:  https://github.com/glumpy/glumpy/blob/master/examples/filter-compose.py
 
+.. ----------------------------------------------------------------------------
+.. _section-examples-filter:
+
 =======
 Filters
 =======

diff --git a/doc/examples-gloo.rst b/doc/examples-gloo.rst
@@ -25,9 +25,12 @@
 .. _gloo-frame.py:           https://github.com/glumpy/glumpy/blob/master/examples/gloo-frame.py
 .. _gloo-transparency.py:    https://github.com/glumpy/glumpy/blob/master/examples/gloo-transparency.py
 
-======================
-Object Oriented (gloo)
-======================
+.. ----------------------------------------------------------------------------
+.. _section-examples-gloo:
+
+============
+OpenGL layer
+============
 
 The ``glumpy.gloo`` layer is the heart of glumpy and is responsible for talking
 to the GPU throught buffers, textures and programs. This is done quite

diff --git a/doc/examples-misc.rst b/doc/examples-misc.rst
@@ -8,3 +8,5 @@ Miscellaneous
 * Heighfields
 * High-frequency signal
 * Image spatial interpolations
+* Realtime signals
+* Quiver plot
diff --git a/doc/examples-transform.rst b/doc/examples-transform.rst
@@ -11,6 +11,9 @@
 .. _transform-lin-log-scale.py: https://github.com/glumpy/glumpy/blob/master/examples/transform-linear-log-scale.py
 .. _transform-log-polar.py: https://github.com/glumpy/glumpy/blob/master/examples/transform-log-polar.py
 
+.. ----------------------------------------------------------------------------
+.. _section-examples-transform:
+
 ==========
 Transforms
 ==========

diff --git a/doc/examples.rst b/doc/examples.rst
@@ -7,16 +7,25 @@ features. You'll find below a list organized around several sections.
 
 **Content**
 
+  * :any:`section-examples-app`         — Window, context, events, backends, etc
+  * :any:`section-examples-gloo`        — Shader, buffer, texture, program, etc.
+  * :any:`section-examples-transform`   — Linear/power/log scales, panzoom, trackball, etc.
+  * :any:`section-examples-collection`  — Point, segment, path, triangle, custom, etc
+  * :any:`section-examples-computation` — Framebuffer, GPGPU, etc.
+  * :any:`section-examples-filter`      — Post-processing, render to texture, etc.
+  * :any:`section-examples-candy`       — Fast, scalable & beautiful
+
 .. toctree::
    :maxdepth: 2
-
+   :hidden:
+
    examples-app
    examples-gloo
-   examples-snippet
-   examples-filter
    examples-transform
    examples-collection
    examples-computation
+   examples-filter
+   examples-snippet
    examples-misc
    examples-candy
 

diff --git a/doc/faq.rst b/doc/faq.rst
@@ -33,3 +33,15 @@ Frequently Asked Questions
 
    Not yet. There are still a number of problems to be solved before something
    happens in that direction.
+
+**Why don't you use this or that feature of OpenGL x.y ?**
+
+   Glumpy tries to stick to OpenGL ES 2.0 in order to maximize the number of
+   compatible graphic cards. Some features of glumpy could be easily rewritten
+   using latest OpenGL features but this would require extra-effort to write
+   two versions of the same feature: one for old cards and one for new cards.
+
+   .. image:: _static/gl-history.png
+
+   Furthermore, giving the slow latency in OpenGL releases, it's hard to stay
+   in touch with latest features.
diff --git a/examples/fireworks.py b/examples/fireworks.py
@@ -1,7 +1,5 @@
-#! /usr/bin/env python
-# -*- coding: utf-8 -*-
 # -----------------------------------------------------------------------------
-# Copyright (c) 2014, Nicolas P. Rougier. All Rights Reserved.
+# Copyright (c) 2011-2016, Nicolas P. Rougier. All Rights Reserved.
 # Distributed under the (new) BSD License.
 # -----------------------------------------------------------------------------
 """

diff --git a/examples/galaxy.py b/examples/galaxy.py
@@ -1,7 +1,5 @@
-#! /usr/bin/env python
-# -*- coding: utf-8 -*-
 # -----------------------------------------------------------------------------
-# Copyright (c) 2014, Nicolas P. Rougier
+# Copyright (c) 2011-2016, Nicolas P. Rougier
 # Distributed under the (new) BSD License. See LICENSE.txt for more info.
 # -----------------------------------------------------------------------------
 import numpy as np

diff --git a/examples/voronoi.py b/examples/voronoi.py
@@ -1,7 +1,5 @@
-#! /usr/bin/env python
-# -*- coding: utf-8 -*-
 # -----------------------------------------------------------------------------
-# Copyright (c) 2014, Nicolas P. Rougier. All Rights Reserved.
+# Copyright (c) 2011-2016, Nicolas P. Rougier. All Rights Reserved.
 # Distributed under the (new) BSD License.
 # -----------------------------------------------------------------------------
 import numpy as np