Developing 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.

-  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``.