vkmtl

vkmtl is an experimental Zig graphics library that chooses the best native graphics backend for the current platform and exposes one small abstraction layer to applications. Version 0.1.0 establishes the first portable source compatibility baseline.

The intended default backend selection is:

• Apple platforms: Metal
• Other desktop platforms: Vulkan

The repository now uses backend modules for Vulkan and Metal behind public runtime wrappers. Examples live under examples/ and use the vkmtl API instead of calling Vulkan or Metal directly.

Windowed work uses WindowContext. Compute, transfer, ray tracing, resource work, and texture-backed offscreen rendering that do not need presentation can use HeadlessContext; it creates no window, surface, swapchain, or drawable.

Shader authoring uses Slang. Applications embed Slang source and declare shader usage through Device; zig build precompiles matching SPIR-V, MSL, and reflection JSON into the executable. Runtime consumes those embedded blobs directly from memory; inspectable build artifacts are installed under zig-out/shaders. The public API should only expose vkmtl concepts, not raw Vulkan or Metal handles except through explicit debug/native-handle escape hatches.

Documentation

• Docs index: map of the documentation set.
• Developer docs: current contract and planning sources of truth.
• Public API policy: API admission, v0.1.x compatibility, package, toolchain, and release gates.
• Changelog: user-visible release history.
• Roadmap: current priorities and completion gates.
• Native semantic coverage: Metal/Vulkan lowering status, unsupported semantics, and evidence gaps.
• Architecture: module boundaries, ownership, backend lowering, shaders, headless execution, and presentation.
• API migration: updating callers from older namespaces, owners, and package integration.
• Validation: required backend, host, package, physical GPU, pixel, and release evidence.
• Core API zh_CN: current public API surface in Chinese.
• Features and limits zh_CN: capability and limit interpretation in Chinese.
• Quick Start zh_CN: current usage path in Chinese.
• Diagnostics zh_CN: capture, profiling, and issue-report guidance in Chinese.
• Validation zh_CN: Vulkan and Metal native API validation setup in Chinese.
• Core API en_US: current public API surface in English.
• Features and limits en_US: capability and limit interpretation in English.
• Quick Start en_US: current usage path in English.
• Diagnostics en_US: capture, profiling, and issue-report guidance in English.
• Validation en_US: Vulkan and Metal native API validation setup in English.
• Development history: compact Period 1-56, post-Period-56 outcomes, and release evidence ledger.

Package And Compatibility

v0.1.x preserves the documented portable Zig source API. Intentional portable source breaks require v0.2.0 or later and migration guidance. This promise does not include a stable binary ABI, the layout of opaque _state storage, raw native-handle values, or backend-native escape hatches. The supported toolchain for this line is Zig 0.16.0.

The package exports one supported module named vkmtl. Applications that use runtime shader declarations provide a consumer-owned build-time shader manifest:

const vkmtl_dep = b.dependency("vkmtl", .{
    .target = target,
    .optimize = optimize,
    .shader_manifest = b.path("shaders/manifest.json"),
});

exe.root_module.addImport("vkmtl", vkmtl_dep.module("vkmtl"));

Schema version 1 remains accepted with render_shaders, compute_shaders, and ray_tracing_shaders. Schema version 2 adds tessellation_shaders and mesh_shaders. The manifest must be a source-backed LazyPath; shader source paths are relative to it and stay inside its logical package root. The dependency tracks those sources plus Slang include/import depfiles and embeds their SPIR-V, MSL, and reflection blobs; runtime code does not launch slangc or write a shader cache. See the compatibility notes for the manifest contract.

Feature availability remains capability-driven: query the selected device rather than inferring support from its platform. Planning-only or typed-unsupported paths are not executable feature claims.

Examples

Examples belong under examples/.

Ordinary example code should not use raw Vulkan or Metal calls. Explicitly named native/interop samples may create the external object being imported, but all vkmtl-side execution must use the public API.

The voxel-world example includes an optional hardware-RT PTGI lane selected with VKMTL_VOXEL_RT=auto|off|required. It uses one stochastic diffuse path per covered opaque pixel per frame, with up to three sequential cosine-weighted segments and independent sun/moon next-event estimation at every hit. Temporal accumulation and four a-trous passes reconstruct that sample before an independently authored fixed presentation profile. The native pipeline still has recursion depth 1 because ray generation issues the segments sequentially; the water reflection remains one unfiltered specular segment. Frame data receives nonzero TLAS x/z bounds only after the complete contiguous profile square has been published; sparse bootstrap or moving subsets use zero extent and cannot sample the diffuse-miss environment. With complete bounds, the path must escape above the terrain top before a horizontal edge, and the same proof gates the traced-edge environment mix. Its current default view is a 13 x 13, 169-chunk neighborhood within the complete bounded 17 x 17 RT limit, and secondary hits use the CPU terrain sampler's exact material columns. CPU chunk meshing runs through a bounded example-private background worker while GPU upload and acceleration-structure work remain on the render thread. Metal has physical API Validation execution for the material-bound route; Vulkan currently has build/test/compile validation only, so no physical Vulkan PTGI result is claimed. SEUS PTGI E12 was a visual-strategy reference, not copied source, constants, assets, or a pixel-identity target. Its default explicit reflection/diffuse chain is not a three-bounce prescription; the current three-segment PTGI path is a clean-room experimental enhancement.

Run Examples

zig build
zig build run-api-guard
zig build run-triangle
zig build run-offscreen-texture
zig build run-rainbow-cube
zig build run-voxel-world
zig build run-transfer-readback
zig build run-compute-readback
zig build run-external-import
zig build run-capability-dump
zig build run-profiling-plan
zig build run-validation-plan
zig build run-pixel-regression
zig build run-gpu-soak -- --iterations=120
zig build run-release-readiness

On macOS, .auto selects Metal when available. Vulkan can be forced for backend debugging:

zig build run-triangle -Dvulkan
zig build run-compute-readback -Dvulkan

The transfer, compute, and Metal external-import readback examples are genuinely headless and do not initialize or link GLFW.

See Configuration zh_CN or Configuration en_US for backend overrides, macOS Vulkan paths, and Slang precompile setup.

References

• https://github.com/HissingRat/zig-glfw
• https://github.com/andrewrk/zig-vulkan-triangle
• https://github.com/Snektron/vulkan-zig
• https://www.glfw.org/