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## Reserving EGL Enumerant Ranges 34 35EGL enumerants are documented in api/egl.xml . New ranges can be allocated 36by proposing a pull request to master modifying this file, following the 37existing examples. Allocate ranges starting at the lowest free values 38available (search for "Reservable for future use"). Ranges are not 39officially allocated until your pull request is *accepted* into master. At 40that point you can use values from your assigned range for API extensions. 41 42 43## Adding Extension Specifications 44 45Extension specification documents can be added by proposing a pull request 46to master, adding the specification .txt file and related changes under 47extensions/\<vendor\>/filename.txt. Your pull request must also: 48 49* Allocate an extension number in registry.tcl (follow the existing 50 ```<extension>``` examples, search for "Next free extension number", and use 51 the lowest available extension number). 52* Include that extension number in the extension specification document. 53* Define the interfaces introduced by this extension in api/egl.xml, 54 following the examples of existing extensions. If you have difficulty 55 doing this, consult the registry schema documentation in the GL registry 56 at www.khronos.org/registry/gl/; you may also create Issues in the 57 EGL-Registry repository to request help. 58* Verify that the EGL headers regenerate properly after applying your XML 59 changes. In the api/ directory, you must be able to do the following without 60 errors: 61``` 62 # Validate XML changes 63 make validate 64 # Verify headers build and are legal C 65 make clobber 66 make 67 make tests 68``` 69* Finally, add a link from the extensions section of index.php to the 70 extension document, using the specified extension number, so it shows up 71 in the web view (this could in principle be generated automatically from 72 registry.tcl / egl.xml, but isn't at present). 73 74Sometimes extension text files contain inappropriate UTF-8 characters. They 75should be restricted to the ASCII subset of UTF-8 at present. They can be 76removed using the iconv Linux command-line tool via 77 78 iconv -c -f utf-8 -t ascii filename.txt 79 80(see internal Bugzilla issue 16141 for more). 81 82We may transition to an asciidoc-based extension specification format at 83some point. 84 85 86## Build Tools 87 88This section is not complete (see https://github.com/KhronosGroup/EGL-Registry/issues/92). 89 90To validate the XML and build the headers you will need at least GNU make, 91'jing' for the 'make validate' step (https://relaxng.org/jclark/jing.html), 92and Python 3.5 and the lxml.etree Python library 93(https://pypi.org/project/lxml/) for the 'make' step. The 'make tests' step 94requires whatever the C and C++ compilers configured for GNU make are, 95usually gcc and g++. 96 97All of these components are available prepackaged for major Linux 98distributions and for the Windows 10 Debian WSL. 99 100 101