Jason McKesson avatar Jason McKesson committed 83059c7

Copyediting. Also added a build tool.

Comments (0)

Files changed (7)

Documents/Build/BuildSingleDotGraph.lua

+
+local filename = ...;
+
+local outname = filename:match("(.+)%.dotgraph$") .. ".svg";
+
+local cmd = {};
+cmd[#cmd + 1] = "dot.exe";
+cmd[#cmd + 1] = [[-Tsvg]];
+--cmd[#cmd + 1] = [[-Kneato]];
+cmd[#cmd + 1] = [["-o]] .. outname .. [["]];
+cmd[#cmd + 1] = [["]] .. filename .. [["]];
+
+print(table.concat(cmd, " "));
+os.execute(table.concat(cmd, " "));

Documents/Positioning/Tutorial 05.xml

             have to worry about those pesky zeros. Unfortunately, because homogeneous spaces are not
             easy to draw, we can't show you what it would look like. But we can show you what it
             would look like if you clipped in camera space, in 2D:</para>
-        <!--TODO: Create images of clipping, one that creates a single triangle, and one that creates more than one-->
         <figure>
             <title>Triangle Clipping</title>
             <mediaobject>
                 clipped.</para>
         </note>
     </section>
+    <!--
         <section>
             <?dbhtml filename="Tut05 Depth Precision.html" ?>
             <title>Depth Precision</title>
                 If the camera or these objects are in motion, horrible flickering artifacts can be
                 seen. This is called <glossterm>z-fighting,</glossterm> as multiple objects appear
                 to be fighting each other when animated.</para>
-            <!--TODO: Show an image of z-fighting.-->
             <para>Fortunately, the days of 16-bit depth buffers are long over; the modern standard
                 is (and has been for years now) 24-bits of precision. Half-precision of 24-bits is
                 12-bits, which is not too far from a 16-bit depth buffer in and of itself. If you
                     into both, just to make sure their depth values show up properly.</para>
             </section>
         </section>
+        -->
     <section>
-    <?dbhtml filename="Tut05 In Review.html" ?>
+        <?dbhtml filename="Tut05 In Review.html" ?>
         <title>In Review</title>
         <para>In this tutorial, you have learned about the following:</para>
         <itemizedlist>

Documents/Positioning/Tutorial 06.xml

             <title>Coordinate System</title>
             <mediaobject>
                 <imageobject>
-                    <imagedata fileref="FullCoordinateEquation.svg"/>
+                    <imagedata fileref="FullCoordinateEquation.svg" format="SVG"/>
                 </imageobject>
             </mediaobject>
         </equation>
 {
     std::vector&lt;GLuint> shaderList;
     
-    shaderList.push_back(Framework::LoadShader(GL_VERTEX_SHADER, "PosColorLocalTransform.vert"));
-    shaderList.push_back(Framework::LoadShader(GL_FRAGMENT_SHADER, "ColorPassthrough.frag"));
+    shaderList.push_back(Framework::LoadShader(GL_VERTEX_SHADER,
+        "PosColorLocalTransform.vert"));
+    shaderList.push_back(Framework::LoadShader(GL_FRAGMENT_SHADER,
+        "ColorPassthrough.frag"));
     
     theProgram = Framework::CreateProgram(shaderList);
     
     positionAttrib = glGetAttribLocation(theProgram, "position");
     colorAttrib = glGetAttribLocation(theProgram, "color");
     
-    modelToCameraMatrixUnif = glGetUniformLocation(theProgram, "modelToCameraMatrix");
-    cameraToClipMatrixUnif = glGetUniformLocation(theProgram, "cameraToClipMatrix");
+    modelToCameraMatrixUnif = glGetUniformLocation(theProgram,
+        "modelToCameraMatrix");
+    cameraToClipMatrixUnif = glGetUniformLocation(theProgram,
+        "cameraToClipMatrix");
     
     float fzNear = 1.0f; float fzFar = 45.0f;
     
     cameraToClipMatrix[3].z = (2 * fzFar * fzNear) / (fzNear - fzFar);
     
     glUseProgram(theProgram);
-    glUniformMatrix4fv(cameraToClipMatrixUnif, 1, GL_FALSE, glm::value_ptr(cameraToClipMatrix));
+    glUniformMatrix4fv(cameraToClipMatrixUnif, 1, GL_FALSE,
+        glm::value_ptr(cameraToClipMatrix));
     glUseProgram(0);
 }</programlisting>
         </example>
             corner, which is set to 1. As with the rest of GLM, this works in GLSL as well.</para>
     </section>
     <section>
-        <?dbhtml filename="Tut06 Successive Transformations.html" ?>
-        <title>Successive Transformations</title>
+        <?dbhtml filename="Tut06 Fun with Matrices.html" ?>
+        <title>Fun with Matrices</title>
         <para>In all of the previous examples except for the translation one, we always combined the
             transformation with a translation operation. So the scale transform was not a pure scale
             transform; it was a scale and translate transformation matrix. The translation was there
         modelToCameraStack.Push();
         modelToCameraStack.Translate(posBaseLeft);
         modelToCameraStack.Scale(glm::vec3(1.0f, 1.0f, scaleBaseZ));
-        glUniformMatrix4fv(modelToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(modelToCameraStack.Top()));
-        glDrawElements(GL_TRIANGLES, ARRAY_COUNT(indexData), GL_UNSIGNED_SHORT, 0);
+        glUniformMatrix4fv(modelToCameraMatrixUnif, 1, GL_FALSE,
+            glm::value_ptr(modelToCameraStack.Top()));
+        glDrawElements(GL_TRIANGLES, ARRAY_COUNT(indexData),
+            GL_UNSIGNED_SHORT, 0);
         modelToCameraStack.Pop();
     }
     
         modelToCameraStack.Push();
         modelToCameraStack.Translate(posBaseRight);
         modelToCameraStack.Scale(glm::vec3(1.0f, 1.0f, scaleBaseZ));
-        glUniformMatrix4fv(modelToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(modelToCameraStack.Top()));
-        glDrawElements(GL_TRIANGLES, ARRAY_COUNT(indexData), GL_UNSIGNED_SHORT, 0);
+        glUniformMatrix4fv(modelToCameraMatrixUnif, 1, GL_FALSE,
+            glm::value_ptr(modelToCameraStack.Top()));
+        glDrawElements(GL_TRIANGLES, ARRAY_COUNT(indexData),
+            GL_UNSIGNED_SHORT, 0);
         modelToCameraStack.Pop();
     }
     

Documents/Positioning/Tutorial 07.xml

         <para>Speaking of the transformation pipeline, here is a diagram of the full transform for
             vertex positions, from the initial attribute loaded from the buffer object, to the final
             window-space position.</para>
-        <!--TODO: An Image of the full vertex transformation sequence, from attribute to window-space.-->
         <figure>
             <title>Full Vertex Transformation Pipeline</title>
             <mediaobject>
         </figure>
         <para>The controls for this tutorial are as follows:</para>
         <!--TODO: Add the table of key controls.-->
+        <table frame="all">
+            <title>World Space Controls</title>
+            <tgroup cols="3">
+                <colspec colname="c1" colnum="1" colwidth="1.0*"/>
+                <colspec colname="c2" colnum="2" colwidth="1.0*"/>
+                <colspec colname="c3" colnum="3" colwidth="1.0*"/>
+                <thead>
+                    <row>
+                        <entry>Function</entry>
+                        <entry>Increase/Left</entry>
+                        <entry>Decrease/Right</entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry>Move camera target up/down</entry>
+                        <entry><keycap>e</keycap></entry>
+                        <entry><keycap>q</keycap></entry>
+                    </row>
+                    <row>
+                        <entry>Move camera target horizontally</entry>
+                        <entry><keycap>a</keycap></entry>
+                        <entry><keycap>d</keycap></entry>
+                    </row>
+                    <row>
+                        <entry>Move camera target vertically</entry>
+                        <entry><keycap>w</keycap></entry>
+                        <entry><keycap>s</keycap></entry>
+                    </row>
+                    <row>
+                        <entry>Rotate camera horizontally around target</entry>
+                        <entry><keycap>l</keycap></entry>
+                        <entry><keycap>j</keycap></entry>
+                    </row>
+                    <row>
+                        <entry>Rotate camera vertically around target</entry>
+                        <entry><keycap>i</keycap></entry>
+                        <entry><keycap>k</keycap></entry>
+                    </row>
+                    <row>
+                        <entry>Move camera towards/away from target</entry>
+                        <entry><keycap>u</keycap></entry>
+                        <entry><keycap>o</keycap></entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </table>
         <para>In addition, if you hold down the shift key while pressing any of these keys, then the
-            affected control will be much slower. This allows for more precision movements.</para>
+            affected control will be much slower. This allows for more precision movements. The
+            spacebar will toggle the appearance of an object indicating the position of the camera
+            point.</para>
         <para>This world is more complicated than anything we've seen up until now. There are a lot
             of objects being rendered, and most of them are composed out of multiple objects.</para>
         <para>This tutorial is the first to incorporate a number of the tutorial framework's
                 <programlisting>const glm::vec3 &amp;camPos = ResolveCamPosition();
 
 Framework::MatrixStack camMatrix;
-camMatrix.SetMatrix(CalcLookAtMatrix(camPos, g_camTarget, glm::vec3(0.0f, 1.0f, 0.0f)));
+camMatrix.SetMatrix(CalcLookAtMatrix(camPos, g_camTarget,
+    glm::vec3(0.0f, 1.0f, 0.0f)));
 
 glUseProgram(UniformColor.theProgram);
-glUniformMatrix4fv(UniformColor.worldToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
+glUniformMatrix4fv(UniformColor.worldToCameraMatrixUnif,
+    1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
 glUseProgram(ObjectColor.theProgram);
-glUniformMatrix4fv(ObjectColor.worldToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
+glUniformMatrix4fv(ObjectColor.worldToCameraMatrixUnif,
+    1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
 glUseProgram(UniformColorTint.theProgram);
-glUniformMatrix4fv(UniformColorTint.worldToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
+glUniformMatrix4fv(UniformColorTint.worldToCameraMatrixUnif,
+    1, GL_FALSE, glm::value_ptr(camMatrix.Top()));
 glUseProgram(0);</programlisting>
             </example>
             <para>The function <function>ResolveCamPosition</function> computes the camera position,
                 plane. This value is on the range [0, 180], where 0 means straight up and 180 means
                 straight down.</para>
             <para>This is much easier to see in diagram form:</para>
-            <!--TODO: A diagram of spherical coordinates.-->
             <figure>
                 <title>Spherical Coordinates</title>
                 <mediaobject>
                     <imageobject>
-                        <imagedata fileref="Coord_system_SZ_0.svg"/>
+                        <imagedata fileref="Coord_system_SZ_0.svg" format="SVG"/>
                     </imageobject>
                 </mediaobject>
             </figure>
 modelMatrix.Scale(glm::vec3(100.0f, 1.0f, 100.0f));
 
 glUseProgram(UniformColor.theProgram);
-glUniformMatrix4fv(UniformColor.modelToWorldMatrixUnif, 1, GL_FALSE, glm::value_ptr(modelMatrix.Top()));
+glUniformMatrix4fv(UniformColor.modelToWorldMatrixUnif, 1, GL_FALSE,
+    glm::value_ptr(modelMatrix.Top()));
 glUniform4f(UniformColor.baseColorUnif, 0.302f, 0.416f, 0.0589f, 1.0f);
 g_pPlaneMesh->Render();
 glUseProgram(0);</programlisting>
 modelMatrix.Scale(1.0f, 1.0f, 1.0f);
 
 glUseProgram(ObjectColor.theProgram);
-glUniformMatrix4fv(ObjectColor.modelToWorldMatrixUnif, 1, GL_FALSE, glm::value_ptr(modelMatrix.Top()));
-glUniformMatrix4fv(ObjectColor.worldToCameraMatrixUnif, 1, GL_FALSE, glm::value_ptr(idenity));
+glUniformMatrix4fv(ObjectColor.modelToWorldMatrixUnif, 1, GL_FALSE,
+    glm::value_ptr(modelMatrix.Top()));
+glUniformMatrix4fv(ObjectColor.worldToCameraMatrixUnif, 1, GL_FALSE,
+    glm::value_ptr(idenity));
 g_pCubeColorMesh->Render();
 glUseProgram(0);
 glEnable(GL_DEPTH_TEST);</programlisting>
                 all, they don't have storage within a program object; their data comes from a buffer
                 object.</para>
             <para>So instead of calling glGetUniformLocation, we have a new function.</para>
-            <programlisting>data.globalUniformBlockIndex = glGetUniformBlockIndex(data.theProgram, "GlobalMatrices");</programlisting>
+            <programlisting>data.globalUniformBlockIndex =
+    glGetUniformBlockIndex(data.theProgram, "GlobalMatrices");</programlisting>
             <para>The function <function>glGetUniformBlockIndex</function> takes a program object
                 and the name of a uniform block. It returns a <glossterm>uniform block
                     index</glossterm> that is used to refer to this uniform block. This is similar
 modelMatrix.Scale(1.0f, 1.0f, 1.0f);
 
 glUseProgram(ObjectColor.theProgram);
-glUniformMatrix4fv(ObjectColor.modelToWorldMatrixUnif, 1, GL_FALSE, glm::value_ptr(modelMatrix.Top()));
+glUniformMatrix4fv(ObjectColor.modelToWorldMatrixUnif, 1,
+    GL_FALSE, glm::value_ptr(modelMatrix.Top()));
 g_pCubeColorMesh->Render();
 glUseProgram(0);
 glEnable(GL_DEPTH_TEST);</programlisting>
         <para>Let us also say that, while you do have a large world, you are not concerned about
             rendering <emphasis>all</emphasis> of it at any one time. The part of the world you're
             interested in is the part within view from the camera. And you're not interested in
-            viewing incredibly distance objects; the far depth plane is going to cull out the world
+            viewing incredibly distant objects; the far depth plane is going to cull out the world
             beyond a certain point from the camera.</para>
         <para>The problem is that a 32-bit floating-point number can only hold about 7 digits of
             precision. So towards the edges of the world, at around 63,000,000 inches, you only have
             quite a bit of precision available in <varname>cameraPos</varname>.</para>
         <para>And in <varname>gl_Position</varname>, everything is in clip-space, which is again
             relative to the camera. While you can have depth buffer precision problems, that only
-            happens at far distances from the camera. Again, since everything is relative to the
+            happens at far distances from the near plane. Again, since everything is relative to the
             camera, there is no precision problem.</para>
         <para>The only precision problem is with <varname>worldPos</varname>. Or rather, in the
                 <varname>modelToWorldMatrix</varname>.</para>
             vector/matrix multiplies per vertex; you're doing them per <emphasis>object</emphasis>.
             And since the final result would actually fit within 32-bit precision limitations, the
             solution is obvious.</para>
-        <para>Never have an explicit model-to-world matrix. Instead, generate a matrix that goes
-            straight from model space to <emphasis>camera</emphasis> space. You can use
-            double-precision computations to do this if you need to; simply transform them back to
-            single-precision when uploading the matrices to OpenGL.</para>
+        <para>The take-home point is this: avoid presenting OpenGL with an explicit model-to-world
+            matrix. Instead, generate a matrix that goes straight from model space to
+                <emphasis>camera</emphasis> space. You can use double-precision computations to do
+            this if you need to; simply transform them back to single-precision when uploading the
+            matrices to OpenGL.</para>
     </section>
     <section>
         <?dbhtml filename="Tut07 In Review.html" ?>
                 <glossterm>Euclidean geometry</glossterm>
                 <glossdef>
                     <para>A specific kind of coordinate system that follows certain axioms. For the
-                        sake or brevity, consider it a <quote>regular</quote> coordinate system, one
+                        sake of brevity, consider it a <quote>regular</quote> coordinate system, one
                         that follows the simple, obvious rules one might expect of a 2D sheet of
                         paper.</para>
                 </glossdef>

Documents/Tutorials.xml

 <?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
 <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
     <info>
-        <title>OpenGL Tutorials</title>
+        <title>Learning Modern 3D Graphics Programming Through OpenGL</title>
     </info>
     <preface>
         <?dbhtml filename="About these Tutorials.html" ?>

Documents/chunked.css

 code.literal { color: #0f0aae; }
 
 span.type {  }
+code.classname {  }
 
 em.glossterm { text-decoration: underline; }
 
 acronym.acronym { font-weight: bold; }
+span.propername { font-weight: bold; }
 
 
 /* Code documentation. */

Documents/cssDoc.txt

     code.classname: Used for classes.
     span.type: Used for the types of things.
     span.mathphrase: Used for math phrases.
+    span.propername: Used for the names of the various tutorials.
     
     div.example: Stores the entire example.
         p.title: The title of the example.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.