docs: publish canonical OpenCL documentation and file introductions

GENERATOR_COMMIT

@@ -1 +1 @@
-d15925cd24ebcc93532771b7e5b1b793371fc853
+3af612046afc12c82626a18e575dc59763285a63

README.md

@@ -317,3 +317,12 @@ The publisher fills this README's package metadata from `VERSION` and checks
 documentation drift together with the other distribution files. The primary
 installation command remains unpinned; release tags are an optional choice
 for reproducible builds.
+
+## Source navigation
+
+`opencl.v` is generated; its introduction and declarations belong to the
+[canonical generator](https://github.com/antono2/v_opencl_bindings).
+Handwritten discovery, ownership, event, image and interoperability files have
+purpose comments describing their role. Make shared source and example changes
+in that repository, then run its publisher; direct edits here can be overwritten.
+Keep vendored OpenCL headers and their upstream license notices intact.

abi/main.c.v

@@ -1,3 +1,4 @@
+// Compiles representative OpenCL declarations to check C/V ABI compatibility.
 module main
 
 import antono2.opencl as cl

capabilities.v

@@ -1,3 +1,4 @@
+// Collects optional device extensions and identity information for capability-gated operations.
 module opencl
 
 // DeviceCapabilities is a snapshot of optional extension support advertised by

convenience.v

@@ -1,3 +1,4 @@
+// Converts OpenCL status codes to contextual V errors and copies platform/device query results.
 module opencl
 
 // OpenCLError preserves the native OpenCL status code and the operation that failed.

convenience_test.v

@@ -1,3 +1,4 @@
+// Checks typed errors, resource reference counts, ownership, and convenience operations.
 module main
 
 import antono2.opencl as cl
@@ -104,8 +105,7 @@ fn test_clone_ref_retains_independently_owned_native_references() ! {
 	assert memory_reference_count(buffer.handle)! == buffer_refs
 
 	mut program := cl.build_source_program(context, device,
-		'__kernel void retain_test(__global uint *values) { values[get_global_id(0)] += 1; }',
-		'')!
+		'__kernel void retain_test(__global uint *values) { values[get_global_id(0)] += 1; }', '')!
 	program_refs := program_reference_count(program.handle)!
 	mut retained_program := program.clone_ref()!
 	assert program_reference_count(program.handle)! == program_refs + 1
@@ -119,13 +119,20 @@ fn test_clone_ref_retains_independently_owned_native_references() ! {
 	retained_kernel.close()!
 	assert kernel_reference_count(kernel.handle)! == kernel_refs
 
-	mut event := queue.marker([]cl.Event{})!
+	// A queued marker may lose runtime-owned references as it completes. Use an
+	// unqueued user event so these counts measure only our retain/release calls.
+	mut event_status := cl.ErrorCode(0)
+	mut event := &cl.OwnedEvent{
+		handle: cl.create_user_event(context.handle, &event_status)
+	}
+	cl.check(event_status, 'create user event for reference-count test')!
 	event_refs := event_reference_count(event.handle)!
 	mut retained_event := event.clone_ref()!
 	assert event_reference_count(event.handle)! == event_refs + 1
 	retained_event.close()!
 	assert event_reference_count(event.handle)! == event_refs
 
+	cl.check(cl.set_user_event_status(event.handle, cl.complete), 'complete reference-count event')!
 	event.close()!
 	kernel.close()!
 	program.close()!

event.v

@@ -1,3 +1,5 @@
+// Owns OpenCL event references and exposes completion and profiling queries.
+// Close each owned reference after dependent work no longer needs it.
 module opencl
 
 // OwnedEvent owns one OpenCL event reference. The command queue and context

examples/image_svm/main.v

@@ -1,3 +1,4 @@
+// Demonstrates typed images and shared virtual memory where the device supports them.
 module main
 
 import antono2.opencl as cl

examples/vector_add/main.v

@@ -1,3 +1,4 @@
+// Builds and executes a vector-add kernel using owned OpenCL resource helpers.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/compile_shaders.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
+# Compiles the particle and trail GLSL shaders to the SPIR-V files used by the demo.
 set -eu
 
 : "${VULKAN_SDK:?Set VULKAN_SDK to the Vulkan SDK directory}"

examples/vulkan_particles/compute.v

@@ -1,3 +1,5 @@
+// Owns OpenCL particle kernels and their compute buffers.
+// Supports reset, simulation updates, and readback for staged presentation.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/fd_abi.v

@@ -1,3 +1,4 @@
+// Adapts Vulkan external-memory and semaphore file-descriptor output pointers to the C ABI.
 module main
 
 import antono2.vulkan as vk

examples/vulkan_particles/frame_resources.v

@@ -1,3 +1,5 @@
+// Owns per-frame Vulkan command and synchronization resources for particle drawing.
+// Coordinates graphics completion with external compute handoffs.
 module main
 
 import antono2.vulkan as vk

examples/vulkan_particles/interop_probe.v

@@ -1,3 +1,5 @@
+// Checks matching device UUIDs and external-memory/semaphore capabilities.
+// Reports whether zero-copy presentation is available before choosing the runtime path.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/interop_probe_test.v

@@ -1,3 +1,4 @@
+// Checks complete extension-token matching and device UUID comparisons.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/live_sync.v

@@ -1,3 +1,5 @@
+// Coordinates live OpenCL/Vulkan access through imported external semaphores.
+// Pairs compute acquire/release operations with graphics ownership handoffs.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/main.v

@@ -1,3 +1,4 @@
+// Particle-demo entry point selecting headless, staged, or zero-copy execution from options.
 module main
 
 import os

examples/vulkan_particles/options.v

@@ -1,3 +1,5 @@
+// Parses particle-demo environment settings and command-line overrides.
+// Rejects incompatible runtime modes before allocating device resources.
 module main
 
 import os

examples/vulkan_particles/options_test.v

@@ -1,3 +1,4 @@
+// Checks option precedence, invalid combinations, and cursor-to-particle coordinate mapping.
 module main
 
 fn test_command_line_options_override_defaults() {

examples/vulkan_particles/particle_buffer.v

@@ -1,3 +1,5 @@
+// Creates particle buffers for staged uploads or shared external-memory access.
+// Owns the Vulkan allocation and any OpenCL import until explicit destruction.
 module main
 
 import antono2.opencl as cl

examples/vulkan_particles/particles.cl

@@ -1,3 +1,4 @@
+// OpenCL kernels for deterministic particle initialization and time-step updates.
 typedef struct {
 	float4 position;
 	float4 velocity;

examples/vulkan_particles/particles.frag

@@ -1,3 +1,4 @@
+// Shades particle fragments using interpolated particle color.
 #version 450
 
 layout(location = 0) in vec3 color;

examples/vulkan_particles/particles.vert

@@ -1,3 +1,4 @@
+// Transforms particle positions and supplies per-particle color to the fragment stage.
 #version 450
 
 layout(location = 0) in vec4 in_position;

examples/vulkan_particles/pipeline.v

@@ -1,3 +1,4 @@
+// Creates shader modules and Vulkan pipelines for particle and trail rendering.
 module main
 
 import antono2.vulkan as vk

examples/vulkan_particles/shader_test.v

@@ -1,3 +1,4 @@
+// Checks committed shader binaries for valid SPIR-V structure using available tooling.
 module main
 
 import os

examples/vulkan_particles/swapchain.v

@@ -1,3 +1,5 @@
+// Creates presentation images, views, and framebuffers for the particle window.
+// Queries surface support and destroys the associated swapchain resources.
 module main
 
 import antono2.glfw

examples/vulkan_particles/trails.frag

@@ -1,3 +1,4 @@
+// Shades trail fragments using the interpolated trail color.
 #version 450
 
 layout(location = 0) in vec3 color;

examples/vulkan_particles/trails.vert

@@ -1,3 +1,4 @@
+// Transforms trail vertices for the particle demo's history rendering.
 #version 450
 
 layout(location = 0) in vec4 in_position;

examples/vulkan_particles/window_smoke.v

@@ -1,3 +1,5 @@
+// Runs the GLFW/Vulkan particle presentation loop with staged or shared compute buffers.
+// Maps pointer input into simulation coordinates and selects a graphics/present queue.
 module main
 
 import antono2.glfw

examples/vulkan_particles/zero_copy_smoke.v

@@ -1,3 +1,4 @@
+// Probes external-memory and semaphore sharing between UUID-matched OpenCL/Vulkan devices.
 module main
 
 import antono2.opencl as cl

external_interop.v

@@ -1,3 +1,5 @@
+// Loads optional external-memory and semaphore entry points for a selected platform.
+// Imports native handles and coordinates ownership across API boundaries.
 module opencl
 
 $if windows {

image.v

@@ -1,3 +1,4 @@
+// Typed image and sampler ownership with checked dimensions, formats, and transfers.
 module opencl
 
 // Image2D owns a typed two-dimensional OpenCL image. T represents one complete

opencl.v

@@ -1,4 +1,6 @@
 // Code generated from the Khronos OpenCL XML API Registry. DO NOT EDIT.
+// Raw OpenCL constants, types, and entry points; resource lifetimes follow the C API.
+// Regenerate in antono2/v_opencl_bindings with python3 src/main.py.
 module opencl
 
 #flag linux -lOpenCL

ownership.v

@@ -1,3 +1,5 @@
+// Owned context, queue, and buffer helpers with explicit retain/close operations.
+// Raw handles remain available for operations outside the convenience layer.
 module opencl
 
 // OwnedContext owns one reference to an OpenCL context. Call close when done.

program.v

@@ -1,3 +1,4 @@
+// Builds source programs with diagnostic logs and owns kernels and their arguments.
 module opencl
 
 // ProgramBuildError includes the compiler log returned for the selected device.

svm.v

@@ -1,3 +1,4 @@
+// Capability-gated shared virtual memory allocation, mapping, and kernel argument helpers.
 module opencl
 
 fn platform_svm_alloc(context Context, flags SvmMemFlags, size usize, alignment u32) voidptr {

test/pointer_abi_shim.c

@@ -1,3 +1,4 @@
+// C-side instrumentation for null pointers, handle arrays, and transfer callback ABI tests.
 #include <CL/opencl.h>
 #include <stddef.h>
 #include <stdint.h>

test/pointer_abi_test.v

@@ -1,3 +1,4 @@
+// Checks the exact pointers passed from V wrappers to instrumented C entry points.
 module main
 
 import antono2.opencl as cl