Jason McKesson avatar Jason McKesson committed 2cb7dda

Copyediting.

Comments (0)

Files changed (3)

Documents/Illumination/Tutorial 13.xml

             that the user provided with <function>glDepthRange.</function></para>
         <para>We write the final depth to a built-in output variable
                 <varname>gl_FragDepth.</varname></para>
-        <section>
-            <section>
-                <sidebar>
-                    <title>Fragments and Depth</title>
-                    <para>The default behavior of OpenGL is, if a fragment shader does not write to
-                        the output depth, then simply take the <varname>gl_FragCoord.z</varname>
-                        depth as the depth of the fragment. Oh, you could do this manually. One
-                        could add the following statement to any fragment shader that uses the
-                        default depth value:</para>
-                    <programlisting language="glsl">gl_FragDepth = gl_FragCoord.z</programlisting>
-                    <para>This is, in terms of behavior a noop; it does nothing OpenGL would not have
-                        done itself. However, in terms of <emphasis>performance</emphasis>, this is
-                        a drastic change.</para>
-                    <para>The reason fragment shaders are not required to have this line in all of
-                        them is to allow for certain optimizations. If the OpenGL driver can see
-                        that you do not set <varname>gl_FragDepth</varname> anywhere in the fragment
-                        shader, then it can dramatically improve performance in certain
-                        cases.</para>
-                    <para>If the driver knows that the output fragment depth is the same as the
-                        generated one, it can do the whole depth test <emphasis>before</emphasis>
-                        executing the fragment shader. This is called <glossterm>early depth
-                            test</glossterm> or <glossterm>early-z</glossterm>. This means that it
-                        can discard fragments <emphasis>before</emphasis> wasting precious time
-                        executing potentially complex fragment shaders. Indeed, most hardware
-                        nowadays has complicated early z culling hardware that can discard multiple
-                        fragments with a single test.</para>
-                    <para>The moment your fragment shader writes anything to
-                            <varname>gl_FragDepth</varname>, all of those optimizations have to go
-                        away. So generally, you should only write a depth value yourself if you
-                            <emphasis>really</emphasis> need to do it.</para>
-                    <para>Also, if your shader writes <varname>gl_FragDepth</varname> anywhere, it
-                        must ensure that it is <emphasis>always</emphasis> written to, no matter
-                        what conditional branches your shader uses. The value is not initialized to
-                        a default; you either always write to it or never mention
-                                <quote><varname>gl_FragDepth</varname></quote> in your fragment
-                        shader at all. Obviously, you do not always have to write the same value; you
-                        can conditionally write different values. But you cannot write something in
-                        one path and not write something in another. Initialize it explicitly with
-                            <varname>gl_FragCoord.z</varname> if you want to do something like
-                        that.</para>
-                </sidebar>
-            </section>
-        </section>
+        <sidebar>
+            <title>Fragments and Depth</title>
+            <para>The default behavior of OpenGL is, if a fragment shader does not write to the
+                output depth, then simply take the <varname>gl_FragCoord.z</varname> depth as the
+                depth of the fragment. Oh, you could do this manually. One could add the following
+                statement to any fragment shader that uses the default depth value:</para>
+            <programlisting language="glsl">gl_FragDepth = gl_FragCoord.z</programlisting>
+            <para>This is, in terms of behavior a noop; it does nothing OpenGL would not have done
+                itself. However, in terms of <emphasis>performance</emphasis>, this is a drastic
+                change.</para>
+            <para>The reason fragment shaders are not required to have this line in all of them is
+                to allow for certain optimizations. If the OpenGL driver can see that you do not set
+                    <varname>gl_FragDepth</varname> anywhere in the fragment shader, then it can
+                dramatically improve performance in certain cases.</para>
+            <para>If the driver knows that the output fragment depth is the same as the generated
+                one, it can do the whole depth test <emphasis>before</emphasis> executing the
+                fragment shader. This is called <glossterm>early depth test</glossterm> or
+                    <glossterm>early-z</glossterm>. This means that it can discard fragments
+                    <emphasis>before</emphasis> wasting precious time executing potentially complex
+                fragment shaders. Indeed, most hardware nowadays has complicated early z culling
+                hardware that can discard multiple fragments with a single test.</para>
+            <para>The moment your fragment shader writes anything to
+                <varname>gl_FragDepth</varname>, all of those optimizations have to go away. So
+                generally, you should only write a depth value yourself if you
+                    <emphasis>really</emphasis> need to do it.</para>
+            <para>Also, if your shader writes <varname>gl_FragDepth</varname> anywhere, it must
+                ensure that it is <emphasis>always</emphasis> written to, no matter what conditional
+                branches your shader uses. The value is not initialized to a default; you either
+                always write to it or never mention <quote><varname>gl_FragDepth</varname></quote>
+                in your fragment shader at all. Obviously, you do not always have to write the same
+                value; you can conditionally write different values. But you cannot write something
+                in one path and not write something in another. Initialize it explicitly with
+                    <varname>gl_FragCoord.z</varname> if you want to do something like that.</para>
+        </sidebar>
     </section>
     <section>
         <?dbhtml filename="Tut13 Purloined Primitives.html" ?>
             <funcsynopsis>
                 <funcprototype>
                     <funcdef>void <function>EmitVertex</function></funcdef>
