DOC: context for GLLineVertices

fsleyes/assets/gl/gl21/gllinevector_vert.glsl

@@ -12,7 +12,7 @@
 uniform sampler3D vectorTexture;
 
 /*
- * Transformations between voxel and 
+ * Transformations between voxel and
  * display coordinate systems.
  */
 uniform mat4 displayToVoxMat;
@@ -44,7 +44,7 @@ uniform vec3 imageShape;
 uniform vec3 imageDims;
 
 /*
- * If true, the vectors are 
+ * If true, the vectors are
  * inverted about the x axis.
  */
 uniform bool xFlip;
@@ -57,7 +57,7 @@ uniform bool xFlip;
 uniform bool directed;
 
 /*
- * If true, each vector is scaled to have a length 
+ * If true, each vector is scaled to have a length
  * of 1*lengthScale in the image coordinate system.
  */
 uniform bool unitLength;
@@ -88,7 +88,7 @@ varying vec4 fragColourFactor;
 
 void main(void) {
 
-  
+
   vec3  texCoord;
   vec3  vector;
   vec3  voxCoord;
@@ -122,11 +122,11 @@ void main(void) {
   if (xFlip)
     vector.x = -vector.x;
 
-  /* 
-   * Kill the vector if its length is 0. 
-   * We have to be tolerant of errors, 
+  /*
+   * Kill the vector if its length is 0.
+   * We have to be tolerant of errors,
    * because of the transformation to/
-   * from the texture data range. This 
+   * from the texture data range. This
    * may end up being too tolerant.
    */
   if (vectorLen < 0.0001) {
@@ -134,17 +134,16 @@ void main(void) {
     return;
   }
 
-
   if (unitLength) {
 
     /*
-     * Scale the vector so it has length 0.5. 
+     * Scale the vector so it has length 0.5.
      */
     vector /= 2 * vectorLen;
 
     /*
      * Scale the vector by the minimum voxel length,
-     * so it is a unit vector within real world space 
+     * so it is a unit vector within real world space
      */
     vector /= imageDims / min(imageDims.x, min(imageDims.y, imageDims.z));
   }

fsleyes/gl/gllinevector.py

@@ -7,10 +7,8 @@
 """This module provides the :class:`GLLineVector` class, for displaying 3D
 vector :class:`.Image` overlays in line mode.
 
-
 The :class:`.GLLineVertices` class is also defined in this module, and is used
-in certain rendering situations - specifically, when running in OpenGL
-1.4. See the :mod:`.gl14.gllinevector_funcs` and
+when running in OpenGL 1.4. See the :mod:`.gl14.gllinevector_funcs` and
 :mod:`.gl21.gllinevector_funcs` modules for more details.
 """
 
@@ -160,10 +158,17 @@ class GLLineVector(glvector.GLVector):
 
 
 class GLLineVertices(object):
-    """The ``GLLineVertices`` class is used in some cases when rendering a
-    :class:`GLLineVector`. It contains logic to generate vertices for every
-    vector in the vector :class:`.Image` that is being displayed by a
-    ``GLLineVector`` instance.
+    """The ``GLLineVertices`` class is used when rendering a
+    :class:`GLLineVector` with OpenGL 1.4. It contains logic to generate
+    vertices for every vector in the vector :class:`.Image` that is being
+    displayed by a ``GLLineVector`` instance.
+
+
+    This class is used by the OpenGL 1.4 implementation - when using OpenGL
+    2.1, the logic encoded in this class is implemented in the line vector
+    vertex shader. This is because OpenGL 1.4 vertex programs (using the
+    ARB_vertex_program extension) are unable to perform texture lookups,
+    so cannot retrieve the vector data.
 
 
     After a ``GLLineVertices`` instance has been created, the :meth:`refresh`