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