docs: explain Vulkan source boundaries and helper file purposes

.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
 

README.md

@@ -239,3 +239,25 @@ 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 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).

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

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

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

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

ergonomic/allocator_test.v

@@ -1,3 +1,4 @@
+// Checks optional allocation callbacks and copying of their structure.
 module ergonomic
 
 import antono2.vulkan as vk

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

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

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

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

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

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

ergonomic/presentation_test.v

@@ -1,3 +1,4 @@
+// Checks format, presentation-mode, extent, and swapchain option selection.
 module ergonomic
 
 import antono2.vulkan as vk

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

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

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

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

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 _

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 {