From 23a063f5eaeee4af72bf2b6ad08f3997ddb04505 Mon Sep 17 00:00:00 2001 From: Anton Oreskin Date: Wed, 7 Oct 2026 10:59:38 +0200 Subject: [PATCH 1/2] docs: explain Vulkan source boundaries and helper file purposes --- .github/scripts/setup-vulkan-ci.sh | 1 + README.md | 18 ++++++++++++++++++ c/volk.c.v | 2 ++ ci/bundled_header_smoke/main.v | 2 ++ ci/platform_xlib/main.v | 1 + ergonomic/allocator.v | 2 ++ ergonomic/allocator_test.v | 1 + ergonomic/configuration.v | 2 ++ ergonomic/configuration_test.v | 1 + ergonomic/discovery.v | 2 ++ ergonomic/ergonomic.v | 2 ++ ergonomic/ergonomic_test.v | 1 + ergonomic/presentation.v | 2 ++ ergonomic/presentation_test.v | 1 + ergonomic/resources.v | 2 ++ ergonomic/resources_test.v | 1 + examples/ergonomic_lifecycle/main.v | 2 ++ loader.v | 2 ++ 18 files changed, 45 insertions(+) diff --git a/.github/scripts/setup-vulkan-ci.sh b/.github/scripts/setup-vulkan-ci.sh index 2ce7d47..15ca452 100644 --- a/.github/scripts/setup-vulkan-ci.sh +++ b/.github/scripts/setup-vulkan-ci.sh @@ -1,4 +1,5 @@ #!/usr/bin/env bash +# Prepares Vulkan SDK and software-driver artifacts for CI on supported hosts. set -euo pipefail diff --git a/README.md b/README.md index 90e4442..51af6f7 100644 --- a/README.md +++ b/README.md @@ -239,3 +239,21 @@ where they explain compatibility. - [Jalon Solov (@JalonSolov)](https://github.com/JalonSolov) — for quick and solid answers to obscure questions. - [Alexander Medvednikov (@medvednikov)](https://github.com/medvednikov) — for creating V and relentless productivity. - The awesome team at [V](https://vlang.io/) — for making this possible. + +## Source navigation + +`vulkan.v` and `vulkan_video.v` are registry-generated API declarations. Update their +source in [`v_vulkan_bindings`](https://github.com/antono2/v_vulkan_bindings) +rather than editing individual declarations. Keep registry versions and +regeneration changes separate from handwritten convenience-layer edits. + +[`loader.v`](loader.v) selects and initializes native dispatch; [`c/`](c/) +contains the local bridge to Volk. [`ergonomic/`](ergonomic/) contains discovery, +configuration, allocation and resource-lifetime helpers. Start with +[`examples/`](examples/) for their initialization and cleanup order, and +[`ci/`](ci/) for loader and ABI smoke checks. Vendored headers retain their +upstream license and provenance comments. + +The committed generated snapshots retain their existing headers for now; the +generator owns new purpose and regeneration comments. Refresh them through a +reviewed registry regeneration, not a manual edit of generated declarations. diff --git a/c/volk.c.v b/c/volk.c.v index 5c27455..6475fad 100644 --- a/c/volk.c.v +++ b/c/volk.c.v @@ -1,3 +1,5 @@ +// Compiles the bundled Volk implementation once for the V binding. +// Loader declarations share the pinned Vulkan headers selected here. module c #flag -I@VMODROOT/c/vendor/include diff --git a/ci/bundled_header_smoke/main.v b/ci/bundled_header_smoke/main.v index b6846e7..fd7231d 100644 --- a/ci/bundled_header_smoke/main.v +++ b/ci/bundled_header_smoke/main.v @@ -1,3 +1,5 @@ +// Checks that the module compiles against its bundled Vulkan headers. +// Exercises representative declarations without requiring device creation. module main import antono2.vulkan as vk diff --git a/ci/platform_xlib/main.v b/ci/platform_xlib/main.v index 916daf4..0d41e03 100644 --- a/ci/platform_xlib/main.v +++ b/ci/platform_xlib/main.v @@ -1,3 +1,4 @@ +// Compile probe for Vulkan Xlib extension types enabled by the platform flag. module main import antono2.vulkan as vk diff --git a/ergonomic/allocator.v b/ergonomic/allocator.v index 7ae1e15..cfb714e 100644 --- a/ergonomic/allocator.v +++ b/ergonomic/allocator.v @@ -1,3 +1,5 @@ +// Retains optional host allocation callbacks for owned Vulkan resources. +// Copies the callback structure so cleanup uses the same allocator configuration. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/allocator_test.v b/ergonomic/allocator_test.v index 3758f9f..6471641 100644 --- a/ergonomic/allocator_test.v +++ b/ergonomic/allocator_test.v @@ -1,3 +1,4 @@ +// Checks optional allocation callbacks and copying of their structure. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/configuration.v b/ergonomic/configuration.v index 2d29735..ddb84e6 100644 --- a/ergonomic/configuration.v +++ b/ergonomic/configuration.v @@ -1,3 +1,5 @@ +// Builds validated instance and device creation options. +// Plans queue requests and checks requested extension/layer names before Vulkan calls. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/configuration_test.v b/ergonomic/configuration_test.v index 8f1ee09..1b887f4 100644 --- a/ergonomic/configuration_test.v +++ b/ergonomic/configuration_test.v @@ -1,3 +1,4 @@ +// Checks option validation, extension names, and device queue planning without a GPU. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/discovery.v b/ergonomic/discovery.v index edaa86d..17f4bdf 100644 --- a/ergonomic/discovery.v +++ b/ergonomic/discovery.v @@ -1,3 +1,5 @@ +// Enumerates instance/device capabilities into V-owned descriptions. +// Provides extension, layer, and queue-family selection support. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/ergonomic.v b/ergonomic/ergonomic.v index 984b94a..108707e 100644 --- a/ergonomic/ergonomic.v +++ b/ergonomic/ergonomic.v @@ -1,3 +1,5 @@ +// Opt-in owned Vulkan handles, result errors, and lifecycle helpers. +// Explicit close methods release resources; parent objects must outlive their children. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/ergonomic_test.v b/ergonomic/ergonomic_test.v index 9692cd2..10eb63c 100644 --- a/ergonomic/ergonomic_test.v +++ b/ergonomic/ergonomic_test.v @@ -1,3 +1,4 @@ +// Checks result handling, queue selection, and lifecycle validation before driver calls. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/presentation.v b/ergonomic/presentation.v index 7b2fe50..e165c1c 100644 --- a/ergonomic/presentation.v +++ b/ergonomic/presentation.v @@ -1,3 +1,5 @@ +// Queries surface support and selects presentation settings. +// Wraps swapchain-related resources while retaining explicit Vulkan lifetime rules. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/presentation_test.v b/ergonomic/presentation_test.v index 2d65f7f..1fbe604 100644 --- a/ergonomic/presentation_test.v +++ b/ergonomic/presentation_test.v @@ -1,3 +1,4 @@ +// Checks format, presentation-mode, extent, and swapchain option selection. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/resources.v b/ergonomic/resources.v index 001e0b3..36edf05 100644 --- a/ergonomic/resources.v +++ b/ergonomic/resources.v @@ -1,3 +1,5 @@ +// Provides checked mapped-buffer access and owned shader/resource helpers. +// Validates ranges and input data before invoking the Vulkan driver. module ergonomic import antono2.vulkan as vk diff --git a/ergonomic/resources_test.v b/ergonomic/resources_test.v index 182675b..5d6ed1c 100644 --- a/ergonomic/resources_test.v +++ b/ergonomic/resources_test.v @@ -1,3 +1,4 @@ +// Checks buffer ranges, coherent writes, shader validation, and cleared-resource cleanup. module ergonomic import antono2.vulkan as vk diff --git a/examples/ergonomic_lifecycle/main.v b/examples/ergonomic_lifecycle/main.v index be9ce03..7c5ffb0 100644 --- a/examples/ergonomic_lifecycle/main.v +++ b/examples/ergonomic_lifecycle/main.v @@ -1,3 +1,5 @@ +// Exercises the opt-in resource lifecycle API on a real Vulkan device. +// A software Vulkan implementation can be used for headless validation. module main import antono2.vulkan as vk diff --git a/loader.v b/loader.v index 278b63a..1e0d801 100644 --- a/loader.v +++ b/loader.v @@ -1,3 +1,5 @@ +// Initializes Volk and loads instance/device command tables for raw Vulkan calls. +// Call the appropriate loader step before using commands for each handle level. module vulkan fn C.v_vulkan_initialize_loader() Result From 332149db0a247dd2c67db1eb1ad475a36862a20b Mon Sep 17 00:00:00 2001 From: Anton Oreskin Date: Wed, 7 Oct 2026 11:40:29 +0200 Subject: [PATCH 2/2] docs: regenerate Vulkan binding introductions without API changes --- README.md | 10 +++++++--- vulkan.v | 3 +++ vulkan_video.v | 3 +++ 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 51af6f7..235c748 100644 --- a/README.md +++ b/README.md @@ -254,6 +254,10 @@ configuration, allocation and resource-lifetime helpers. Start with [`ci/`](ci/) for loader and ABI smoke checks. Vendored headers retain their upstream license and provenance comments. -The committed generated snapshots retain their existing headers for now; the -generator owns new purpose and regeneration comments. Refresh them through a -reviewed registry regeneration, not a manual edit of generated declarations. +The generator owns the purpose and regeneration comments in both generated +files. These introductions were regenerated from Vulkan-Docs tag `v1.4.365` +(commit `8c9361ba8180c1f4164c0bf79de2f6e817770b0d`), with all declarations +verified unchanged. Select Vulkan-Docs using this module's `VERSION`; the +generator repository's historical default snapshot may be older. Despite its +name, `REGISTRY_COMMIT` pins **Vulkan-Headers**, not Vulkan-Docs. Keep that C-header +pin and `VOLK_COMMIT` aligned with the inputs described in [the vendor guide](c/vendor/README.md). diff --git a/vulkan.v b/vulkan.v index eaa8c71..ae7d8ce 100644 --- a/vulkan.v +++ b/vulkan.v @@ -22,6 +22,9 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +// Registry-generated Vulkan declarations; native handles follow Vulkan lifetime rules. +// Regenerate in antono2/v_vulkan_bindings with scripts/generate.sh (or .ps1). +// Do not edit declarations here; change src/vgenerator.py and the registry input. module vulkan import vulkan.c as _ diff --git a/vulkan_video.v b/vulkan_video.v index 6f77acc..8f1eeac 100644 --- a/vulkan_video.v +++ b/vulkan_video.v @@ -22,6 +22,9 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +// Registry-generated Vulkan declarations; native handles follow Vulkan lifetime rules. +// Regenerate in antono2/v_vulkan_bindings with scripts/generate.sh (or .ps1). +// Do not edit declarations here; change src/vgenerator.py and the registry input. module vulkan pub fn make_video_std_version(major u32, minor u32, patch u32) u32 {