From 1f4a1e35ce8a7e42afa5cf60858126c0b3952756 Mon Sep 17 00:00:00 2001 From: Faith Ekstrand Date: Wed, 6 May 2026 10:28:37 -0400 Subject: [PATCH 1/3] docs: Move and rename "Development Notes" Also, re-title things to make it clear that the current text is about implementing OpenGL[ES] extensions. --- docs/{devinfo.rst => developing-extensions.rst} | 10 +++++----- docs/index.rst | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) rename docs/{devinfo.rst => developing-extensions.rst} (92%) diff --git a/docs/devinfo.rst b/docs/developing-extensions.rst similarity index 92% rename from docs/devinfo.rst rename to docs/developing-extensions.rst index 34921c10ca4..a5cfc88de9b 100644 --- a/docs/devinfo.rst +++ b/docs/developing-extensions.rst @@ -1,8 +1,8 @@ -Development Notes -================= +Developing Extensions +===================== -Adding Extensions ------------------ +Implementing OpenGL[ES] Extensions +---------------------------------- To add a new GL extension to Mesa you have to do at least the following. @@ -17,7 +17,7 @@ To add a new GL extension to Mesa you have to do at least the following. /* 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 diff --git a/docs/index.rst b/docs/index.rst index a1bd8a7d9ae..4448b7cbe91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,9 +105,9 @@ Linux, FreeBSD, and other operating systems. sourcetree utilities helpwanted - devinfo codingstyle submittingpatches + developing-extensions rust releasing release-calendar From 2f9bf676f422b8b9a24f86ddc328b92962120aad Mon Sep 17 00:00:00 2001 From: Faith Ekstrand Date: Wed, 6 May 2026 11:55:36 -0400 Subject: [PATCH 2/3] docs: Add docs with Vulkan/SPIR-V extensions basics --- docs/developing-extensions.rst | 70 +++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/docs/developing-extensions.rst b/docs/developing-extensions.rst index a5cfc88de9b..d73149493b2 100644 --- a/docs/developing-extensions.rst +++ b/docs/developing-extensions.rst @@ -1,8 +1,74 @@ Developing Extensions ===================== -Implementing OpenGL[ES] Extensions ----------------------------------- +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. From 54fd0d390df2a7a7ad801fa0ec51b1a8029b53ae Mon Sep 17 00:00:00 2001 From: Faith Ekstrand Date: Wed, 6 May 2026 12:16:44 -0400 Subject: [PATCH 3/3] docs: Add docs for drafting new MESA extensions --- docs/developing-extensions.rst | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/developing-extensions.rst b/docs/developing-extensions.rst index d73149493b2..e3c403d164b 100644 --- a/docs/developing-extensions.rst +++ b/docs/developing-extensions.rst @@ -1,6 +1,58 @@ 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 representativs 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 ---------------------------