main a5d7671

purego-vulkan

Linux-first Vulkan bindings for Go without cgo.

purego-vulkan loads the system Vulkan loader (libvulkan.so.1) through bnema.dev/purego and generates its raw Vulkan API surface from the pinned Khronos registry at registry/vk.xml.

The package is intentionally low-level. It exposes Vulkan ABI types, constants, command signatures, result helpers, and explicit global/instance/device dispatch tables for compositor and renderer code that owns its rendering architecture.

Status

Early v0.x implementation. The committed generated package uses the wsi coverage profile: CPU-visible buffer uploads, memory-property queries, buffer/image copies, pipeline barriers, graphics pipeline creation/destruction, draw commands, dynamic rendering, Linux surface/swapchain bindings, and image readback commands are covered. Other platforms, high-level rendering helpers, swapchain management policy, and scene abstractions are out of scope for this milestone.

Usage

if err := vulkan.Init(); err != nil {
    return err
}

gd := vulkan.Global()
var version uint32
if gd.HasEnumerateInstanceVersion() {
    if err := vulkan.Check(gd.EnumerateInstanceVersion(&version)); err != nil {
        return err
    }
    fmt.Println(vulkan.FormatVersion(version))
}

Use LoadInstanceDispatch(instance) and LoadDeviceDispatch(instanceDispatch, device) after creating Vulkan handles. Dispatch commands are pointer-receiver methods; use HasX() (for example, dd.HasGetMemoryFdKHR()) before invoking optional commands. Unavailable commands return false from HasX(). Package-level VkXxx function variables remain available for compatibility.

Run the smoke example on a Vulkan-capable Linux machine:

go run ./examples/enumerate

The example prints the loader version, compositor-critical extension availability, and physical device names.

Development

Stable commands:

make generate
make test
make check

make check runs generation, tests, and git diff --exit-code to ensure generated files are fresh.

Optional hardware probe (DMA-BUF image export and timeline semaphore FD export on real GPUs):

PUREGO_VULKAN_HW_PROBE=1 PUREGO_VULKAN_REQUIRE_POSITIVE=1 go test ./integration -run TestHardwareDMABUFExport -v -count=1

Without PUREGO_VULKAN_REQUIRE_POSITIVE=1, a machine with no capable device skips with UNSUPPORTED.

The development target is raw Vulkan binding coverage, not framework code. Keep upload orchestration, swapchain ownership, pipeline policy, render-target ownership, and command-buffer recording in the consumer; this module supplies the low-level Vulkan commands and structs needed for CPU-visible staging/upload buffers, buffer/image copies, graphics pipelines, draw calls, dynamic rendering, and Linux WSI.

Coverage profiles:

go run ./cmd/vulkangen --profile renderer  # renderer-only subset
go run ./cmd/vulkangen --profile wsi       # default committed profile
go run ./cmd/vulkangen --profile complete  # broad pinned-registry audit profile

See docs/binding-coverage.md for current registry coverage counts and intentional exclusions.

Generated files

Generated files are committed. To update them, modify cmd/vulkangen, registry/vk.xml, or overrides, then run:

go generate ./...
go test ./...
git diff --exit-code

Consumer integration

go get bnema.dev/purego-vulkan@latest

To work on the bindings and a consumer together, use a Go workspace (go work init . ../purego-vulkan) instead of a replace directive. Rendering policy, image import and presentation belong in the consumer; do not copy generated files into it.

See docs/design-notes.md for dispatch design, selected extensions, exclusions, and the consumer handoff checklist.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 3

Tags 10

↑↓ moveenter openesc close