README.md
1# EGL-Registry
2
3The EGL-Registry repository contains the EGL API and Extension Registry,
4including specifications, reference pages and reference cards, and the
5enumerant registry. It is also used as a backing store for the web view of
6the registry at https://www.khronos.org/registry/egl/ ; commits to the
7master branch of this repository will be reflected there.
8
9In the past, the EGL registry was maintained in a public Subversion
10repository. The history in that repository has not been imported to github,
11but it is still available at
12https://cvs.khronos.org/svn/repos/registry/trunk/public/egl/ .
13
14Interesting files in this repository include:
15
16* index.php - toplevel index page for the web view. This relies on PHP
17 include files found elsewhere on www.khronos.org and so is not very useful
18 in isolation.
19* registry.tcl - extension number registry. Documents the names and index
20 numbers assigned to EGL extension specifications.
21* api/egl.xml - extension enumerant and API registry. Defines the EGL API,
22 including extensions, and is used to generate headers. Documents the EGL
23 enumerant ranges assigned to different vendors.
24* api/EGL/ and api/KHR/ - header files used by an EGL implementation.
25 EGL/eglext.h and EGL/egl.h are generated from egl.xml. The other headers
26 are handcoded and express OS and window system (platform) dependencies.
27* extensions/ - EGL extension specifications, grouped into vendor-specific
28 subdirectories.
29* sdk/ - EGL reference pages and reference cards. There are separate sets
30 for each API version.
31* specs/ - EGL specification documents.
32
33
34## Reserving EGL Enumerant Ranges
35
36EGL enumerants are documented in api/egl.xml . New ranges can be allocated
37by proposing a pull request to master modifying this file, following the
38existing examples. Allocate ranges starting at the lowest free values
39available (search for "Reservable for future use"). Ranges are not
40officially allocated until your pull request is *accepted* into master. At
41that point you can use values from your assigned range for API extensions.
42
43
44## Adding Extension Specifications
45
46Extension specification documents can be added by proposing a pull request
47to master, adding the specification .txt file and related changes under
48extensions/\<vendor\>/filename.txt. Your pull request must also:
49
50* Allocate an extension number in registry.tcl (follow the existing
51 ```<extension>``` examples, search for "Next free extension number", and use
52 the lowest available extension number).
53* Include that extension number in the extension specification document.
54* Define the interfaces introduced by this extension in api/egl.xml,
55 following the examples of existing extensions. If you have difficulty
56 doing this, consult the registry schema documentation in the GL registry
57 at www.khronos.org/registry/gl/; you may also create Issues in the
58 EGL-Registry repository to request help.
59* Verify that the EGL headers regenerate properly after applying your XML
60 changes. In the api/ directory, you must be able to do the following without
61 errors:
62```
63 # Validate XML changes
64 make validate
65 # Verify headers build and are legal C
66 make clobber
67 make
68 make tests
69```
70* Finally, add a link from the extensions section of index.php to the
71 extension document, using the specified extension number, so it shows up
72 in the web view (this could in principle be generated automatically from
73 registry.tcl / egl.xml, but isn't at present).
74
75Sometimes extension text files contain inappropriate UTF-8 characters. They
76should be restricted to the ASCII subset of UTF-8 at present. They can be
77removed using the iconv Linux command-line tool via
78
79 iconv -c -f utf-8 -t ascii filename.txt
80
81(see internal Bugzilla issue 16141 for more).
82
83We may transition to an asciidoc-based extension specification format at
84some point.
85