1// XX to be filled in by the merger of this PR (likely Jon) 2= *Advance Notice of Pending XML Registry Change (posted 2021-01-XX)* 3 4[WARNING] 5.Warning 6==== 7Shortly after 2021-04-XX, we will be removing the old-style group blocks 8(contained within the `groups` section at the top of the XML registry) 9The groups are intended to contain all the possible legal values 10for corresponding function parameters, but it is likely that many 11of the groups are out of date relative to current OpenGL and OpenGL 12ES specifications, and the many extensions to those specifications. 13As of Wednesday 8th January 2020, these group blocks have been 14deprecated in favour of group attributes declared inline with 15the enumerant itself, which are currently the only actively updated 16source for groupings. For more information, see public issue 17link:https://github.com/KhronosGroup/OpenGL-Registry/issues/335[#335]. 18==== 19 20 21= OpenGL-Registry 22 23 24== OpenGL, OpenGL ES, and OpenGL ES-SC API and Extension Registry 25 26This site contains the API and Extension registries for the OpenGL family 27APIs - OpenGL, OpenGL ES, and OpenGL SC. It includes API specifications; 28specifications of Khronos- and vendor-approved extensions; header files 29corresponding to the specifications; the XML API Registry defining each 30API; and related tools and scripts. 31 32It does not contain the OpenGL and OpenGL ES Reference Pages, which are in 33the KhronosGroup/OpenGL-Refpages repository. 34 35If you want to add an extension specification to the Registry, correct an 36existing specification, request allocation of enumerants and other 37controlled resources in the OpenGL / GLX / WGL namespaces, or otherwise 38change the Registry, propose a pull request against the OpenGL-Registry 39repository and adding the appropriate extension specifications, making changes 40to the appropriate XML file, etc. Note that any changes you propose to 41reserved values in the registry are not official until your pull request is 42*accepted* into the master branch. 43 44Feel free to post issues on the repository if it's unclear how to do 45something you need to with extensions, or if you find any problems. 46 47 48== Please Don't File API And GLSL Bugs Here! 49 50The OpenGL-Registry repository isn't the right place to report problems with 51the OpenGL and OpenGL ES API and Shading Language Specifications. 52 53For API (both core and extension) issues, please use the issue tracker in 54the https://github.com/KhronosGroup/OpenGL-API repository. 55 56For Shading Language (both core and extension) issues, please use the issue 57tracker in the https://github.com/KhronosGroup/OpenGL-GLSL repository. 58 59Please tag your issues with +[OpenGL]+ or +[OpenGL ES]+ in the title, if 60they are specific to that API and/or Shading Language. 61 62Reporting problems with the registry *itself*, including missing or badly 63formed extension documents, headers, or XML files, should be done using the 64OpenGL-Registry issue tracker. 65 66 67=== Defining New Extensions 68 69To create a new extension specification, take these steps: 70 71* Request one or more blocks of unused enumerants for GL, GLX, or WGL 72 depending on the needs of your extension, by adding the reservation(s) to 73 the end of gl.xml, glx.xml, and/or wgl.xml. 74* Once the pull request modifying the XML files is accepted into master, you 75 have control of those enumerant blocks. 76* Create an extension specification, following the model of existing vendor 77 specifications under extensions/*vendor*/ . 78* Obtain whatever degree of review, implementation, and signoff you need 79 from affected parties before declaring the extension complete. 80* Add the extension specification under extensions/*vendor*/*extension* . 81* Modify extensions/registry.py to include the extension, using the next 82 free ARB, GL, and/or ES extension numbers (depending on which API the 83 extension is defined for). Execute the python script nextfree.py in the 84 extensions/ directory to find the next free numbers. 85* Once registry.py is updated, 'make' in extensions/ to update the PHP 86 include files which are used to show an index of extensions on the 87 registry website. This requires GNU make and Python 3. 88* Add the extension number(s) to the extension specification in the 'Number' 89 block. 90* Add the extension interfaces and enumerant assignments to xml/gl.xml, 91 glx.xml, and/or wgl.xml following existing examples. Verify that the 92 relevant extension headers are generated with the correct interfaces by 93 running 'make' in xml/. This requires the lxml Python module. 94* Once the pull request adding the extension specification and modifying 95 registry.py is accepted, your extension is registered. 96 97There are some documents under the docs/ directory describing some of the 98processes for making extensions, but they are largely out of date. They may 99be updated or removed over time: 100 101* link:docs/rules.html[How to create extensions] 102* link:docs/enums.html[Enumerant allocation policies] 103* link:docs/template.txt[Extension specification template] 104* link:docs/promoting.html[Extension promotion guidelines] 105* link:docs/reserved.txt[GLX opcode registry (rarely updated)] 106* link:docs/syntaxrules.txt[OpenGL Syntax Rules (updated 2006/12/13)] 107* link:docs/GLSLExtensionRules.txt[OpenGL Shading Language Extension Conventions (updated 2006/12/18)] 108* link:docs/fog_coord.txt[Extension Specification Example] 109 110 111=== Repository Contents 112 113* ABI - OpenGL ABI for Linux 114* api - Header files for all APIs 115** api/ES - Headers for OpenGL ES 116** api/GL - Headers for OpenGL 117** api/SC - Headers for OpenGL SC 118** Note that the OpenGL ES and OpenGL SC headers all depend on the shared 119 https://www.khronos.org/registry/EGL/api/KHR/khrplatform.h[khrplatform.h] 120 This file is maintained in the http://www.khronos.org/registry/EGL/[EGL 121 Registry]. 122* docs - Miscellaneous documentation on creating extensions, mostly out of date. 123* extensions - Extension specifications for all APIs 124** extensions/registry.py - combined extension registry for all APIs 125** extensions/makeindex.py - create HTML extension indices from registry.py 126* index_{es,gl,sc}.php - Index files for the website, linking to specifications, headers, and extensions relevant to each API 127* specs - API and Shading Language Specifications for all APIs 128** specs/es - OpenGL ES Specifications 129** specs/gl - OpenGL Specifications 130** specs/sc - OpenGL SC Specifications 131* xml - XML API Registry and related tools 132 133 134=== There Sure Is A Lot Of Stuff In Here! 135 136Yes, there sure is. The specs/ directory contains over 125 MB of PDFs, 137including the latest specs for each version of OpenGL and OpenGL ES. While 138this may be somewhat distressing to people who just want to add a single 139extension, due to the repository download time, the *primary* purpose of 140this repository is to be the backing store for the web registry on 141khronos.org. Fortunately git is very efficient, so once you've done the 142initial repository clone, updates will be small and quick. 143