Commits

Jason McKesson committed b2f7291

Improved a couple of documentation sections.

Comments (0)

Files changed (4)

Documents/Building the Tutorials.xml

         <title>Unofficial OpenGL SDK</title>
         <para>Distributed with the tutorials is the Unofficial OpenGL SDK. This is an aggregation of
             libraries, unifying a number of tools for developing OpenGL applications, all bound
-            together with a unified build system. You do not need to download it; a modified SDK
-            distribution is bundled with these tutorials. The copy that comes with these tutorials
+            together with a unified build system. You do not need to download it; a modified version
+            of the SDK is bundled with these tutorials. The copy that comes with these tutorials
             does not contain the documentation or GLFW.</para>
         <para>The SDK library uses Premake to generate its build files. So, with
                 <command>premake4.exe</command> in your path, go to the <filename>glsdk</filename>

Documents/Further Study.xml

 <?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
 <appendix xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+    <?dbhtml filename="Further Study.html" ?>
     <title>Further Study</title>
     <para>G</para>
     <section>
+        <?dbhtml filename="Further Study Debugging.html" ?>
+        <title>Debugging</title>
+        <para>This book provides functioning code to solve various problems and implement a variety
+            of effects. However, it does not talk about how to get code from a non-working state
+            into a working one. That is, debugging.</para>
+        <para>Debugging OpenGL code is very difficult. Frequently when there is an OpenGL bug, the
+            result is a massively unhelpful blank screen. If the problem is localized to a single
+            shader or state used to render an object, the result is a black object. Compounding this
+            problem is the fact that OpenGL has a lot of global state. One of the reasons this book
+            will often bind objects, do something with them, and then unbind them, is to reduce the
+            amount of state dependencies. It ensures that every object is rendered with a specific
+            program, a set of textures, a certain VAO, etc. It may be slightly slower to do this,
+            but for a simple application, getting it working is more important.</para>
+        <para>Debugging shaders is even more problematic; there are no breakpoints or watches you
+            can put on GLSL shaders. Fragment shaders offer the possibility of
+                <function>printf</function>-style debugging: one can always write some values to the
+            framebuffer and see something. Vertex or other shader stages require passing their data
+            through another stage before the outcome can be seen. And even then, it is an
+            interpolated version.</para>
+        <para>Because of the difficulty in debugging, the general tactics for doing so revolve
+            around bug prevention rather than bug finding. Therefore, the most important tactic for
+            debugging is this: always start with working code. Begin development with something that
+            actually functions, even if it is not drawing what you ultimately intend for it to. Once
+            you have working code, you can change it to render what you need it to.</para>
+        <para>The second tip is to minimize the amount of code/data that could be causing any
+            problem you encounter. This means making small changes in a working application and
+            immediately testing to see if they work or not. If they do not, then it must be because
+            of those small changes. If you make big changes, then the size of the code/data you have
+            to look through is much larger. The more code you have to debug, the harder it is to do
+            so effectively.</para>
+        <para>Along with the last tip is to use a distributed version control system and check in
+            your code often, preferably after each small change. This will allow you to revert any
+            changes that do not work, as well as see the actual differences between the last working
+            version and the now non-functional version. This will save you from inadvertent
+            keystrokes and the like.</para>
+        <para>The next step is to avail yourself of debugging tools, where they exist for your
+            platform(s) of interest. OpenGL itself can help here. The OpenGL specification defines
+            what functions should do in the case of malformed input. Specifically, they will place
+            errors into the OpenGL error queue. After every OpenGL function call, you may want to
+            check to see if an error has been added to the queue. This is done with code as
+            follows:</para>
+        <programlisting language="cpp">for(GLenum currError = glGetError(); currError != GL_NO_ERROR; currError = glGetError())
+{
+  //Do something with `currError`.
+}</programlisting>
+        <para>It would be very tedious to put this after every function. But since the errors are
+            all stored in a queue, they are not associated with the actual function that caused the
+            error. If <function>glGetError</function> is not called frequently, it becomes very
+            difficult to know where any particular error came from. Therefore, there is a special
+            OpenGL extension specifically for aiding in debugging: ARB_debug_output. This extension
+            is only available when creating an OpenGL context with a special debug flag. The
+            framework used here automatically uses this extension in debug builds.</para>
+        <para>The debug output extension allows the user to register a function that will be called
+            whenever errors happen. It can also be called when less erroneous circumstances occur;
+            this depends on the OpenGL implementation. When set up for synchronous error messages,
+            the callback will be called before the function that created the error returned. So it
+            is possible to breakpoint inside the callback function and see exactly which function
+            caused it.</para>
+        <para>Setting up the callback is somewhat complex. The Unofficial OpenGL SDK offers, as part
+            of its GL Utilities sub-library, a registration function for setting up the debug output
+            properly. Also, the framework for this book's code offers similar functionality. It is
+            located in <filename>framework/framework.cpp</filename>.</para>
+        <para>There are alternatives for catching OpenGL errors. The utility glIntercept (it works
+            in Linux and Windows, but the Linux port is slightly iffy) is capable of hooking into
+            OpenGL without any code modifications and tracking every OpenGL function call. It can
+            dump every OpenGL call to a file, as well as the given parameters. This is very useful
+            for debugging, as it tells you more about what may have caused certain error or visual
+            glitches. It also automatically checks for errors after every function call, alleviating
+            the need to do so manually. Any errors are logged with the function that produced
+            them.</para>
+        <para>The gDebugger tool, Windows only, offers similar features, though unlike glIntercept,
+            it is not open-source.</para>
+    </section>
+    <section>
+        <?dbhtml filename="Further Study Topics.html" ?>
         <title>Topics of Interest</title>
         <para>This book should provide a firm foundation for understanding graphics development. But
             there are many subjects that are not covered in this book which are also important in