+                    <paramdef/>
                 </funcprototype>
             </funcsynopsis>
             <para>Available on in the geometry shader, when this function is called, all output

Documents/Texturing/Tutorial 14.xml

                 there is a corresponding sampler type. So a texture that is of type
                     <literal>GL_TEXTURE_1D</literal> is paired with a sampler of type
                     <type>sampler1D</type>.</para>
-            <para>The GLSL sampler type is very unusual. You can use vectors of all kinds as inputs,
-                outputs, function parameters, etc. You can use matrices and even arrays as outputs
-                or inputs. But not samplers. The restrictions on samplers are:</para>
+            <para>The GLSL sampler type is very unusual. Indeed, it is probably best if you do not
+                think of it like a normal basic type. Think of it instead as a specific hook into
+                the shader that the user can use to supply a texture. The restrictions on sampler
+                types are:</para>
             <itemizedlist>
                 <listitem>
-                    <para>Samplers can only declared as <literal>uniform</literal> in function
-                        parameters with the <literal>in</literal> qualifier. They cannot even be
-                        declared as local variables.</para>
+                    <para>Samplers can only declared at the global scope as
+                            <literal>uniform</literal> or in function parameter lists with the
+                            <literal>in</literal> qualifier. They cannot even be declared as local
+                        variables.</para>
                 </listitem>
                 <listitem>
                     <para>Samplers cannot be members of structs or uniform blocks.</para>
                         variables.</para>
                 </listitem>
                 <listitem>
-                    <para>Variables of sampler type can only be used as parameters to functions.
+                    <para>The only use of variables of sampler type is as parameters to functions.
                         User-defined functions can take them as parameters, and there are a number
                         of built-in functions that take samplers.</para>
                 </listitem>
             <para>In the shader <filename>TextureGaussian.frag</filename>, we have an example of
                 creating a sampler:</para>
             <programlisting language="glsl">uniform sampler1D gaussianTexture;</programlisting>
-            <para>This sampler is used in our lighting computation function:</para>
+            <para>This creates a sampler for a 1D texture type; the user cannot use any other type
+                of texture with this sampler. This sampler is used in our lighting computation
+                function:</para>
             <example>
                 <title>Shader Texture Access</title>
                 <programlisting language="glsl">vec3 halfAngle = normalize(lightDir + viewDirection);

Documents/Texturing/Tutorial 15.xml

                 to see where one mipmap ends and another begins.</para>
             <para>OpenGL actually allows all combinations of <literal>NEAREST</literal> and
                     <literal>LINEAR</literal> in minification filtering. Using nearest filtering
-                within levels while filtering between levels
+                within a mipmap level while linearly filtering between levels
                     (<literal>GL_NEAREST_MIPMAP_LINEAR</literal>) is not terribly useful
                 however.</para>
             <sidebar>
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.