| Developing Extensions | |
| ===================== | |
| Drafting new MESA extensions | |
| ---------------------------- | |
| The Mesa project works closely with Khronos, the standards body that | |
| governs the OpenGL, OpenCL, EGL, and Vulkan specifications. Mesa | |
| developers are often spec authors and not just implementors. There are | |
| several ``GL_MESA_*`` and ``VK_MESA_`` extensions which serve the unique | |
| needs of the Linux graphics ecosystem as well as many other vendor, EXT, | |
| and even KHR extensions extensions with Mesa developers as authors. | |
| There are generally two processes for developing new extensions. For | |
| developers who work for a Khronos member company, extensions can be | |
| developed via the normal Khronos process. This means making a merge | |
| request to the Khronos internal repositories, responding to review feedback | |
| from the working group, and participating in the conference calls where | |
| in-development extensions are discussed. This process happens under the | |
| Khronos NDA and is a little more heavy-weight than most Mesa discussions. | |
| However, this is generally the preferred method from a Khronos perspective | |
| because the NDA gives the hardware company representatives the freedom to be | |
| more involved with extension review. | |
| Alternatively, extensions can be developed in public. This is done by | |
| opening a pull request against the ``KhronosGroup/Vulkan-Docs`` and related | |
| repositories on GitHub. The advantage of this process is that it is | |
| publicly visible and more accessible to open-source developers. This makes | |
| it the preferred process when developing something that needs broad Linux | |
| ecosystem consensus and where we need review from people who aren't under | |
| the Khronos NDA. The downside is that hardware company representatives are | |
| much less likely to interact. If the extension exposes hardware and not | |
| software details, it's better to go through the Khronos process. | |
| Regardless of which path is taken, any extensions bearing the MESA prefix, | |
| need to adhere to the following policy: | |
| 1. The extension needs to be accompanied by a Mesa merge request and the | |
| extension MR needs to link to the Mesa MR. For public extensions, both | |
| merge requests should be public and they should link to each other. | |
| For extensions developed under the Khronos NDA, the Mesa merge request | |
| can be made in the Khronos-internal Mesa repo. | |
| 2. As with all other extensions, MESA extensions must be accompanied by | |
| CTS tests to ensure we can regression test them in CI. | |
| 3. Before the extension gets merged and released, the Mesa implementation | |
| must be complete, passing the relevant CTS tests, and the code | |
| reviewed. For extensions developed under the Khronos NDA, further | |
| review may happen when the implementation goes public. However, | |
| developers should make a good-faith effort to get enough relevant | |
| review while the extension is still in development to find any issues | |
| which may impact the specification itself. | |
| Implementing new extensions | |
| --------------------------- | |
| Updating Khronos XML and headers | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| When implementing a brand new extension, Mesa's copies of the relevant spec | |
| assets may need to be updated: | |
| - For Vulkan, the headers are placed in ``include/vulkan/`` and the XML | |
| description is placed in ``src/vulkan/registry/vk.xml`` | |
| - For SPIR-V, the headers and JSON files are placed in | |
| ``src/compiler/spirv/``. | |
| - For OpenGL and OpenGL ES, the headers are placed in ``include/GL/`` or | |
| ``include/GLES*/`` and the XML description is placed in | |
| ``src/mesa/glapi/glapi/registry/gl.xml``. | |
| - For EGL, the headers are placed in ``include/EGL/`` and the XML | |
| description is placed in ``src/egl/generate/egl.xml``. | |
| - For OpenCL, the headers are placed in ``include/CL/``. | |
| All of these must be updated with the ``khronos_update.py`` script in | |
| ``bin/``. They should not be updated manually. The script updates all | |
| headers and XML/JSON descriptions by default but only the changes for the | |
| relevant API need to be checked in. When updating XML or headers, provide | |
| a descriptive commit message that specifies the new version. | |
| Implementing Vulkan extensions | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| As of today, implementing Vulkan extensions is a mostly per-driver process. | |
| Pulling a new XML and headers will automatically update all the dispatch | |
| table and other codegen. It's then up to the driver to implement and | |
| advertise the extension. When advertising a new extension, remember that | |
| there are generally three places that need updating: | |
| - The driver's supported extensions table | |
| - The driver's supported features table | |
| - The driver's properties table | |
| The extensions and features tables are split in two: physical device and | |
| instance. The instance tables are used for instance extensions and the | |
| physical device tables are used for physical device extensions. Only | |
| physical device extensions have properties. | |
| Implementing SPIR-V capabilities | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| SPIR-V features are typically implemented in terms of capabilities, not | |
| extensions. While SPIR-V does have extension strings, Mesa generally | |
| ignores them. When implementing a new SPIR-V feature, the | |
| ``implemented_capabilities`` table needs to be updated. This table only | |
| describes the capabilities implemented by the SPIR-V parser. There is also | |
| a ``supported_capabilities`` table that gets passed into the SPIR-V parser. | |
| For OpenGL or OpenCL, implementing a new SPIR-V capability requires also | |
| updating the ``supported_capabilities`` in the relevant state tracker. For | |
| Vulkan, ``supported_capabilities`` is automatically populated based on the | |
| Vulkan device's physical device features. | |
| Implementing OpenGL[ES] extensions | |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| To add a new GL extension to Mesa you have to do at least the following. | |
| - If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h`` | |
| and add code like this: | |
| .. code-block:: c | |
| #ifndef GL_EXT_the_extension_name | |
| #define GL_EXT_the_extension_name 1 | |
| /* declare the new enum tokens */ | |
| /* prototype the new functions */ | |
| /* TYPEDEFS for the new functions */ | |
| #endif | |
| - In the ``src/mesa/glapi/glapi/gen/`` directory, add the new extension | |
| functions and enums to the ``gl_API.xml`` file. Then, a bunch of | |
| source files must be regenerated by executing the corresponding | |
| Python scripts. | |
| - Add a new entry to the ``gl_extensions`` struct in ``consts_exts.h`` if | |
| the extension requires driver capabilities not already exposed by | |
| another extension. | |
| - Add a new entry to the ``src/mesa/main/extensions_table.h`` file. | |
| - From this point, the best way to proceed is to find another | |
| extension, similar to the new one, that's already implemented in Mesa | |
| and use it as an example. | |
| - If the new extension adds new GL state, the functions in ``get.c``, | |
| ``enable.c`` and ``attrib.c`` will most likely require new code. | |
| - To determine if the new extension is active in the current context, | |
| use the auto-generated ``_mesa_has_##name_str()`` function defined in | |
| ``src/mesa/main/extensions.h``. |