Documents/Getting Started.xml

             <formalpara>
                 <title>GLFW</title>
                 <para>GLFW is an alternative to FreeGLUT. Like FreeGLUT, GLFW is fairly bare-bones.
-                    It provides a way to create windows or full-screen displays. It provides ways to
-                    get keyboard and mouse input.</para>
+                    It provides a way to create windows or full-screen displays.</para>
             </formalpara>
             <para>The biggest difference between them is that, while FreeGLUT owns the message
                 processing loop, GLFW does not. GLFW requires that the user poll it to process
                 While this makes GLFW programs a bit more complicated than FreeGLUT ones (which is
                 why these tutorials use FreeGLUT), it does mean that GLFW would be more useful in
                 serious applications.</para>
-            <para>GLFW also provides more robust input support as well as </para>
-            <para>GLFW uses the zLib license.</para>
+            <para>Additionally, GLFW offers more robust support in a number of areas. Both FreeGLUT
+                and GLFW can create full-screen applications, but GLFW provides a means to query the
+                available resolutions. They both offer time querying, but GLFW offers much higher
+                resolution timers, while FreeGLUT timers only have millisecond resolution. They both
+                offer support for joystick input, but GLFW allows the ability to query basic
+                information about the joysticks (number of buttons and axes), as well as supporting
+                an arbitrary number of buttons and axes.</para>
+            <para>Overall, it is a more game-centric API than FreeGLUT. One thing that is
+                (currently) missing from GLFW is the ability to create an sRGB default framebuffer.
+                GLFW uses the zLib license.</para>
             <formalpara>
                 <title>Multimedia Libraries</title>
                 <para>A multimedia library is a library that handles, in a cross-platform way,
                 <para>There are a number of cross-platform GUI libraries that deal with detailed
                     window management, provide controls, and generally act like a full-fledged
                     windowing system. Most of them have support for using OpenGL in one or more of
-                    their windows.</para>
+                    their windows. Qt, wxWidgets, GTK, all have some form of OpenGL window that you
+                    can use.</para>
             </formalpara>
             <para>Which window creation tools you use are entirely up to you; the possible needs
                 that you might have are well beyond the scope of this book.</para>
                 do it for you.</para>
             <formalpara>
                 <title>GL Load</title>
-                <para>This comes with the Unofficial OpenGL SDK. And while most of the SDK is not
-                    intended for high-performance use, GL Load is still perfectly serviceable in
-                    that capacity. After all, this is generally a one-time initialization step, so
+                <para>This comes with the Unofficial OpenGL SDK. While most of the SDK is not
+                    intended for high-performance use, GL Load is still perfectly functional in that
+                    capacity. After all, this is generally a one-time initialization step, so
                     performance is ultimately irrelevant.</para>
             </formalpara>
-            <para>GL Load works with core and compatibility contexts equally well. GL Load uses the
-                MIT License.</para>
+            <para>GL Load works with core and compatibility contexts equally well. Indeed, unlike
+                most OpenGL loading libraries, it separates not just core and compatibility headers,
+                but it also separates headers by OpenGL version. So if you work in OpenGL 3.3, you
+                won't see functions or enumerators from later versions (except when they are exposed
+                as OpenGL extensions).</para>
+            <para>GL Load uses the MIT License.</para>
             <formalpara>
                 <title>GLEW</title>
-                <para>GLEW (the OpenGL Extension Wrangler) is perhaps the most widely used
-                    alternative. While it is technically intended for loading extension functions,
-                    it works just as well on the OpenGL core functions.</para>
+                <para>GLEW (the OpenGL Extension Wrangler) is perhaps the most widely used OpenGL
+                    loading library. While it is technically intended for loading extension
+                    functions, it works just as well on the OpenGL core functions.</para>
             </formalpara>
-            <para>The principle downside of GLEW is that it does not work well with
-                non-compatibility contexts. There is some experimental support to make this work,
-                but it is experimental. GLEW uses the MIT license.</para>
+            <para>The principle downside of GLEW is that it does not work well with core contexts.
+                There is some experimental support to make this work, but it is experimental. GLEW
+                uses the MIT license.</para>
             <formalpara>
                 <title>GL3W</title>
                 <para>GL3W is unique in that it is not technically a library. It is a Python script
             </formalpara>
             <para>GL3W is intended specifically for core contexts, and it does not work with
                 compatibility or older OpenGL versions. Being a Python script, it requires a Python
