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