diff options
Diffstat (limited to 'externals/glfw-3.0.2/docs/html/context.html')
| -rw-r--r-- | externals/glfw-3.0.2/docs/html/context.html | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/externals/glfw-3.0.2/docs/html/context.html b/externals/glfw-3.0.2/docs/html/context.html new file mode 100644 index 00000000..03968670 --- /dev/null +++ b/externals/glfw-3.0.2/docs/html/context.html @@ -0,0 +1,178 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.8.3.1"/> +<title>GLFW: Context handling guide</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> + $(document).ready(function() { searchBox.OnSelectItem(0); }); +</script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td style="padding-left: 0.5em;"> + <div id="projectname">GLFW +  <span id="projectnumber">3.0.2</span> + </div> + <div id="projectbrief">A multi-platform library for OpenGL, window and input</div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.3.1 --> +<script type="text/javascript"> +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +</script> + <div id="navrow1" class="tabs"> + <ul class="tablist"> + <li><a href="index.html"><span>Main Page</span></a></li> + <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> + <li><a href="modules.html"><span>Modules</span></a></li> + <li><a href="annotated.html"><span>Data Structures</span></a></li> + <li><a href="files.html"><span>Files</span></a></li> + <li> + <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.png" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> + </span> + </div> + </li> + </ul> + </div> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +</div><!-- top --> +<div class="header"> + <div class="headertitle"> +<div class="title">Context handling guide </div> </div> +</div><!--header--> +<div class="contents"> +<div class="toc"><h3>Table of Contents</h3> +<ul><li class="level1"><a href="#context_object">Context handles</a></li> +<li class="level1"><a href="#context_hints">Context creation hints</a></li> +<li class="level1"><a href="#context_current">Current context</a></li> +<li class="level1"><a href="#context_swap">Swapping buffers</a></li> +<li class="level1"><a href="#context_glext">OpenGL extension handling</a><ul><li class="level2"><a href="#context_glext_header">The glext.h header</a></li> +<li class="level2"><a href="#context_glext_string">Checking for extensions</a></li> +<li class="level2"><a href="#context_glext_proc">Fetching function pointers</a></li> +</ul> +</li> +</ul> +</div> +<div class="textblock"><p>The primary purpose of GLFW is to provide a simple interface to window management and OpenGL and OpenGL ES context creation. GLFW supports multiple windows, each of which has its own context.</p> +<h1><a class="anchor" id="context_object"></a> +Context handles</h1> +<p>The <a class="el" href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a> object encapsulates both a window and a context. They are created with <a class="el" href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a> and destroyed with <a class="el" href="group__window.html#gacdf43e51376051d2c091662e9fe3d7b2">glfwDestroyWindow</a> (or <a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>, if any remain). As the window and context are inseparably linked, the object pointer is used as both a context and window handle.</p> +<h1><a class="anchor" id="context_hints"></a> +Context creation hints</h1> +<p>There are a number of hints, specified using <a class="el" href="group__window.html#ga4fd9e504bb937e79588a0ffdca9f620b">glfwWindowHint</a>, related to what kind of context is created. See <a class="el" href="window.html#window_hints_ctx">context related hints</a> in the window handling guide.</p> +<h1><a class="anchor" id="context_current"></a> +Current context</h1> +<p>Before you can use the OpenGL or OpenGL ES APIs, you need to have a current context of the proper type. The context encapsulates all render state and all objects like textures and shaders.</p> +<p>Note that a context can only be current for a single thread at a time, and a thread can only have a single context at a time.</p> +<p>A context is made current with <a class="el" href="group__context.html#ga1c04dc242268f827290fe40aa1c91157">glfwMakeContextCurrent</a>.</p> +<div class="fragment"><div class="line"><a class="code" href="group__context.html#ga1c04dc242268f827290fe40aa1c91157" title="Makes the context of the specified window current for the calling thread.">glfwMakeContextCurrent</a>(window);</div> +</div><!-- fragment --><p>The current context is returned by <a class="el" href="group__context.html#gac84759b1f6c2d271a4fea8ae89ec980d">glfwGetCurrentContext</a>.</p> +<div class="fragment"><div class="line"><a class="code" href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window = <a class="code" href="group__context.html#gac84759b1f6c2d271a4fea8ae89ec980d" title="Returns the window whose context is current on the calling thread.">glfwGetCurrentContext</a>();</div> +</div><!-- fragment --><h1><a class="anchor" id="context_swap"></a> +Swapping buffers</h1> +<p>See <a class="el" href="window.html#window_swap">swapping buffers</a> in the window handling guide.</p> +<h1><a class="anchor" id="context_glext"></a> +OpenGL extension handling</h1> +<p>One of the benefits of OpenGL is its extensibility. Independent hardware vendors (IHVs) may include functionality in their OpenGL implementations that expand upon the OpenGL standard before that functionality is included in a new version of the OpenGL specification.</p> +<p>An extension is defined by:</p> +<ul> +<li>An extension name (e.g. <code>GL_ARB_debug_output</code>)</li> +<li>New OpenGL tokens (e.g. <code>GL_DEBUG_SEVERITY_HIGH_ARB</code>)</li> +<li>New OpenGL functions (e.g. <code>glGetDebugMessageLogARB</code>)</li> +</ul> +<p>Note the <code>ARB</code> affix, which stands for Architecture Review Board and is used for official extensions. There are many different affixes, depending on who wrote the extension. A list of extensions, together with their specifications, can be found at the <a href="http://www.opengl.org/registry/">OpenGL Registry</a>.</p> +<p>To use a certain extension, you must first check whether the context supports that extension and then, if it introduces new functions, retrieve the pointers to those functions.</p> +<p>This can be done with GLFW, as will be described in this section, but usually you will instead want to use a dedicated extension loading library such as <a href="http://glew.sourceforge.net/">GLEW</a>. This kind of library greatly reduces the amount of work necessary to use both OpenGL extensions and modern versions of the OpenGL API. GLEW in particular has been extensively tested with and works well with GLFW.</p> +<h2><a class="anchor" id="context_glext_header"></a> +The glext.h header</h2> +<p>The <code>glext.h</code> header is a continually updated file that defines the interfaces for all OpenGL extensions. The latest version of this can always be found at the <a href="http://www.opengl.org/registry/">OpenGL Registry</a>. It it strongly recommended that you use your own copy, as the one shipped with your development environment may be several years out of date and may not include the extensions you wish to use.</p> +<p>The header defines function pointer types for all functions of all extensions it supports. These have names like <code>PFNGLGETDEBUGMESSAGELOGARB</code> (for <code>glGetDebugMessageLogARB</code>), i.e. the name is made uppercase and <code>PFN</code> and <code>PROC</code> are added to the ends.</p> +<h2><a class="anchor" id="context_glext_string"></a> +Checking for extensions</h2> +<p>A given machine may not actually support the extension (it may have older drivers or a graphics card that lacks the necessary hardware features), so it is necessary to check whether the context supports the extension. This is done with <a class="el" href="group__context.html#ga87425065c011cef1ebd6aac75e059dfa">glfwExtensionSupported</a>.</p> +<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__context.html#ga87425065c011cef1ebd6aac75e059dfa" title="Returns whether the specified extension is available.">glfwExtensionSupported</a>(<span class="stringliteral">"GL_ARB_debug_output"</span>))</div> +<div class="line">{</div> +<div class="line"> <span class="comment">// The extension is supported by the current context</span></div> +<div class="line">}</div> +</div><!-- fragment --><p>The argument is a null terminated ASCII string with the extension name. If the extension is supported, <a class="el" href="group__context.html#ga87425065c011cef1ebd6aac75e059dfa">glfwExtensionSupported</a> returns non-zero, otherwise it returns zero.</p> +<h2><a class="anchor" id="context_glext_proc"></a> +Fetching function pointers</h2> +<p>Many extensions, though not all, require the use of new OpenGL functions. These entry points are often not exposed by your link libraries, making it necessary to fetch them at run time. With <a class="el" href="group__context.html#ga35f1837e6f666781842483937612f163">glfwGetProcAddress</a> you can retrieve the address of extension and non-extension OpenGL functions.</p> +<div class="fragment"><div class="line">PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog = <a class="code" href="group__context.html#ga35f1837e6f666781842483937612f163" title="Returns the address of the specified function for the current context.">glfwGetProcAddress</a>(<span class="stringliteral">"glGetDebugMessageLogARB"</span>);</div> +</div><!-- fragment --><p>In general, you should avoid giving the function pointer variables the (exact) same name as the function, as this may confuse your linker. Instead, you can use a different prefix, like above, or some other naming scheme.</p> +<p>Now that all the pieces have been introduced, here is what they might look like when used together.</p> +<div class="fragment"><div class="line"><span class="preprocessor">#include "glext.h"</span></div> +<div class="line"></div> +<div class="line"><span class="preprocessor">#define glGetDebugMessageLogARB pfnGetDebugMessageLog</span></div> +<div class="line"><span class="preprocessor"></span>PFNGLGETDEBUGMESSAGELOGARB pfnGetDebugMessageLog;</div> +<div class="line"></div> +<div class="line"><span class="comment">// Flag indicating whether the extension is supported</span></div> +<div class="line"><span class="keywordtype">int</span> has_debug_output = 0;</div> +<div class="line"></div> +<div class="line"><span class="keywordtype">void</span> load_extensions(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__context.html#ga87425065c011cef1ebd6aac75e059dfa" title="Returns whether the specified extension is available.">glfwExtensionSupported</a>(<span class="stringliteral">"GL_ARB_debug_output"</span>))</div> +<div class="line"> {</div> +<div class="line"> pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARB) <a class="code" href="group__context.html#ga35f1837e6f666781842483937612f163" title="Returns the address of the specified function for the current context.">glfwGetProcAddress</a>(<span class="stringliteral">"glGetDebugMessageLogARB"</span>);</div> +<div class="line"> <span class="keywordflow">if</span> (pfnGetDebugMessageLog)</div> +<div class="line"> {</div> +<div class="line"> <span class="comment">// Both the extension name and the function pointer are present</span></div> +<div class="line"> has_debug_output = 1;</div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line">}</div> +<div class="line"></div> +<div class="line"><span class="keywordtype">void</span> some_function(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <span class="comment">// Now the extension function can be called as usual</span></div> +<div class="line"> glGetDebugMessageLogARB(...);</div> +<div class="line">}</div> +</div><!-- fragment --> </div></div><!-- contents --> +<!-- start footer part --> +<hr class="footer"/><address class="footer"><small> +Generated on Sun Aug 25 2013 21:45:13 for GLFW by  <a href="http://www.doxygen.org/index.html"> +<img class="footer" src="doxygen.png" alt="doxygen"/> +</a> 1.8.3.1 +</small></address> +</body> +</html> |