-                2.6 environment; it is unknown if it works with later Python versions. GL3W is
-                public domain software.</para>
+                environment. Specifically it requires Python 2.6; it is unknown if it works with
+                later Python versions. GL3W is public domain software.</para>
         </section>
         <section>
             <title>Initialization</title>

Documents/preface.xml

     <section>
         <?dbhtml filename="About Need.html" ?>
         <title>What You Need</title>
-        <para>This is a book for beginning graphics programmers; it can also serve as a book for
-            those familiar with fixed functionality who want to understand programmable rendering
-            better. But this is not a book for beginning programmers.</para>
+        <para>This is a book for beginning graphics programmers; it can also serve as a good
+            introductory text for those familiar with fixed function-based graphics who want to
+            understand programmable rendering better.</para>
+        <para>What this book is not is a book for beginning <emphasis>programmers</emphasis>.</para>
         <para>You are expected to be able to read C and reasonable C++ code. If <quote>Hello,
                 world!</quote> is the extent of your C/C++ knowledge, then perhaps you should write
             some more substantial code before proceeding with trying to render images. 3D graphics
             tutorials.</para>
         <para>Any substantial discussion of 3D rendering requires a discussion of mathematics, which
             are at the foundation of all 3D graphics. This book expects you to know basic geometry
-            and algebra.</para>
-        <para>The tutorials will present the more advanced math needed for graphics as it becomes
-            necessary, but you should have at least a working knowledge of geometry and algebra.
-            Linear algebra is not required, though it would be helpful.</para>
-        <para>The code tutorials in this book use OpenGL as their rendering API. You do not need to
-            know OpenGL, but to execute the code, you must have a programming environment that
-            allows OpenGL. Specifically, you will need hardware capable of running OpenGL version
-            3.3. This means any GeForce 8xxx or better, or any Radeon HD-class card. These are also
+            and algebra. This book will present the more advanced math needed for graphics as it
+            becomes necessary. But you should have at least a working knowledge of geometry and
+            algebra. Linear algebra is not required.</para>
+        <para>The source code in this book use OpenGL as its rendering API. You do not need to know
+            OpenGL when starting, but in order to compile and run any of this code, you must have a
+            development environment that allows OpenGL.</para>
+        <para>Specifically, you will need graphics hardware capable of running OpenGL version 3.3.
+            This means any GeForce 8xxx or better, or any Radeon HD-class card. These are also
             called <quote>Direct3D 10</quote> cards, but you do not need Windows Vista or 7 to use
-            their advanced features through OpenGL.</para>
+            their advanced features through OpenGL. You should have the most recent version of
+            graphics drivers installed, available on the home page of your graphics card
+            manufacturer. Outside of drivers and the actual tutorial distribution, you will not need
+            to download or install anything else to work with OpenGL.</para>
+        <section>
+            <title>Be Open</title>
+            <para>This book is intended to teach graphics programmers the basics of graphics
+                development. The most important thing you can bring within yourself is a willingness
+                to learn. This also means leaving preconceived notions, and most importantly of all,
+                not trying to learn anything in particular.</para>
+            <para>Often, programmers will scour the internet or pour over books, looking for
+                information about how to perform some specific task. Once they find it, they will
+                try to copy that code into their application and see if they can make it work. This
+                method can achieve results faster, but it impairs learning by focusing on achieving
+                a certain effect goal instead of truly understanding how it works.</para>
+            <para>When first approaching this book, you should try to avoid thinking about any
+                specific problem. You may keep a particular problem in the back of your mind, but do
+                not allow the search for a solution to drive your reading. Instead, focus on the
+                material being presented. Once you have finished the book, then you can look back
+                and see if you understand how to solve that problem you wanted to solve.</para>
+            <para>You may find that you have a better solution than you would have thought of
+                otherwise.</para>
+        </section>
     </section>
     <section>
         <?dbhtml filename="About Organization.html" ?>
             code itself; these are intended to further your understanding of these concepts. If the
             tutorial introduced new OpenGL functions or functions for the OpenGL shading language,
             they will be reviewed here as well.</para>
-        <para>This is a book for beginning graphics programmers. Graphics is a huge topic, and this
-            book will not cover every possible effect, feature, or technique. This book will also
-            not cover every technique in full detail. Sometimes techniques will be revisited in
-            later materials, but there simply isn't enough space to say everything about everything.
+        <para>This is a book for beginning graphics programmers. Graphics is a huge topic, and no
+            book could cover every possible effect, feature, or technique. This book will also not
+            cover every technique in full detail. Sometimes techniques will be revisited in later
+            materials, but there simply isn't enough space to say everything about everything.
             Therefore, when certain techniques are introduced, there will be a section at the end
             providing some cursory examination of more advanced techniques. This will help you
             further your own research into graphics programming, as you will know what to search for