Skip to content

Commit a9208f4

Browse files
committed
Add Vulkan API update instructions
1 parent d6d1f11 commit a9208f4

2 files changed

Lines changed: 72 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Common documentation
6464

6565
* [Building a layer](./docs/building.md)
6666
* [Creating a new layer](./docs/creating.md)
67+
* [Updating an existing layer](./docs/updating.md)
6768
* [Running using a layer on Android](./docs/running_android.md)
6869
* [Running using a layer on Linux](./docs/running_linux.md)
6970
* [About layers design notes](./docs/about_layers.md)
@@ -86,7 +87,7 @@ or general mobile graphics development or technology, please submit them on the
8687

8788
- - -
8889

89-
_Copyright © 2024-2025, Arm Limited and contributors._
90+
_Copyright © 2024-2026, Arm Limited and contributors._
9091

9192
[1]: https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum/
9293
[2]: https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio

‎docs/updating.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Updating layers
2+
3+
This page gives you instructions for updating an existing layer to use a newer
4+
version of Vulkan.
5+
6+
## Updating Vulkan version
7+
8+
When updating to a newer version of Vulkan, there are three things that need to
9+
be updated in sync or things will break:
10+
11+
* Upstream Vulkan headers (submodule)
12+
* Upstream Vulkan utilities library (submodule)
13+
* Generated common code in libGPULayers
14+
15+
### Updating submodules
16+
17+
Updating Khronos Vulkan headers, e.g.:
18+
19+
```sh
20+
pushd .
21+
cd ./source_third_party/khronos/vulkan/
22+
git checkout v1.4.359
23+
popd
24+
```
25+
26+
Updating Khronos Vulkan utilities library, e.g.:
27+
28+
```sh
29+
pushd .
30+
cd ./source_third_party/khronos/vulkan-utilities/
31+
git checkout v1.4.359
32+
popd
33+
```
34+
35+
### Updating generated code
36+
37+
After you have updated the Khronos Vulkan headers, which includes the
38+
machine-readable XML, you can regenerate the auto-generated common code:
39+
40+
```sh
41+
python3 ./generator/generate_vulkan_common.py
42+
```
43+
44+
### Committing your changes
45+
46+
All three of these changes need to land at the same time to avoid runtime
47+
errors caused by any mismatches or unknown structures.
48+
49+
For maintainers updating GitHub, ensure you commit all three together when
50+
raising a new PR to update Vulkan.
51+
52+
## Updating existing layers
53+
54+
When updating to a newer Vulkan version, existing layers might need to be
55+
updated.
56+
57+
We recommend layers use a forwarding pattern, which returns Vulkan API handles
58+
from the layer below to the application. This means that any new entrypoints
59+
will see a valid handle, and will function as expected if a layer does not
60+
intercept them. It is common that this style of layer needs no updates, unless
61+
a new API function needs to be explicitly processed to implement the desired
62+
functionality in the layer itself.
63+
64+
For maintainers updating GitHub, we usually commit layer updates to support new
65+
API entry points as per-layer commits, separately from the triggering Vulkan
66+
API update. This makes patch sets smaller and easier to review.
67+
68+
- - -
69+
70+
_Copyright © 2026, Arm Limited and contributors._

0 commit comments

Comments
 (0)