15bd8deadSopenharmony_ci<html> 25bd8deadSopenharmony_ci 35bd8deadSopenharmony_ci<head> 45bd8deadSopenharmony_ci<title>How to Create Khronos API Extensions</title> 55bd8deadSopenharmony_ci</head> 65bd8deadSopenharmony_ci 75bd8deadSopenharmony_ci<body> 85bd8deadSopenharmony_ci<h1>How to Create Khronos API Extensions</h1> 95bd8deadSopenharmony_ci 105bd8deadSopenharmony_ci<p> This document outlines the steps to create, define, and use 115bd8deadSopenharmony_ci an extension for some of the APIs supported by Khronos. It 125bd8deadSopenharmony_ci is currently focused on OpenGL, OpenGL ES, GLX, and EGL. 135bd8deadSopenharmony_ci Some discussion of OpenVG and WGL is also included. 145bd8deadSopenharmony_ci 155bd8deadSopenharmony_ci<ul> 165bd8deadSopenharmony_ci <li><a href="#spec">Specifying</a> an extension prior to coding it. 175bd8deadSopenharmony_ci <li><a href="#implementation">Implementing</a> an extension (this 185bd8deadSopenharmony_ci discusses only aspects of the implemention visible to users - 195bd8deadSopenharmony_ci primarily determining if the extension is available and 205bd8deadSopenharmony_ci defining its interface in header files. 215bd8deadSopenharmony_ci <li><a href="#using">Using</a> an extension in an application (this 225bd8deadSopenharmony_ci discusses the mechanics of using an extension if and only if 235bd8deadSopenharmony_ci it's supported by an implementation). 245bd8deadSopenharmony_ci</ul> 255bd8deadSopenharmony_ci 265bd8deadSopenharmony_ci<p><hr> 275bd8deadSopenharmony_ci 285bd8deadSopenharmony_ci<a name="spec"></a> 295bd8deadSopenharmony_ci<h2>Specification</h2> 305bd8deadSopenharmony_ci 315bd8deadSopenharmony_ci<p> When initially creating an extension, take the following steps: 325bd8deadSopenharmony_ci 335bd8deadSopenharmony_ci<ul> 345bd8deadSopenharmony_ci <li><a href="#spec_existing">Determine if an existing extension</a> 355bd8deadSopenharmony_ci can be used, instead of writing a new one. This may involve 365bd8deadSopenharmony_ci reuse of an existing specification, or 375bd8deadSopenharmony_ci <a href="promoting.html">promotion</a> to multivendor or 385bd8deadSopenharmony_ci Khronos-approved status. In either case, coordinate this use 395bd8deadSopenharmony_ci with the vendor(s) defining and shipping the existing extension. 405bd8deadSopenharmony_ci <li>If no suitable extension already exists, determine if you can 415bd8deadSopenharmony_ci <a href="#spec_category">agree on a multivendor or Khronos 425bd8deadSopenharmony_ci extension</a>, or if the extension must be specific to a single 435bd8deadSopenharmony_ci vendor. 445bd8deadSopenharmony_ci <li>Develop and <a href="#spec_writing">write an extension 455bd8deadSopenharmony_ci specification</a>, following the <a href="#spec_naming">naming 465bd8deadSopenharmony_ci conventions</a>. 475bd8deadSopenharmony_ci <li>When you're ready to release the extension, freeze the 485bd8deadSopenharmony_ci specification and <a href="#spec_registry">add it to the 495bd8deadSopenharmony_ci registry</a> maintained by Khronos. At this time (but not 505bd8deadSopenharmony_ci before), you can obtain permanent token (enumerant) assignments. 515bd8deadSopenharmony_ci <li>When shipping an extension, make sure that its interfaces are 525bd8deadSopenharmony_ci defined in header files accessible to ISVs. If the extension is 535bd8deadSopenharmony_ci Khronos-approved, use the Khronos-provided headers. 545bd8deadSopenharmony_ci</ul> 555bd8deadSopenharmony_ci 565bd8deadSopenharmony_ci<a name="spec_existing"></a> 575bd8deadSopenharmony_ci<h3>Is there already an extension that does what I want?</h3> 585bd8deadSopenharmony_ci 595bd8deadSopenharmony_ci<p> Specifications for extensions that have already been developed can 605bd8deadSopenharmony_cibe obtained from the <a href="http://opengl.org/registry/"> Extension 615bd8deadSopenharmony_ciRegistry</a> maintained by Khronos. Since we are just getting started 625bd8deadSopenharmony_ciwith most of the Khronos APIs, the registry currently contains only 635bd8deadSopenharmony_ciOpenGL, GLX, and WGL extension specifications. 645bd8deadSopenharmony_ci 655bd8deadSopenharmony_ci<p> It's possible that additional extensions may have been submitted to 665bd8deadSopenharmony_cithe registry but not yet updated on the website, or that another 675bd8deadSopenharmony_cilicensee may be working on a similar extension but not yet have released 685bd8deadSopenharmony_cithe specification. So it's worth asking on the appropriate Working 695bd8deadSopenharmony_ciGroup mailing list if anyone has defined related functionality already. 705bd8deadSopenharmony_ci 715bd8deadSopenharmony_ci<a name="spec_category"></a> 725bd8deadSopenharmony_ci<h3>Should the extension be Khronos-approved, multivendor, or specific 735bd8deadSopenharmony_ci to a single vendor?</h3> 745bd8deadSopenharmony_ci 755bd8deadSopenharmony_ci<p> OpenGL's history has made clear that ISVs do <b>not</b> want to deal 765bd8deadSopenharmony_ci with vendor-specific extensions if they can possibly avoid it. So if 775bd8deadSopenharmony_ci the functionality being exposed is going to be available on multiple 785bd8deadSopenharmony_ci platforms - as most will - it's a good idea to agree on a single 795bd8deadSopenharmony_ci extension with other vendors providing that functionality. This 805bd8deadSopenharmony_ci makes it easier for ISVs to justify using extensions. 815bd8deadSopenharmony_ci 825bd8deadSopenharmony_ci<p> If the functionality is well-understood, it may be appropriate to 835bd8deadSopenharmony_ci define a <b>Khronos-approved extension</b>. This is the most 845bd8deadSopenharmony_ci "blessed" category of extension; it goes through the 855bd8deadSopenharmony_ci entire standards process, and is approved by the group, but remains 865bd8deadSopenharmony_ci optional functionality. Many core features have been promoted 875bd8deadSopenharmony_ci directly from existing Khronos-approved extensions. 885bd8deadSopenharmony_ci 895bd8deadSopenharmony_ci<p> If Khronos as a whole isn't ready to deal with the extension, but 905bd8deadSopenharmony_ci other vendors are, then it should be defined as a <b>multivendor 915bd8deadSopenharmony_ci extension</b>. The interested parties can develop the specification 925bd8deadSopenharmony_ci entirely among themselves, outside the standards process; or they 935bd8deadSopenharmony_ci may be able to use Khronos Working Groups as a forum to develop the 945bd8deadSopenharmony_ci specification. 955bd8deadSopenharmony_ci 965bd8deadSopenharmony_ci<p> In some cases, vendors may share a common core of functionality, 975bd8deadSopenharmony_ci with vendor-specific additional features. Here, it may make sense to 985bd8deadSopenharmony_ci agree on a multivendor extension to access the core, with additional 995bd8deadSopenharmony_ci vendor-specific extensions layered on the core exposing unique 1005bd8deadSopenharmony_ci features. 1015bd8deadSopenharmony_ci 1025bd8deadSopenharmony_ci<p> Finally, some extensions will probably have to remain proprietary. 1035bd8deadSopenharmony_ci 1045bd8deadSopenharmony_ci<a name="spec_writing"></a> 1055bd8deadSopenharmony_ci<h3>How do I write a specification?</h3> 1065bd8deadSopenharmony_ci 1075bd8deadSopenharmony_ci<p> Start with the <a href="template.txt">template</a> for writing 1085bd8deadSopenharmony_ci extension specifications. There are different templates for 1095bd8deadSopenharmony_ci different APIs, but general comments apply: 1105bd8deadSopenharmony_ci 1115bd8deadSopenharmony_ci<ul> 1125bd8deadSopenharmony_ci<li> It's important to think about all the different areas of the core 1135bd8deadSopenharmony_ci language specification(s) that are affected. How are queries for 1145bd8deadSopenharmony_ci state handled? What attribute group does new state belong in? How 1155bd8deadSopenharmony_ci are existing calls modified or expanded in scope? How are existing 1165bd8deadSopenharmony_ci objects affected by use of the extension? The template helps with 1175bd8deadSopenharmony_ci this by at least reminding you to consider each part of the core 1185bd8deadSopenharmony_ci language specification. 1195bd8deadSopenharmony_ci<li> Extension specifications must be written against a specific version 1205bd8deadSopenharmony_ci of the core API specification. If possible, it's highly preferable 1215bd8deadSopenharmony_ci to write against the most recent public version. "Written 1225bd8deadSopenharmony_ci against" means that new language must be written as 1235bd8deadSopenharmony_ci well-defined modifications to the Specification being referenced. It 1245bd8deadSopenharmony_ci should be possible for someone not involved with the development of 1255bd8deadSopenharmony_ci an extension to sit down with a copy of the Specification and the 1265bd8deadSopenharmony_ci extension and produce a merged document identical to that you 1275bd8deadSopenharmony_ci intended. 1285bd8deadSopenharmony_ci<li> Extension specifications may also be specified as Docbook XML 1295bd8deadSopenharmony_ci documents, although we're still using plain text for the most part. 1305bd8deadSopenharmony_ci Docbook is a very powerful structural representation of documents, 1315bd8deadSopenharmony_ci but we're still feeling our way into using it. Known <a 1325bd8deadSopenharmony_ci href="toolchain.html">Docbook tools and editors</a> are described 1335bd8deadSopenharmony_ci elsewhere. 1345bd8deadSopenharmony_ci</ul> 1355bd8deadSopenharmony_ci 1365bd8deadSopenharmony_ci<p> One complete, shipping example to refer to is the 1375bd8deadSopenharmony_ci <a href="../specs/EXT/fog_coord.txt">Fog Coordinate</a> OpenGL extension 1385bd8deadSopenharmony_ci specification. 1395bd8deadSopenharmony_ci<!-- (<a href="fog_coord.xml">Docbook source</a>). --> 1405bd8deadSopenharmony_ci 1415bd8deadSopenharmony_ci<a name="spec_naming"></a> 1425bd8deadSopenharmony_ci<h3>Naming Conventions</h3> 1435bd8deadSopenharmony_ci 1445bd8deadSopenharmony_ci<p> API entry points and enumerants in an extension must be named 1455bd8deadSopenharmony_ciaccording to the <a href="syntaxrules.txt">syntax rules</a> specific to 1465bd8deadSopenharmony_cithat API. In particular, follow the sections "Extension name 1475bd8deadSopenharmony_cirules" and "Shared extensions". 1485bd8deadSopenharmony_ci 1495bd8deadSopenharmony_ci<p> All extensions must be named and the name included in the extension 1505bd8deadSopenharmony_cispecification. The extension name is of the form 1515bd8deadSopenharmony_ci<tt>"api_category_name"</tt> where 1525bd8deadSopenharmony_ci 1535bd8deadSopenharmony_ci<ul> 1545bd8deadSopenharmony_ci<li> <tt>"api"</tt> identifies the API 1555bd8deadSopenharmony_ci (<tt>"GL"</tt> for OpenGL and OpenGL ES; 1565bd8deadSopenharmony_ci <tt>"EGL"</tt>, <tt>"GLX"</tt>, and 1575bd8deadSopenharmony_ci <tt>"WGL"</tt> for the corresponding window-system 1585bd8deadSopenharmony_ci abstraction APIs EGL, GLX, and WGL; <tt>"GLU"</tt> for the 1595bd8deadSopenharmony_ci OpenGL Utility Library; and <tt>"OVG"</tt> for OpenVG. 1605bd8deadSopenharmony_ci 1615bd8deadSopenharmony_ci (<b>Note</b>: OpenMAX, OpenSL, OpenML TBD). 1625bd8deadSopenharmony_ci 1635bd8deadSopenharmony_ci<li> <tt>"category"</tt> identifies the extension category. 1645bd8deadSopenharmony_ci For a vendor-specific extension, the category is a 2-3 letter string 1655bd8deadSopenharmony_ci identifying the vendor: <tt>"NV"</tt> for NVIDIA, 1665bd8deadSopenharmony_ci <tt>"ATI"</tt> for ATI, etc. For a multivendor extensions, 1675bd8deadSopenharmony_ci the category is <tt>"EXT"</tt>. For Khronos-approved 1685bd8deadSopenharmony_ci extensions, one of several API-specific categories is used 1695bd8deadSopenharmony_ci (<tt>"ARB"</tt> for OpenGL extensions, 1705bd8deadSopenharmony_ci <tt>"OES"</tt> for OpenGL ES extensions, 1715bd8deadSopenharmony_ci <tt>"OML"</tt> for OpenML extensions, and so on). 1725bd8deadSopenharmony_ci 1735bd8deadSopenharmony_ci<li> <tt>"name"</tt> is one or more words separated by 1745bd8deadSopenharmony_ci underscores, providing a short label for the extension. 1755bd8deadSopenharmony_ci Conventionally the name is entirely lower-case. 1765bd8deadSopenharmony_ci</ul> 1775bd8deadSopenharmony_ci 1785bd8deadSopenharmony_ci<p> For example, the extension name 1795bd8deadSopenharmony_ci <tt>"GL_EXT_framebuffer_object"</tt> is used for a 1805bd8deadSopenharmony_ci multivendor OpenGL extension adding support for framebuffer objects. 1815bd8deadSopenharmony_ci 1825bd8deadSopenharmony_ci<p> Choose names that are 1835bd8deadSopenharmony_ci 1845bd8deadSopenharmony_ci<ul> 1855bd8deadSopenharmony_ci<li> Short. 1865bd8deadSopenharmony_ci<li> Meaningful. 1875bd8deadSopenharmony_ci<li> Not prefixes of any existing extension name (disregarding the 1885bd8deadSopenharmony_ci category). For example, <tt>"GL_ARB_fog"</tt> is a prefix 1895bd8deadSopenharmony_ci of <tt>"GL_EXT_fog_coord"</tt>, so should not be chosen. 1905bd8deadSopenharmony_ci<li> Not prefixed by any existing extension name (again, disregarding 1915bd8deadSopenharmony_ci the category). 1925bd8deadSopenharmony_ci</ul> 1935bd8deadSopenharmony_ci 1945bd8deadSopenharmony_ci<p> The goal is for names to be clear, but not at the cost of confusion 1955bd8deadSopenharmony_ci or ambiguity. 1965bd8deadSopenharmony_ci 1975bd8deadSopenharmony_ci 1985bd8deadSopenharmony_ci<h4> Advertising Extension Names to Applications </h4> 1995bd8deadSopenharmony_ci 2005bd8deadSopenharmony_ci<p> Each Khronos API provides a way of describing the supported 2015bd8deadSopenharmony_ci extensions at compile- and run-time. This is done by a combination 2025bd8deadSopenharmony_ci of preprocessor tokens in header files, and queryable extension 2035bd8deadSopenharmony_ci strings. 2045bd8deadSopenharmony_ci 2055bd8deadSopenharmony_ci<p> <b>OpenGL and OpenGL ES</b> #define a preprocessor token 2065bd8deadSopenharmony_ci corresponding to the extension name in <tt><GL/gl.h></tt> (or 2075bd8deadSopenharmony_ci an include file that <tt>gl.h</tt> includes, such as the 2085bd8deadSopenharmony_ci <tt>glext.h</tt> header provided in the registry). When this token 2095bd8deadSopenharmony_ci is defined, it indicates that the function prototypes and enumerant 2105bd8deadSopenharmony_ci definitions required to use the extension are available at compile 2115bd8deadSopenharmony_ci time. 2125bd8deadSopenharmony_ci 2135bd8deadSopenharmony_ci<p> If an OpenGL or OpenGL ES extension is supported at runtime, the 2145bd8deadSopenharmony_ci extension name must also be included in the string returned by 2155bd8deadSopenharmony_ci <tt>glGetString(GL_EXTENSIONS)</tt>. 2165bd8deadSopenharmony_ci 2175bd8deadSopenharmony_ci<p> <b>GLX</b> #defines a preprocessor token corresponding to the 2185bd8deadSopenharmony_ci extension name in <tt><GL/glx.h></tt> (or an include file that 2195bd8deadSopenharmony_ci <tt>glx.h</tt> includes, such as the <tt>glxext.h</tt> header 2205bd8deadSopenharmony_ci provided in the registry). When this token is defined, it indicates 2215bd8deadSopenharmony_ci that the function prototypes and enumerant definitions required to 2225bd8deadSopenharmony_ci use the extension are available at compile time. 2235bd8deadSopenharmony_ci 2245bd8deadSopenharmony_ci<p> If a GLX extension is supported at runtime, the extension name must 2255bd8deadSopenharmony_ci also be included in the strings returned by 2265bd8deadSopenharmony_ci <b>glXQueryExtensionsString</b>, <b>glXGetClientString</b>, and/or 2275bd8deadSopenharmony_ci <b>glXQueryServerString</b> (see below for a description of the 2285bd8deadSopenharmony_ci different routines). 2295bd8deadSopenharmony_ci 2305bd8deadSopenharmony_ci<p> <b>WGL</b> #defines a preprocessor token corresponding to the 2315bd8deadSopenharmony_ci extension name in the <tt>wglext.h</tt> header provided in the 2325bd8deadSopenharmony_ci registry (the wgl.h supplied with Microsoft Windows does not 2335bd8deadSopenharmony_ci #include <tt>wglext.h</tt>, or define any extensions itself). When 2345bd8deadSopenharmony_ci this token is defined, it indicates that the function prototypes and 2355bd8deadSopenharmony_ci enumerant definitions required to use the extension are available at 2365bd8deadSopenharmony_ci compile time. 2375bd8deadSopenharmony_ci 2385bd8deadSopenharmony_ci<p> If a WGL extension is supported at runtime, the extension name must 2395bd8deadSopenharmony_ci also be included in the string returned by 2405bd8deadSopenharmony_ci <b>wglGetExtensionsStringEXT</b>. 2415bd8deadSopenharmony_ci 2425bd8deadSopenharmony_ci<p> <b>OpenVG</b> extension conventions are <i>To Be Determined</i>. 2435bd8deadSopenharmony_ci 2445bd8deadSopenharmony_ci<p> Note that extensions can have both OpenGL components and windowing 2455bd8deadSopenharmony_ci system components. For example, the ARB multisampling extension 2465bd8deadSopenharmony_ci modifies both GLX and OpenGL. In this case there will be two tokens 2475bd8deadSopenharmony_ci associated with the extension (e.g., <tt>GL_ARB_multisample</tt> and 2485bd8deadSopenharmony_ci <tt>GLX_ARB_multisample</tt>) and the extension will be advertised 2495bd8deadSopenharmony_ci by both OpenGL and GLX. 2505bd8deadSopenharmony_ci 2515bd8deadSopenharmony_ci<a name="spec_registry"></a> 2525bd8deadSopenharmony_ci<h3>Extension Registry</h3> 2535bd8deadSopenharmony_ci 2545bd8deadSopenharmony_ci<p> Khronos keeps a registry of extension specifications, enumerated 2555bd8deadSopenharmony_ci type values, GLX codes (vendor private opcodes, vendor private with 2565bd8deadSopenharmony_ci reply opcodes, new visual attribute type values, GLX error codes and 2575bd8deadSopenharmony_ci GLX event codes), OpenGL rendering codes for GLX, and OpenGL 2585bd8deadSopenharmony_ci rendering codes for GLS and extension numbers. Vendors shipping 2595bd8deadSopenharmony_ci extensions using any of these values must obtain them from Khronos. 2605bd8deadSopenharmony_ci 2615bd8deadSopenharmony_ci<p> If an extension defines new OpenGL enumerant names, values for those 2625bd8deadSopenharmony_ci names must be requested in one or more blocks of 16 values. If an 2635bd8deadSopenharmony_ci extension defines new OpenGL rendering commands then you need to 2645bd8deadSopenharmony_ci register GLS rendering codes for it. If you want the extensions to 2655bd8deadSopenharmony_ci work with the X windowing system (i.e., with GLX), then you must 2665bd8deadSopenharmony_ci request GLX opcodes and define GLX protocol for it. 2675bd8deadSopenharmony_ci 2685bd8deadSopenharmony_ci<p> There are detailed <a href="enums.html">enumerant allocation 2695bd8deadSopenharmony_ci policies</a> for OpenGL, GLX, and WGL enumerants. 2705bd8deadSopenharmony_ci 2715bd8deadSopenharmony_ci<p> All new extensions must have a number associated with them for 2725bd8deadSopenharmony_ci documentation purposes. If an extension depends on another 2735bd8deadSopenharmony_ci extension, the other extension must have a lower number. (Note that 2745bd8deadSopenharmony_ci when an extension is deprecated, the number associated with it is 2755bd8deadSopenharmony_ci not reassigned.) This number will also be assigned by Khronos when 2765bd8deadSopenharmony_ci you register the extension. 2775bd8deadSopenharmony_ci 2785bd8deadSopenharmony_ci<p> Include all new enumerated values, GLX codes, and the extension 2795bd8deadSopenharmony_ci number in the specification. 2805bd8deadSopenharmony_ci 2815bd8deadSopenharmony_ci<p> Once you have completed the extension, please make it available to 2825bd8deadSopenharmony_ci other Khronos members and application developers, by submitting the 2835bd8deadSopenharmony_ci extension specification to the Khronos Registrar for inclusion in 2845bd8deadSopenharmony_ci the public registry. 2855bd8deadSopenharmony_ci 2865bd8deadSopenharmony_ci<p><hr> 2875bd8deadSopenharmony_ci 2885bd8deadSopenharmony_ci<a name="implementation"></a> 2895bd8deadSopenharmony_ci<h2>Implementing and Advertising Extensions</h2> 2905bd8deadSopenharmony_ci 2915bd8deadSopenharmony_ci<h4><u>Errors</u></h4> 2925bd8deadSopenharmony_ci 2935bd8deadSopenharmony_ci<p> Whenever possible, extensions should use existing errors instead of 2945bd8deadSopenharmony_ci defining new error returns. For GLX, if a new protocol error is 2955bd8deadSopenharmony_ci introduced, then an error number must be obtained from and 2965bd8deadSopenharmony_ci registered with Khronos. 2975bd8deadSopenharmony_ci 2985bd8deadSopenharmony_ci<p> Vendors may ship a single OpenGL library, containing extensions, for 2995bd8deadSopenharmony_ci a variety of platforms. It is possible that some of the extension 3005bd8deadSopenharmony_ci routines defined in the library may not be supported on some of the 3015bd8deadSopenharmony_ci platforms. If this is the case and an application calls a routine 3025bd8deadSopenharmony_ci that is not supported by the current OpenGL renderer then a 3035bd8deadSopenharmony_ci <tt>GL_INVALID_OPERATION</tt> error should be returned. 3045bd8deadSopenharmony_ci 3055bd8deadSopenharmony_ci<h4><u>OpenGL Extension Availability</u></h4> 3065bd8deadSopenharmony_ci 3075bd8deadSopenharmony_ci<p> OpenGL extensions must be advertised in the extension string 3085bd8deadSopenharmony_ci returned by <b>glGetString</b>. Note that in a client-server 3095bd8deadSopenharmony_ci environment, this call returns the set of extensions that can be 3105bd8deadSopenharmony_ci supported on the connection. GLX client libraries must send a 3115bd8deadSopenharmony_ci <b>glXClientInfo</b> request to the server at start up time (if the 3125bd8deadSopenharmony_ci client libarary is 1.1 or later) indicating the version of the 3135bd8deadSopenharmony_ci client library and the OpenGL extensions that it supports. Then, 3145bd8deadSopenharmony_ci when <b>glGetString</b> is called, the client issues a GetString 3155bd8deadSopenharmony_ci request. The server intersects the set of extensions that the client 3165bd8deadSopenharmony_ci supports with the set of extensions that it supports (if a 3175bd8deadSopenharmony_ci <b>glXClientInfo</b> request was never received then the server 3185bd8deadSopenharmony_ci assumes that the client supports no OpenGL extensions) and returns 3195bd8deadSopenharmony_ci the result to the client. The client library then appends any 3205bd8deadSopenharmony_ci client-side only extensions to the list and returns the result. 3215bd8deadSopenharmony_ci 3225bd8deadSopenharmony_ci<p> Extension names for all known OpenGL extensions are #defined in the 3235bd8deadSopenharmony_ci <tt>glext.h</tt> header included in the registry. 3245bd8deadSopenharmony_ci 3255bd8deadSopenharmony_ci<h4><u>EGL Extension Availability</u></h4> 3265bd8deadSopenharmony_ci 3275bd8deadSopenharmony_ci<p> EGL extensions must be advertised in the extension string returned 3285bd8deadSopenharmony_ci by <tt>eglQueryString(EGL_EXTENSIONS)</tt>. Extension names for all 3295bd8deadSopenharmony_ci known EGL extensions are #defined in the <tt>eglext.h</tt> header 3305bd8deadSopenharmony_ci included in the registry. 3315bd8deadSopenharmony_ci 3325bd8deadSopenharmony_ci<h4><u>GLX Extension Availability</u></h4> 3335bd8deadSopenharmony_ci 3345bd8deadSopenharmony_ci<p> GLX client-side extensions must be advertised in the extension 3355bd8deadSopenharmony_ci string returned by <b>glXGetClientString</b>; server-side extensions 3365bd8deadSopenharmony_ci must be advertised in the extension string returned by 3375bd8deadSopenharmony_ci <b>glXQueryServerString</b>. 3385bd8deadSopenharmony_ci 3395bd8deadSopenharmony_ci<p> <b>glXQueryExtensionsString</b> returns the list of extensions that 3405bd8deadSopenharmony_ci can be supported on the connection. The client then issues a 3415bd8deadSopenharmony_ci <b>glXQueryServerString</b> request, intersects the returned string 3425bd8deadSopenharmony_ci with the set of extensions it can support and then appends any 3435bd8deadSopenharmony_ci client-side only extensions to the list. 3445bd8deadSopenharmony_ci 3455bd8deadSopenharmony_ci<p> Extension names for all known GLX extensions are #defined in the 3465bd8deadSopenharmony_ci <tt>glxext.h</tt> header included in the registry. 3475bd8deadSopenharmony_ci 3485bd8deadSopenharmony_ci<h4><u>WGL Extension Availability</u></h4> 3495bd8deadSopenharmony_ci 3505bd8deadSopenharmony_ci<p> WGL initially had no mechanism for returning its own extensions 3515bd8deadSopenharmony_ci string. For this reason, WGL extension names were initially 3525bd8deadSopenharmony_ci advertised in the GL extensions string returned by 3535bd8deadSopenharmony_ci <b>glGetString</b>. With the creation of a more formal WGL extension 3545bd8deadSopenharmony_ci mechanism, all implementations offering WGL extensions should export 3555bd8deadSopenharmony_ci the <tt>WGL_EXT_extensions_string</tt> extension, and should 3565bd8deadSopenharmony_ci advertise WGL extensions in the extensions string returned by the 3575bd8deadSopenharmony_ci <b>wglGetExtensionsStringEXT</b> interface defined by 3585bd8deadSopenharmony_ci <tt>WGL_EXT_extensions_string</tt>, as well as via 3595bd8deadSopenharmony_ci <b>glGetString</b>, for compatibility with older programs.</p> 3605bd8deadSopenharmony_ci 3615bd8deadSopenharmony_ci<p> Extension names for all known WGL extensions are #defined in the 3625bd8deadSopenharmony_ci <tt>wglext.h</tt> header included in the registry. 3635bd8deadSopenharmony_ci 3645bd8deadSopenharmony_ci<p><hr> 3655bd8deadSopenharmony_ci 3665bd8deadSopenharmony_ci<a name="using"></a> 3675bd8deadSopenharmony_ci<h2>Use of Extensions</h2> 3685bd8deadSopenharmony_ci 3695bd8deadSopenharmony_ci<h4><u>Using OpenGL Extensions</u></h4> 3705bd8deadSopenharmony_ci 3715bd8deadSopenharmony_ci<p> Programmers that wish to use a particular OpenGL extension should 3725bd8deadSopenharmony_ci check both compile-time defines (to ensure that the extension is 3735bd8deadSopenharmony_ci supported by the library they are compiling against) and the 3745bd8deadSopenharmony_ci extension string returned by <b>glGetString</b> (to ensure that the 3755bd8deadSopenharmony_ci renderer supports the extension). For Windows, extensions usually 3765bd8deadSopenharmony_ci are not defined at link time, and function pointers to extension 3775bd8deadSopenharmony_ci APIs should be obtained by calling <b>wglGetProcAddress</b>. 3785bd8deadSopenharmony_ci 3795bd8deadSopenharmony_ci<p> For example, the following code could be used to check whether the 3805bd8deadSopenharmony_ci renderer supports an OpenGL extension called 3815bd8deadSopenharmony_ci <tt>GL_EXT_new_extension</tt>. This code would need to be executed 3825bd8deadSopenharmony_ci after the context had been made current: 3835bd8deadSopenharmony_ci 3845bd8deadSopenharmony_ci<blockquote><pre><tt> 3855bd8deadSopenharmony_ci static GLboolean CheckExtension(char *extName, const char *extString) 3865bd8deadSopenharmony_ci { 3875bd8deadSopenharmony_ci /* 3885bd8deadSopenharmony_ci ** Search for extName in the extensions string. Use of strstr() 3895bd8deadSopenharmony_ci ** is not sufficient because extension names can be prefixes of 3905bd8deadSopenharmony_ci ** other extension names. Could use strtok() but the constant 3915bd8deadSopenharmony_ci ** string returned by glGetString can be in read-only memory. 3925bd8deadSopenharmony_ci */ 3935bd8deadSopenharmony_ci char *p = (char *)extString; 3945bd8deadSopenharmony_ci char *end; 3955bd8deadSopenharmony_ci int extNameLen; 3965bd8deadSopenharmony_ci 3975bd8deadSopenharmony_ci extNameLen = strlen(extName); 3985bd8deadSopenharmony_ci end = p + strlen(p); 3995bd8deadSopenharmony_ci 4005bd8deadSopenharmony_ci while (p < end) { 4015bd8deadSopenharmony_ci int n = strcspn(p, " "); 4025bd8deadSopenharmony_ci if ((extNameLen == n) && (strncmp(extName, p, n) == 0)) { 4035bd8deadSopenharmony_ci return GL_TRUE; 4045bd8deadSopenharmony_ci } 4055bd8deadSopenharmony_ci p += (n + 1); 4065bd8deadSopenharmony_ci } 4075bd8deadSopenharmony_ci return GL_FALSE; 4085bd8deadSopenharmony_ci } 4095bd8deadSopenharmony_ci 4105bd8deadSopenharmony_ci const GLubyte *ext_string; 4115bd8deadSopenharmony_ci int new_ext_supported = GL_FALSE; 4125bd8deadSopenharmony_ci 4135bd8deadSopenharmony_ci if (CheckExtension("GL_EXT_new_extension", glGetString(GL_EXTENSIONS))) 4145bd8deadSopenharmony_ci new_ext_supported = GL_TRUE; 4155bd8deadSopenharmony_ci</tt></pre></blockquote> 4165bd8deadSopenharmony_ci 4175bd8deadSopenharmony_ci<p> If the renderer supports the extension, then it is safe to use it at 4185bd8deadSopenharmony_ci runtime. (Note that in a client-server environment, 4195bd8deadSopenharmony_ci <b>glGetString</b> will only return the set of extensions that can 4205bd8deadSopenharmony_ci be supported by the client and server.) However, compile time checks 4215bd8deadSopenharmony_ci must be made to ensure that the library that you are linked against 4225bd8deadSopenharmony_ci supports the extension. For example: 4235bd8deadSopenharmony_ci 4245bd8deadSopenharmony_ci<blockquote><pre><tt> 4255bd8deadSopenharmony_ci #ifdef GL_EXT_new_extension 4265bd8deadSopenharmony_ci if (new_ext_supported) 4275bd8deadSopenharmony_ci glNewExtensionEXT() 4285bd8deadSopenharmony_ci #endif 4295bd8deadSopenharmony_ci</tt></pre></blockquote> 4305bd8deadSopenharmony_ci 4315bd8deadSopenharmony_ci<p> For a Windows OpenGL implementation, extensions are usually 4325bd8deadSopenharmony_ci dynamically loaded from the device driver, rather than statically 4335bd8deadSopenharmony_ci linked. Function pointers to extension APIs are obtained from 4345bd8deadSopenharmony_ci <b>wglGetProcAddress</b> and use to invoke the extension. For 4355bd8deadSopenharmony_ci example: 4365bd8deadSopenharmony_ci 4375bd8deadSopenharmony_ci<blockquote><pre><tt> 4385bd8deadSopenharmony_ci typedef void (WINAPI *PFNGLNEWEXTENSIONEXTPROC)(); 4395bd8deadSopenharmony_ci PFNGLNEWEXTENSIONEXTPROC *glNewExtensionEXT = NULL; 4405bd8deadSopenharmony_ci 4415bd8deadSopenharmony_ci /* Do this once, after context creation */ 4425bd8deadSopenharmony_ci #ifdef GL_EXT_new_extension 4435bd8deadSopenharmony_ci if (new_ext_supported) 4445bd8deadSopenharmony_ci glNewExtensionEXT = (PFNGLNEWEXTENSIONEXTPROC) 4455bd8deadSopenharmony_ci wglGetProcAddress("glNewExtensionEXT"); 4465bd8deadSopenharmony_ci #endif 4475bd8deadSopenharmony_ci 4485bd8deadSopenharmony_ci /* Do this when calling the extension */ 4495bd8deadSopenharmony_ci #ifdef GL_EXT_new_extension 4505bd8deadSopenharmony_ci if (new_ext_supported) 4515bd8deadSopenharmony_ci (*glNewExtensionEXT)(); 4525bd8deadSopenharmony_ci #endif 4535bd8deadSopenharmony_ci</tt></pre></blockquote> 4545bd8deadSopenharmony_ci 4555bd8deadSopenharmony_ci<h4><u>Using EGL Extensions</u></h4> 4565bd8deadSopenharmony_ci 4575bd8deadSopenharmony_ci<p> Before using an EGL extension, check for the extension name in both 4585bd8deadSopenharmony_ci the compile-time #defines and the extension string returned by 4595bd8deadSopenharmony_ci <tt>eglGetString(EGL_EXTENSIONS)</tt>. For example, this code could 4605bd8deadSopenharmony_ci be used to check whether an extension called 4615bd8deadSopenharmony_ci <tt>EGL_OES_new_extension</tt> can be used. 4625bd8deadSopenharmony_ci 4635bd8deadSopenharmony_ci<blockquote><pre><tt> 4645bd8deadSopenharmony_ci EGLDisplay dpy; // Initialized elsewhere 4655bd8deadSopenharmony_ci int new_ext_supported = FALSE; 4665bd8deadSopenharmony_ci 4675bd8deadSopenharmony_ci if (CheckExtension("EGL_OES_new_extension", 4685bd8deadSopenharmony_ci eglGetString(display, EGL_EXTENSIONS)); 4695bd8deadSopenharmony_ci new_ext_supported = TRUE; 4705bd8deadSopenharmony_ci #endif 4715bd8deadSopenharmony_ci</tt></pre></blockquote> 4725bd8deadSopenharmony_ci 4735bd8deadSopenharmony_ci<p> If the extension is supported, then it is safe to use it at runtime. 4745bd8deadSopenharmony_ci However, compile time checks must be made to ensure that you can 4755bd8deadSopenharmony_ci call the extension. For example: 4765bd8deadSopenharmony_ci 4775bd8deadSopenharmony_ci<blockquote><pre><tt> 4785bd8deadSopenharmony_ci #ifdef EGL_OES_new_extension 4795bd8deadSopenharmony_ci if (new_ext_supported) 4805bd8deadSopenharmony_ci eglNewExtensionEXT(...); 4815bd8deadSopenharmony_ci #endif 4825bd8deadSopenharmony_ci</tt></pre></blockquote> 4835bd8deadSopenharmony_ci 4845bd8deadSopenharmony_ci<h4><u>Using GLX Extensions</u></h4> 4855bd8deadSopenharmony_ci 4865bd8deadSopenharmony_ci<p> Before using a GLX extension, programmers should check the compile 4875bd8deadSopenharmony_ci time defines and the extension string returned by 4885bd8deadSopenharmony_ci <b>glXQueryExtensionsString</b>. 4895bd8deadSopenharmony_ci 4905bd8deadSopenharmony_ci<p> The following code could be used to check whether an extension 4915bd8deadSopenharmony_ci called <tt>GLX_EXT_new_extension</tt> can be used on the connection. 4925bd8deadSopenharmony_ci This code would be executed after the connection had been opened and 4935bd8deadSopenharmony_ci the existence of the GLX extension had been established. 4945bd8deadSopenharmony_ci 4955bd8deadSopenharmony_ci<blockquote><pre><tt> 4965bd8deadSopenharmony_ci Display *dpy; 4975bd8deadSopenharmony_ci int new_ext_supported = GL_FALSE; 4985bd8deadSopenharmony_ci int major, minor, screen; 4995bd8deadSopenharmony_ci 5005bd8deadSopenharmony_ci if (!glXQueryVersion(dpy, &major, &minor)) 5015bd8deadSopenharmony_ci exit(1); 5025bd8deadSopenharmony_ci screen = DefaultScreen(dpy); 5035bd8deadSopenharmony_ci 5045bd8deadSopenharmony_ci #ifdef GLX_VERSION_1_1 5055bd8deadSopenharmony_ci if (minor > 0 || major > 1) 5065bd8deadSopenharmony_ci if (CheckExtension("GLX_EXT_new_extension", 5075bd8deadSopenharmony_ci glXQueryExtensionsString(dpy, screen))) 5085bd8deadSopenharmony_ci new_ext_supported = GL_TRUE; 5095bd8deadSopenharmony_ci #endif 5105bd8deadSopenharmony_ci</tt></pre></blockquote> 5115bd8deadSopenharmony_ci 5125bd8deadSopenharmony_ci<p> If the extension is supported on the connection, then it is safe to 5135bd8deadSopenharmony_ci use it at runtime. However, compile time checks must be made to 5145bd8deadSopenharmony_ci ensure that the library that you are linked against supports the 5155bd8deadSopenharmony_ci extension. For example: 5165bd8deadSopenharmony_ci 5175bd8deadSopenharmony_ci<blockquote><pre><tt> 5185bd8deadSopenharmony_ci #ifdef GLX_EXT_new_extension 5195bd8deadSopenharmony_ci if (new_ext_supported) 5205bd8deadSopenharmony_ci glXNewExtensionEXT(...); 5215bd8deadSopenharmony_ci #endif 5225bd8deadSopenharmony_ci</tt></pre></blockquote> 5235bd8deadSopenharmony_ci 5245bd8deadSopenharmony_ci<h4><u>Using WGL Extensions</u></h4> 5255bd8deadSopenharmony_ci 5265bd8deadSopenharmony_ci<p> Before using a WGL extension, check for its presence in the WGL 5275bd8deadSopenharmony_ci extensions string. Note that the WGL extension string query is 5285bd8deadSopenharmony_ci itself an extension; if not supported, WGL extensions are also 5295bd8deadSopenharmony_ci advertised in the base GL extensions string. 5305bd8deadSopenharmony_ci 5315bd8deadSopenharmony_ci <p> <i>Code snippet should go here</i> 5325bd8deadSopenharmony_ci 5335bd8deadSopenharmony_ci<p> <hr> 5345bd8deadSopenharmony_ci 5355bd8deadSopenharmony_ci<p> Last modified August 13, 2006 by Jon Leech 5365bd8deadSopenharmony_ci 5375bd8deadSopenharmony_ci</body> 5385bd8deadSopenharmony_ci</html> 539