Changeset 257

Timestamp:

05/04/07 06:27:24 (1 year ago)

Author:

aldacron

Message:

[Docs]
* added documentation for extension loading
* tweaked the style sheet a bit

Files:

• trunk/docs/gl.html (modified) (2 diffs)
• trunk/docs/styles.css (modified) (2 diffs)

trunk/docs/gl.html

@@ -66 +66 @@
-application is actually run on that system.
-</p><p>
-
-
-
-
-
-
-
-
-
-pplication is actually using, or which version a graphics card driver supports,
-until the 
+ Windows operating systems. The default opengl32.dll 
+
+
+
+
+
+
+
+
+ctually using, or which version a graphics card driver supports, until the 
+
-</p><p>
-Derelict's dynamic loading mechanism helps to work around the first issue. If not
@@ -215 +215 @@
-</div>
-
+<h3>Loading OpenGL Extensions</h3>
+
+As an added convenience, DerelictGL includes support for the easy detection and
+loading of several OpenGL extensions. In the <tt>derelict.opengl.extension</tt>
+package are several subpackages. Each subpackage contains loaders for a group
+of extensions. For example, loaders for <span class='bold'>GL_EXT</span>
+extensions are found in <tt>derelict.opengl.extension.ext</tt>, loaders for
+<span class='bold'>GL_ARB</span> extensions in <tt>derelict.opengl.extension.arb</tt>,
+loaders for <span class='bold'GL_NV extensions in</span>
+<tt>derelict.opengl.extension.nv</tt>, and so on.
+
+<h4>Naming Conventions</h4>
+It's important to understand the difference between extension 
+<span class='emph'>names</span> and <span class='emph'>name strings</span>.
+A name string is an extension name prefixed with <span class='bold'>GL_</span>
+(for core OpenGL extensions), or a platform-specific prefix (such as 
+<span class='bold'>WGL_</span> on Windows and <span class='bold'>GLX_</span> on 
+Linux) for platform-specific extensions. For example, <span class='bold'>ARB_shadow
+</span> is an extension name and <span class='bold'>GL_ARB_shadow</span> is a
+name string.
+<p>
+In DerelictGL, each supported extension has its own loader. The name of the
+loader's module is identical to the extension name, minus the prefix. The prefix
+is the name of the package in which the module can be found. For example, the
+loader for the extension <span class='bold'>ARB_shadow_objects</span> resides in 
+the module <tt>derelict.opengl.extension.arb.shadow_objects</tt></span>.
+</p>
+<div class='note'>
+The one exception to this rule is the extension 
+<span class='bold'>EXT_422_pixels</span>. In D, module names cannot begin with
+a number. For this extension, the module is
+<tt>derelict.opengl.extension.ext.four22_pixels</tt>. However, the name of the
+loader for this extension follows the convention outlined below.
+</div>
+
+<p>
+The name of each loader is a modified form of the extension name. Essentially, 
+each lowercase word separated by an underscore is capitalized and the underscores
+removed, resulting in a camel-case name. Here are some examples:
+</p>
+<ul>
+<li>ARB_shadow => ARBShadow</li>
+<li>NV_float_buffer => NVFloatBuffer</li>
+<li>EXT_bgra => EXTBgra</li>
+<li>EXT_422_pixels =>EXT422Pixels</li>
+<li>ATI_texture_compression_3dc => ATITextureCompression3dc</li>
+</ul>
+<p>
+Take special notice of EXTBgra. It's tempting to write EXTBGRA instead, but in any
+case where acronyms are part of an extension name, the name of the loader
+will only capitalize the first letter of the acronym.
+</p>
+
+<h4>Loading Extensions</h4>
+
+On some operating systems, it may be possible to load extensions without first
+creating an OpenGL context. Unfortunately, on Windows, this is not the case.
+As such, in order to maintain a consistent interface DerelictGL requires that
+a valid OpenGL context exist before extensions can be loaded. Any attempt to
+load extensions when no context has been created will cause an exception to
+be thrown.
+
+<p>
+Once DerelictGL has been loaded and a context created, you can load all extensions
+used by your application with one method call: <tt>DerelictGL.loadExtensions</tt>.
+Extensions not used by your application will not be loaded. Internally, DerelictGL
+uses module constructors to track which extensions need to be loaded. So all you
+need do is to import the extension loader modules you intend you use. There is
+no requirement that you import them in the same module in which you load them --
+you can import them anywhere in your application:
+</p>
+<pre>
+// render.d
+module myapp.render;
+
+import derelict.opengl.extension.arb.point_sprite;
+import derelict.opengl.extension.nv.texture_rectangle;
+
+...
+
+// init.d
+module myapp.init
+
+void loadOpenGL()
+{
+    // load DerelictGL
+    DerelictGL.load();
+    
+    // create the OpenGL context here (via SDL, Win32, or some other API)
+    ...
+    
+    // load all of the extensions you use (in this case ARB_point_sprite and NV_texture_rectangle)
+    DerelictGL.loadExtensions();
+}
+</pre>
+<p>
+This is a fine compromise between the two techniques often used in the C world:
+loading each extension individually, or using a third-party library that loads
+all available extensions.
+</p><p>
+The <tt>load</tt> method of each extension loader is publicly exposed, so you
+can call it directly if you prefer. It's much simpler, however, to use the
+<tt>loadExtensions</tt> method of DerelictGL instead.
+</p>
+
+<h4>Using Extensions</h4>
+
+Because all extensions used by the application are loaded at once, and because
+failure to load an extension rarely indicates that an application should terminate,
+no exceptions are thrown when an extension is not present or fails to load. It
+would have been possible to use Derelict's selective loading mechanism with
+extension loading, but the decision was made not to do so simply because it is
+not an exceptional circumstance for an extension to be unavailable on a user's
+machine. In fact, it is often expected that some extensions will not be present.
+Therefore, before attempting to use an extension it is important to check
+whether or not the extension is available.
+<p>
+Alternate code paths are the norm in OpenGL programming. Typically, developers
+determine a mimimal OpenGL version and/or extension set to support. If the minimum
+is not available on the user's machine, the application aborts. Many OpenGL
+applications also support more advanced features if they are available. For example,
+some advanced lighting technniques can be implemented with GLSL shaders, but
+when GLSL is unavailable the application can fall back to a different technique
+using the fixed-function pipeline for a degraded effect. Some applications may
+provide for three or four different ways of achieving a single effect.
+</p><p>
+With this in mind, each extension loader in Derelict exposes the following
+method: <tt>bool isEnabled()</tt>. You can call this method to determine if
+an extension is available and take appropriate action if it is not. Here is
+an example:
+</p>
+<pre>
+import derelict.extension.arb.vertex_shader;
+
+void doSomethingWithVertexShaderExtension
+{
+    if(ARBVertexShader.isEnabled())
+    {
+        // use extension here
+    }
+    else
+    {
+        // use fallback, exit program, or whatever you need to do
+    }
+}
+</pre>
+
-
-<h3>Dependencies</h3>

trunk/docs/styles.css

@@ -74 +74 @@
-}
-
+.note tt {
+    background-color: #EEEEEE;
+}
+
-.important {
-    font-weight: bold;
@@ -84 +88 @@
-    font-weight: bold;
-}
+
+.emph {
+    font-style: italic;
+}