From 136e5c08fc47c7d1c2e66fec41b96a5c31f2b139 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Thu, 19 Sep 2013 18:40:49 +0200
Subject: [PATCH] Mentioned version-aware extension queries in portability
 documentation.

---
 doc/portability.dox         | 26 +++++++++++++++++++++-----
 src/AbstractShaderProgram.h |  2 ++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/doc/portability.dox b/doc/portability.dox
index b8dc2971c..d2b2870d7 100644
--- a/doc/portability.dox
+++ b/doc/portability.dox
@@ -37,7 +37,7 @@ make porting easier -- it is better to fail at compile time on e.g. undefined
 enum value than fail at runtime in some corner case because given texture
 format is not supported.
 
-If you include Magnum.h, you get these predefined macros:
+If you include @ref Magnum.h, you get these predefined macros:
 
 - @ref MAGNUM_TARGET_GLES if targeting OpenGL ES
 - @ref MAGNUM_TARGET_GLES2 if targeting OpenGL ES 2.0
@@ -109,7 +109,7 @@ available, but also have proper fallback when it's not, see for example
 @ref AbstractTexture-performance-optimization "AbstractTexture" or
 @ref Mesh-performance-optimization "Mesh". See also @ref required-extensions.
 
-@section portability-shaders Portable shaders
+@section portability-shaders Writing portable shaders
 
 %Shaders are probably the most painful thing to port. There are many issues to
 address - different shader syntax (`in`/`out` vs. `attribute` and `varying`
@@ -121,6 +121,11 @@ you can decide on the syntax in your shader code. You can also use
 @ref Context::supportedVersion() to conveniently select highest supported
 version from a list:
 @code
+// MyShader.cpp
+Version version = Context::instance()->supportedVersion({Version::GL430, Version::GL330, Version::GL210});
+attachShader(Shader::fromFile(version, "MyShader.vert"));
+@endcode
+@code
 // MyShader.vert
 #if __VERSION__ < 130
 #define in attribute
@@ -136,12 +141,23 @@ void main() {
     // ...
 }
 @endcode
+
+It is often desirable to query extension presence based on actually used GLSL
+version -- while the extension might be supported in the driver, it might not
+be available in given GLSL version (e.g. causing compilation errors). You can
+use @ref Context::isExtensionSupported(Version) to check that the extension
+is present in given version:
 @code
-// MyShader.cpp
-Version version = Context::instance()->supportedVersion({Version::GL430, Version::GL330, Version::GL210});
-attachShader(Shader::fromFile(version, "MyShader.vert"));
+if(!Context::instance()->isExtensionSupported<Extensions::GL::ARB::explicit_attrib_location>(version)) {
+    bindAttributeLocation(Position::Location, "position");
+    // ...
+}
 @endcode
 
+See also @ref AbstractShaderProgram class documentation for information about
+specifying attribute location, uniform location and texture layer in various
+OpenGL versions.
+
 All shaders in @ref Shaders namespace support desktop OpenGL starting from
 version 2.1 and also OpenGL ES 2.0 and 3.0. Feel free to look into their
 sources to see how portability is handled there.
diff --git a/src/AbstractShaderProgram.h b/src/AbstractShaderProgram.h
index 3515e7787..4caf92be4 100644
--- a/src/AbstractShaderProgram.h
+++ b/src/AbstractShaderProgram.h
@@ -283,6 +283,8 @@ setUniform() documentation for more information.
 To achieve least state changes, set all uniforms in one run -- method chaining
 comes in handy.
 
+@see @ref portability-shaders
+
 @todo Compiling and linking more than one shader in parallel, then checking
     status, should be faster -- https://twitter.com/g_truc/status/352778836657700866
  */