mirror of
https://gitlab.freedesktop.org/mesa/mesa.git
synced 2026-05-15 22:58:05 +02:00
be9da194f8
Reviewed-by: Emma Anholt <emma@anholt.net> Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com> Reviewed-by: Samuel Pitoiset <samuel.pitoiset@gmail.com> Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/41400>
103 lines
4.1 KiB
ReStructuredText
103 lines
4.1 KiB
ReStructuredText
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``.
|