vulkan

package
v0.26.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2026 License: MIT Imports: 17 Imported by: 1

Documentation

Overview

Package vulkan provides Pure Go Vulkan backend for the HAL.

This backend uses goffi for cross-platform Vulkan API calls, requiring no CGO. Function pointers are loaded dynamically from vulkan-1.dll (Windows), libvulkan.so.1 (Linux), or MoltenVK (macOS).

Architecture

The backend follows wgpu-hal patterns:

  • Instance: VkInstance wrapper with extension loading
  • Adapter: VkPhysicalDevice enumeration and capabilities
  • Device: VkDevice with queues and memory allocator
  • Queue: Command submission and synchronization
  • Resources: Buffers, textures, pipelines with Vulkan objects

Memory Management

Unlike OpenGL, Vulkan requires explicit memory allocation. This backend implements a pool-based memory allocator similar to gpu-allocator.

Platform Support

  • Windows: vulkan-1.dll + VK_KHR_win32_surface
  • Linux: libvulkan.so.1 + VK_KHR_xlib_surface/VK_KHR_xcb_surface (planned)
  • macOS: MoltenVK + VK_EXT_metal_surface (planned)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Adapter 

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter implements hal.Adapter for Vulkan.

func (*Adapter) Destroy 

func (a *Adapter) Destroy()

Destroy releases the adapter.

func (*Adapter) Open 

func (a *Adapter) Open(features gputypes.Features, limits gputypes.Limits) (hal.OpenDevice, error)

Open creates a logical device with the requested features and limits.

func (*Adapter) SurfaceCapabilities 

func (a *Adapter) SurfaceCapabilities(surface hal.Surface) *hal.SurfaceCapabilities

SurfaceCapabilities returns surface capabilities.

func (*Adapter) TextureFormatCapabilities 

func (a *Adapter) TextureFormatCapabilities(format gputypes.TextureFormat) hal.TextureFormatCapabilities

TextureFormatCapabilities returns capabilities for a texture format.

type Backend 

type Backend struct{}

Backend implements hal.Backend for Vulkan.

func (Backend) CreateInstance 

func (Backend) CreateInstance(desc *hal.InstanceDescriptor) (hal.Instance, error)

CreateInstance creates a new Vulkan instance.

func (Backend) Variant 

func (Backend) Variant() gputypes.Backend

Variant returns the backend type identifier.

type BindGroup 

type BindGroup struct {
	// contains filtered or unexported fields
}

BindGroup implements hal.BindGroup for Vulkan.

func (*BindGroup) Destroy 

func (g *BindGroup) Destroy()

Destroy releases the bind group.

func (*BindGroup) Handle 

func (g *BindGroup) Handle() vk.DescriptorSet

Handle returns the VkDescriptorSet handle.

type BindGroupLayout 

type BindGroupLayout struct {
	// contains filtered or unexported fields
}

BindGroupLayout implements hal.BindGroupLayout for Vulkan.

func (*BindGroupLayout) Counts 

func (l *BindGroupLayout) Counts() DescriptorCounts

Counts returns the descriptor counts for this layout.

func (*BindGroupLayout) Destroy 

func (l *BindGroupLayout) Destroy()

Destroy releases the bind group layout.

func (*BindGroupLayout) Handle 

func (l *BindGroupLayout) Handle() vk.DescriptorSetLayout

Handle returns the VkDescriptorSetLayout handle.

type Buffer 

type Buffer struct {
	// contains filtered or unexported fields
}

Buffer implements hal.Buffer for Vulkan.

func (*Buffer) Destroy 

func (b *Buffer) Destroy()

Destroy releases the buffer.

func (*Buffer) Handle 

func (b *Buffer) Handle() vk.Buffer

Handle returns the VkBuffer handle.

func (*Buffer) NativeHandle added in v0.12.0 

func (b *Buffer) NativeHandle() uintptr

NativeHandle returns the raw VkBuffer handle as uintptr.

func (*Buffer) Size 

func (b *Buffer) Size() uint64

Size returns the buffer size in bytes.

type CommandBuffer 

type CommandBuffer struct {
	// contains filtered or unexported fields
}

CommandBuffer holds a recorded Vulkan command buffer. Pooled via cmdBufferResultPool to avoid per-frame heap allocation (VK-PERF-004).

func (*CommandBuffer) Destroy 

func (c *CommandBuffer) Destroy()

Destroy releases the command buffer resources. Returns the struct to the pool for reuse (VK-PERF-004).

type CommandEncoder 

type CommandEncoder struct {
	// contains filtered or unexported fields
}

CommandEncoder implements hal.CommandEncoder for Vulkan.

Uses the free list pattern (Rust wgpu-hal parity): the encoder owns a VkCommandPool and manages a pool of VkCommandBuffer handles internally. BeginEncoding pops from the free list (batch-allocating if empty), EndEncoding detaches the active handle, and ResetAll recycles completed and discarded handles back to the free list with a single vkResetCommandPool.

Two ownership modes:

  • Standalone (poolManaged=false): After EndEncoding, the encoder detaches its pool to the CommandBuffer result and returns itself to encoderPool (sync.Pool for struct reuse). FreeCommandBuffer recycles the Vulkan resources. This is the default mode for user-created command encoders.
  • Pool-managed (poolManaged=true): After EndEncoding, the encoder retains ownership of its VkCommandPool. After GPU completion, ResetAll resets the pool so the encoder can be reused via the wgpu-level encoder pool. Used by pendingWrites.

Pooled via encoderPool to avoid per-frame heap allocation (VK-PERF-003).

Reference: Rust wgpu-hal vulkan/mod.rs:939-965 (struct), vulkan/command.rs:7-192 (begin/end/discard/reset_all).

func (*CommandEncoder) BeginComputePass 

func (e *CommandEncoder) BeginComputePass(desc *hal.ComputePassDescriptor) hal.ComputePassEncoder

BeginComputePass begins a compute pass. Uses sync.Pool for ComputePassEncoder reuse (VK-PERF-005).

func (*CommandEncoder) BeginEncoding 

func (e *CommandEncoder) BeginEncoding(label string) error

BeginEncoding begins command recording.

Pops a VkCommandBuffer from the free list. If the free list is empty, batch-allocates allocationGranularity (16) command buffers from the pool. This matches Rust wgpu-hal begin_encoding (vulkan/command.rs:122-151).

Returns an error if the device is nil or if Vulkan allocation/begin fails.

func (*CommandEncoder) BeginRenderPass 

func (e *CommandEncoder) BeginRenderPass(desc *hal.RenderPassDescriptor) hal.RenderPassEncoder

BeginRenderPass begins a render pass using VkRenderPass (classic Vulkan approach). This is compatible with Intel drivers that don't properly support dynamic rendering. Supports MSAA render passes with resolve targets and depth/stencil attachments. Uses sync.Pool for RenderPassEncoder reuse (VK-PERF-006).

func (*CommandEncoder) ClearBuffer 

func (e *CommandEncoder) ClearBuffer(buffer hal.Buffer, offset, size uint64)

ClearBuffer clears a buffer region to zero.

func (*CommandEncoder) CopyBufferToBuffer 

func (e *CommandEncoder) CopyBufferToBuffer(src, dst hal.Buffer, regions []hal.BufferCopy)

CopyBufferToBuffer copies data between buffers.

func (*CommandEncoder) CopyBufferToTexture 

func (e *CommandEncoder) CopyBufferToTexture(src hal.Buffer, dst hal.Texture, regions []hal.BufferTextureCopy)

CopyBufferToTexture copies data from a buffer to a texture.

func (*CommandEncoder) CopyTextureToBuffer 

func (e *CommandEncoder) CopyTextureToBuffer(src hal.Texture, dst hal.Buffer, regions []hal.BufferTextureCopy)

CopyTextureToBuffer copies data from a texture to a buffer.

func (*CommandEncoder) CopyTextureToTexture 

func (e *CommandEncoder) CopyTextureToTexture(src, dst hal.Texture, regions []hal.TextureCopy)

CopyTextureToTexture copies data between textures.

func (*CommandEncoder) Destroy added in v0.23.4 

func (e *CommandEncoder) Destroy()

Destroy releases the VkCommandPool owned by this encoder. Destroying the pool implicitly frees all command buffers allocated from it. Must be called when the encoder is permanently retired (e.g., device shutdown).

func (*CommandEncoder) DiscardEncoding 

func (e *CommandEncoder) DiscardEncoding()

DiscardEncoding discards the current recording without creating a command buffer. The active command buffer is moved to the discarded list for later pool reset. Rust wgpu-hal does NOT call vkEndCommandBuffer on discarded buffers — vkResetCommandPool handles them in any state (vulkan/command.rs:165-173).

In standalone mode, recycles the pool and returns the encoder struct. In pool-managed mode, retains resources for ResetAll+reuse.

func (*CommandEncoder) EndEncoding 

func (e *CommandEncoder) EndEncoding() (hal.CommandBuffer, error)

EndEncoding finishes command recording and returns a command buffer. Uses sync.Pool for CommandBuffer struct reuse (VK-PERF-004).

In standalone mode (default): detaches pool to the result and returns the encoder struct to encoderPool for reuse. In pool-managed mode: the encoder retains ownership of its VkCommandPool. After GPU completion, call ResetAll to prepare for the next BeginEncoding cycle.

Reference: Rust wgpu-hal end_encoding (vulkan/command.rs:153-163).

func (*CommandEncoder) ResetAll 

func (e *CommandEncoder) ResetAll(commandBuffers []hal.CommandBuffer)

ResetAll recycles completed command buffers and discarded buffers back to the free list, then resets the entire command pool. After this call, all buffers in the free list are in Vulkan "initial" state, ready for vkBeginCommandBuffer.

This is much cheaper than individual vkResetCommandBuffer calls (NVIDIA, ARM). Reference: Rust wgpu-hal reset_all (vulkan/command.rs:175-192).

func (*CommandEncoder) ResolveQuerySet added in v0.16.4 

func (e *CommandEncoder) ResolveQuerySet(querySet hal.QuerySet, firstQuery, queryCount uint32, destination hal.Buffer, destinationOffset uint64)

ResolveQuerySet copies query results from a query set into a destination buffer. For timestamp queries, each result is a uint64 (8 bytes). This uses vkCmdCopyQueryPoolResults under the hood.

func (*CommandEncoder) SetPoolManaged added in v0.23.4 

func (e *CommandEncoder) SetPoolManaged(managed bool)

SetPoolManaged marks this encoder as managed by the wgpu-level encoder pool. When true, EndEncoding retains ownership of the VkCommandPool instead of detaching it to the CommandBuffer result. This enables encoder reuse after ResetAll without creating new Vulkan resources.

func (*CommandEncoder) TransitionBuffers 

func (e *CommandEncoder) TransitionBuffers(barriers []hal.BufferBarrier)

TransitionBuffers transitions buffer states for synchronization.

func (*CommandEncoder) TransitionTextures 

func (e *CommandEncoder) TransitionTextures(barriers []hal.TextureBarrier)

TransitionTextures transitions texture states for synchronization.

type ComputePassEncoder 

type ComputePassEncoder struct {
	// contains filtered or unexported fields
}

ComputePassEncoder implements hal.ComputePassEncoder for Vulkan.

func (*ComputePassEncoder) Dispatch 

func (e *ComputePassEncoder) Dispatch(x, y, z uint32)

Dispatch dispatches compute work.

func (*ComputePassEncoder) DispatchIndirect 

func (e *ComputePassEncoder) DispatchIndirect(buffer hal.Buffer, offset uint64)

DispatchIndirect dispatches compute work with GPU-generated parameters.

func (*ComputePassEncoder) End 

func (e *ComputePassEncoder) End()

End finishes the compute pass. Writes end-of-pass timestamp if requested, then inserts a global memory barrier so compute shader writes are visible to subsequent commands (transfers, other dispatches, etc.). Without this barrier the GPU may reorder a CopyBufferToBuffer before the compute shader has finished writing, causing stale/zero reads. Returns the encoder to the pool for reuse (VK-PERF-005).

func (*ComputePassEncoder) SetBindGroup 

func (e *ComputePassEncoder) SetBindGroup(index uint32, group hal.BindGroup, offsets []uint32)

SetBindGroup sets a bind group.

func (*ComputePassEncoder) SetPipeline 

func (e *ComputePassEncoder) SetPipeline(pipeline hal.ComputePipeline)

SetPipeline sets the compute pipeline.

type ComputePipeline 

type ComputePipeline struct {
	// contains filtered or unexported fields
}

ComputePipeline implements hal.ComputePipeline for Vulkan.

func (*ComputePipeline) Destroy 

func (p *ComputePipeline) Destroy()

Destroy releases the compute pipeline.

type DescriptorAllocator 

type DescriptorAllocator struct {
	// contains filtered or unexported fields
}

DescriptorAllocator manages descriptor pool allocation.

Thread-safe. Uses on-demand pool growth strategy with FREE_DESCRIPTOR_SET flag for individual descriptor set freeing. Follows wgpu patterns adapted for Go.

func NewDescriptorAllocator 

func NewDescriptorAllocator(device vk.Device, cmds *vk.Commands, config DescriptorAllocatorConfig) *DescriptorAllocator

NewDescriptorAllocator creates a new descriptor allocator.

func (*DescriptorAllocator) Allocate 

func (a *DescriptorAllocator) Allocate(layout vk.DescriptorSetLayout, counts DescriptorCounts) (vk.DescriptorSet, *DescriptorPool, error)

Allocate allocates a descriptor set from the given layout.

func (*DescriptorAllocator) Destroy 

func (a *DescriptorAllocator) Destroy()

Destroy releases all descriptor pools.

func (*DescriptorAllocator) Free 

func (a *DescriptorAllocator) Free(pool *DescriptorPool, set vk.DescriptorSet) error

Free frees a descriptor set back to its pool.

func (*DescriptorAllocator) Stats 

func (a *DescriptorAllocator) Stats() (pools int, allocated, freed uint32)

Stats returns allocator statistics.

type DescriptorAllocatorConfig 

type DescriptorAllocatorConfig struct {
	// InitialPoolSize is the number of sets in the first pool.
	// Default: 64
	InitialPoolSize uint32

	// MaxPoolSize is the maximum sets per pool.
	// Default: 4096
	MaxPoolSize uint32

	// GrowthFactor is the multiplier for each new pool size.
	// Default: 2
	GrowthFactor uint32
}

DescriptorAllocatorConfig configures the descriptor allocator.

func DefaultDescriptorAllocatorConfig 

func DefaultDescriptorAllocatorConfig() DescriptorAllocatorConfig

DefaultDescriptorAllocatorConfig returns sensible defaults.

type DescriptorCounts 

type DescriptorCounts struct {
	Samplers           uint32
	SampledImages      uint32
	StorageImages      uint32
	UniformBuffers     uint32
	StorageBuffers     uint32
	UniformTexelBuffer uint32
	StorageTexelBuffer uint32
	InputAttachments   uint32
}

DescriptorCounts tracks the number of descriptors by type. Used to determine pool sizes for allocation.

func (DescriptorCounts) IsEmpty 

func (c DescriptorCounts) IsEmpty() bool

IsEmpty returns true if no descriptors are needed.

func (DescriptorCounts) Multiply 

func (c DescriptorCounts) Multiply(factor uint32) DescriptorCounts

Multiply multiplies all counts by a factor.

func (DescriptorCounts) Total 

func (c DescriptorCounts) Total() uint32

Total returns the total number of descriptors.

type DescriptorPool 

type DescriptorPool struct {
	// contains filtered or unexported fields
}

DescriptorPool wraps a VkDescriptorPool with tracking.

type Device 

type Device struct {
	// contains filtered or unexported fields
}

Device implements hal.Device for Vulkan.

func (*Device) CreateBindGroup 

func (d *Device) CreateBindGroup(desc *hal.BindGroupDescriptor) (hal.BindGroup, error)

CreateBindGroup creates a bind group.

func (*Device) CreateBindGroupLayout 

func (d *Device) CreateBindGroupLayout(desc *hal.BindGroupLayoutDescriptor) (hal.BindGroupLayout, error)

CreateBindGroupLayout creates a bind group layout.

func (*Device) CreateBuffer 

func (d *Device) CreateBuffer(desc *hal.BufferDescriptor) (hal.Buffer, error)

CreateBuffer creates a GPU buffer.

func (*Device) CreateCommandEncoder 

func (d *Device) CreateCommandEncoder(desc *hal.CommandEncoderDescriptor) (hal.CommandEncoder, error)

CreateCommandEncoder creates a command encoder with its own dedicated VkCommandPool. Command buffers are allocated on demand from the pool's internal free list (VK-CMD-001). This per-encoder pool design matches Rust wgpu-hal and eliminates races between pool reset and buffer freeing that caused "Couldn't find VkCommandBuffer Object" crashes (VK-POOL-001). Uses sync.Pool for CommandEncoder struct reuse (VK-PERF-003).

func (*Device) CreateComputePipeline 

func (d *Device) CreateComputePipeline(desc *hal.ComputePipelineDescriptor) (hal.ComputePipeline, error)

CreateComputePipeline creates a compute pipeline.

func (*Device) CreateFence 

func (d *Device) CreateFence() (hal.Fence, error)

CreateFence creates a synchronization fence.

func (*Device) CreatePipelineLayout 

func (d *Device) CreatePipelineLayout(desc *hal.PipelineLayoutDescriptor) (hal.PipelineLayout, error)

CreatePipelineLayout creates a pipeline layout.

func (*Device) CreateQuerySet added in v0.16.4 

func (d *Device) CreateQuerySet(desc *hal.QuerySetDescriptor) (hal.QuerySet, error)

CreateQuerySet creates a Vulkan query pool.

func (*Device) CreateRenderBundleEncoder added in v0.13.0 

func (d *Device) CreateRenderBundleEncoder(_ *hal.RenderBundleEncoderDescriptor) (hal.RenderBundleEncoder, error)

CreateRenderBundleEncoder creates a render bundle encoder. Each bundle gets its own dedicated VkCommandPool for secondary command buffer allocation, matching the per-encoder pool pattern (VK-POOL-001).

func (*Device) CreateRenderPipeline 

func (d *Device) CreateRenderPipeline(desc *hal.RenderPipelineDescriptor) (hal.RenderPipeline, error)

CreateRenderPipeline creates a render pipeline.

func (*Device) CreateSampler 

func (d *Device) CreateSampler(desc *hal.SamplerDescriptor) (hal.Sampler, error)

CreateSampler creates a texture sampler.

func (*Device) CreateShaderModule 

func (d *Device) CreateShaderModule(desc *hal.ShaderModuleDescriptor) (hal.ShaderModule, error)

CreateShaderModule creates a shader module.

func (*Device) CreateTexture 

func (d *Device) CreateTexture(desc *hal.TextureDescriptor) (hal.Texture, error)

CreateTexture creates a GPU texture.

func (*Device) CreateTextureView 

func (d *Device) CreateTextureView(texture hal.Texture, desc *hal.TextureViewDescriptor) (hal.TextureView, error)

CreateTextureView creates a view into a texture.

func (*Device) Destroy 

func (d *Device) Destroy()

Destroy releases the device.

func (*Device) DestroyBindGroup 

func (d *Device) DestroyBindGroup(group hal.BindGroup)

DestroyBindGroup destroys a bind group.

func (*Device) DestroyBindGroupLayout 

func (d *Device) DestroyBindGroupLayout(layout hal.BindGroupLayout)

DestroyBindGroupLayout destroys a bind group layout.

func (*Device) DestroyBuffer 

func (d *Device) DestroyBuffer(buffer hal.Buffer)

DestroyBuffer destroys a GPU buffer.

func (*Device) DestroyComputePipeline 

func (d *Device) DestroyComputePipeline(pipeline hal.ComputePipeline)

DestroyComputePipeline destroys a compute pipeline.

func (*Device) DestroyFence 

func (d *Device) DestroyFence(fence hal.Fence)

DestroyFence destroys a fence.

func (*Device) DestroyPipelineLayout 

func (d *Device) DestroyPipelineLayout(layout hal.PipelineLayout)

DestroyPipelineLayout destroys a pipeline layout.

func (*Device) DestroyQuerySet added in v0.16.4 

func (d *Device) DestroyQuerySet(querySet hal.QuerySet)

DestroyQuerySet destroys a Vulkan query set.

func (*Device) DestroyRenderBundle added in v0.13.0 

func (d *Device) DestroyRenderBundle(bundle hal.RenderBundle)

DestroyRenderBundle destroys a render bundle. Frees the secondary command buffer from its dedicated pool, then destroys the pool.

func (*Device) DestroyRenderPipeline 

func (d *Device) DestroyRenderPipeline(pipeline hal.RenderPipeline)

DestroyRenderPipeline destroys a render pipeline.

func (*Device) DestroySampler 

func (d *Device) DestroySampler(sampler hal.Sampler)

DestroySampler destroys a sampler.

func (*Device) DestroyShaderModule 

func (d *Device) DestroyShaderModule(module hal.ShaderModule)

DestroyShaderModule destroys a shader module.

func (*Device) DestroyTexture 

func (d *Device) DestroyTexture(texture hal.Texture)

DestroyTexture destroys a GPU texture.

func (*Device) DestroyTextureView 

func (d *Device) DestroyTextureView(view hal.TextureView)

DestroyTextureView destroys a texture view.

func (*Device) FreeCommandBuffer added in v0.13.0 

func (d *Device) FreeCommandBuffer(cmdBuffer hal.CommandBuffer)

FreeCommandBuffer recycles a command buffer's pool for reuse. Only call this AFTER the GPU has finished using the command buffer (after fence wait). The pool is returned to the free list and reset on next acquireAllocator. This is only called for standalone-mode encoders where the CommandBuffer carries pool ownership. Pool-managed encoders use ResetAll instead.

func (*Device) GetFenceStatus added in v0.13.0 

func (d *Device) GetFenceStatus(fence hal.Fence) (bool, error)

GetFenceStatus returns true if the fence is signaled (non-blocking). Uses vkGetFenceStatus for efficient polling without blocking.

func (*Device) GetRenderPassCache added in v0.9.3 

func (d *Device) GetRenderPassCache() *RenderPassCache

GetRenderPassCache returns the render pass cache, creating it if needed.

func (*Device) MapBuffer added in v0.25.0 

func (d *Device) MapBuffer(buffer hal.Buffer, offset, size uint64) (hal.BufferMapping, error)

MapBuffer establishes a CPU-visible mapping for the given byte range.

Vulkan maps each VkDeviceMemory block persistently at allocation time (ensureMemoryMapped in CreateBuffer). MapBuffer therefore just returns the cached pointer offset by the requested offset — no additional vkMapMemory call, no syscall overhead.

Coherency: the block may or may not be HOST_COHERENT depending on the memory type chosen by gpu_allocator. We report IsCoherent=false conservatively; the core driver is responsible for issuing Flush / Invalidate via the memory-range Vulkan APIs when needed.

func (*Device) MaxStagingBufferSize added in v0.25.3 

func (d *Device) MaxStagingBufferSize() uint64

MaxStagingBufferSize returns the maximum safe staging buffer allocation size. This is min(64MB, maxMemoryAllocationSize) from the Vulkan allocator. Used by the staging belt to cap individual staging buffers, preventing vkAllocateMemory from silently failing on oversized requests (BUG-VK-001). Implements hal.MaxStagingBufferSizer.

func (*Device) ResetCommandPool added in v0.9.3 

func (d *Device) ResetCommandPool() error

ResetCommandPool resets all recycled command pools. Call this after ensuring all submitted command buffers have completed (e.g., after WaitIdle).

func (*Device) ResetFence added in v0.13.0 

func (d *Device) ResetFence(fence hal.Fence) error

ResetFence resets a fence to the unsignaled state.

func (*Device) UnmapBuffer added in v0.25.0 

func (d *Device) UnmapBuffer(buffer hal.Buffer) error

UnmapBuffer is a no-op for Vulkan because VkDeviceMemory is persistently mapped at allocation time. A subsequent write-back flush, if needed, would be handled via vkFlushMappedMemoryRanges by a higher layer; core currently doesn't call any such hook because host-visible allocations in this implementation are coherent in practice.

func (*Device) Wait 

func (d *Device) Wait(fence hal.Fence, _ uint64, timeout time.Duration) (bool, error)

Wait waits for a fence to reach the specified value. Note: Standard Vulkan fences don't support timeline values, so value is ignored. For timeline semantics, use VK_KHR_timeline_semaphore extension.

func (*Device) WaitIdle added in v0.9.3 

func (d *Device) WaitIdle() error

WaitIdle waits for all GPU operations to complete.

type Extent3D 

type Extent3D struct {
	Width  uint32
	Height uint32
	Depth  uint32
}

Extent3D represents 3D dimensions.

type Fence 

type Fence struct {
	// contains filtered or unexported fields
}

Fence implements hal.Fence for Vulkan.

func (*Fence) Destroy 

func (f *Fence) Destroy()

Destroy releases the fence.

func (*Fence) Handle 

func (f *Fence) Handle() vk.Fence

Handle returns the VkFence handle.

type FramebufferKey added in v0.9.3 

type FramebufferKey struct {
	RenderPass  vk.RenderPass
	ColorView   vk.ImageView // MSAA color view or single-sample color view
	ResolveView vk.ImageView // Resolve target (0 if no MSAA)
	DepthView   vk.ImageView // Depth/stencil view (0 if none)
	Width       uint32
	Height      uint32
}

FramebufferKey uniquely identifies a framebuffer configuration. Supports multiple attachments for MSAA (color + resolve + depth/stencil).

type Instance 

type Instance struct {
	// contains filtered or unexported fields
}

Instance implements hal.Instance for Vulkan.

func (*Instance) CreateSurface 

func (i *Instance) CreateSurface(display, window uintptr) (hal.Surface, error)

CreateSurface creates a Vulkan surface from platform-specific handles. On Linux, it auto-detects X11 vs Wayland based on available extensions:

  • Wayland: display = wl_display*, window = wl_surface* (from libwayland-client)
  • X11: display = Display* (from libX11), window = X11 Window ID

func (*Instance) Destroy 

func (i *Instance) Destroy()

Destroy releases the Vulkan instance.

func (*Instance) EnumerateAdapters 

func (i *Instance) EnumerateAdapters(surfaceHint hal.Surface) []hal.ExposedAdapter

EnumerateAdapters returns available Vulkan adapters (physical devices).

type PipelineLayout 

type PipelineLayout struct {
	// contains filtered or unexported fields
}

PipelineLayout implements hal.PipelineLayout for Vulkan.

func (*PipelineLayout) Destroy 

func (l *PipelineLayout) Destroy()

Destroy releases the pipeline layout.

func (*PipelineLayout) Handle 

func (l *PipelineLayout) Handle() vk.PipelineLayout

Handle returns the VkPipelineLayout handle.

type QuerySet added in v0.16.4 

type QuerySet struct {
	// contains filtered or unexported fields
}

QuerySet implements hal.QuerySet for Vulkan.

func (*QuerySet) Destroy added in v0.16.4 

func (q *QuerySet) Destroy()

Destroy releases the Vulkan query pool.

type Queue 

type Queue struct {
	// contains filtered or unexported fields
}

Queue implements hal.Queue for Vulkan.

func (*Queue) GetTimestampPeriod 

func (q *Queue) GetTimestampPeriod() float32

GetTimestampPeriod returns the timestamp period in nanoseconds.

func (*Queue) PollCompleted added in v0.23.0 

func (q *Queue) PollCompleted() uint64

PollCompleted returns the highest submission index known to be completed by the GPU. Non-blocking.

func (*Queue) Present 

func (q *Queue) Present(surface hal.Surface, _ hal.SurfaceTexture, damageRects []image.Rectangle) error

Present presents a surface texture to the screen.

damageRects is an optional list of rectangles (physical pixels, top-left origin) indicating which surface regions changed this frame. When non-empty and VK_KHR_incremental_present is supported, the rects are chained into VkPresentInfoKHR.PNext as a compositor hint. When empty or the extension is unavailable, the present path is identical to a full-surface present.

func (*Queue) SetSwapchainSuppressed added in v0.26.3 

func (q *Queue) SetSwapchainSuppressed(suppressed bool)

SetSwapchainSuppressed temporarily disables swapchain semaphore binding for subsequent Submit calls. Used for offscreen renders that must not consume acquire/present semaphores intended for the compositor submit.

BUG-WGPU-VK-005: When ui uses RepaintBoundary with GPU texture caching, there are two Submit calls per frame (offscreen + compositor). Without suppression, the first (offscreen) submit hijacks swapchain semaphores, leaving the compositor submit without synchronization -> race -> flickering.

When suppressed is true: saves activeSwapchain/acquireUsed, clears activeSwapchain. When suppressed is false: restores saved values.

Same save/restore pattern as VK-004 in WriteTexture (lines 620-634).

func (*Queue) Submit 

func (q *Queue) Submit(commandBuffers []hal.CommandBuffer) (uint64, error)

Submit submits command buffers to the GPU. Returns a monotonically increasing submission index for tracking completion. The HAL internally manages fence/timeline semaphore synchronization.

VK-SYNC-001: Every submission chains through relay semaphores to guarantee GPU-side execution ordering between consecutive vkQueueSubmit calls.

func (*Queue) SubmitForPresent 

func (q *Queue) SubmitForPresent(commandBuffers []hal.CommandBuffer, swapchain *Swapchain) error

SubmitForPresent submits command buffers with swapchain synchronization.

VK-SYNC-001: Every submission chains through relay semaphores to guarantee GPU-side execution ordering between consecutive vkQueueSubmit calls.

func (*Queue) SupportsCommandBufferCopies added in v0.23.4 

func (q *Queue) SupportsCommandBufferCopies() bool

SupportsCommandBufferCopies returns true for Vulkan. Vulkan uses command buffers for copy operations — PendingWrites batches them.

func (*Queue) WriteBuffer 

func (q *Queue) WriteBuffer(buffer hal.Buffer, offset uint64, data []byte) error

WriteBuffer writes data to a buffer immediately. Uses fence-based synchronization instead of vkQueueWaitIdle to avoid stalling the entire GPU pipeline. Only waits for the last queue submission to complete, which per Khronos benchmarks improves frame times by ~22%.

Both paths use the unified deviceFence: timeline semaphore (VK-IMPL-001) or binary fence pool (VK-IMPL-003).

func (*Queue) WriteTexture 

func (q *Queue) WriteTexture(dst *hal.ImageCopyTexture, data []byte, layout *hal.ImageDataLayout, size *hal.Extent3D) error

WriteTexture writes data to a texture immediately. Returns an error if any step fails (VK-003: no more silent error swallowing).

type RenderBundle added in v0.13.0 

type RenderBundle struct {
	// contains filtered or unexported fields
}

RenderBundle is a pre-recorded set of render commands.

func (*RenderBundle) Destroy added in v0.13.0 

func (b *RenderBundle) Destroy()

Destroy releases the render bundle resources.

type RenderBundleEncoder added in v0.13.0 

type RenderBundleEncoder struct {
	// contains filtered or unexported fields
}

RenderBundleEncoder records commands into a render bundle.

func (*RenderBundleEncoder) Draw added in v0.13.0 

func (e *RenderBundleEncoder) Draw(vertexCount, instanceCount, firstVertex, firstInstance uint32)

Draw draws primitives.

func (*RenderBundleEncoder) DrawIndexed added in v0.13.0 

func (e *RenderBundleEncoder) DrawIndexed(indexCount, instanceCount, firstIndex uint32, baseVertex int32, firstInstance uint32)

DrawIndexed draws indexed primitives.

func (*RenderBundleEncoder) Finish added in v0.13.0 

func (e *RenderBundleEncoder) Finish() hal.RenderBundle

Finish finalizes the bundle and returns it.

func (*RenderBundleEncoder) SetBindGroup added in v0.13.0 

func (e *RenderBundleEncoder) SetBindGroup(index uint32, group hal.BindGroup, offsets []uint32)

SetBindGroup sets a bind group for the given index.

func (*RenderBundleEncoder) SetIndexBuffer added in v0.13.0 

func (e *RenderBundleEncoder) SetIndexBuffer(buffer hal.Buffer, format gputypes.IndexFormat, offset uint64)

SetIndexBuffer sets the index buffer.

func (*RenderBundleEncoder) SetPipeline added in v0.13.0 

func (e *RenderBundleEncoder) SetPipeline(pipeline hal.RenderPipeline)

SetPipeline sets the active render pipeline.

func (*RenderBundleEncoder) SetVertexBuffer added in v0.13.0 

func (e *RenderBundleEncoder) SetVertexBuffer(slot uint32, buffer hal.Buffer, offset uint64)

SetVertexBuffer sets a vertex buffer for the given slot.

type RenderPassCache added in v0.9.3 

type RenderPassCache struct {
	// contains filtered or unexported fields
}

RenderPassCache caches VkRenderPass and VkFramebuffer objects. This is critical for performance and compatibility with Intel drivers that don't properly support VK_KHR_dynamic_rendering.

func NewRenderPassCache added in v0.9.3 

func NewRenderPassCache(device vk.Device, cmds *vk.Commands) *RenderPassCache

NewRenderPassCache creates a new render pass cache.

func (*RenderPassCache) Destroy added in v0.9.3 

func (c *RenderPassCache) Destroy()

Destroy releases all cached resources.

func (*RenderPassCache) GetOrCreateFramebuffer added in v0.9.3 

func (c *RenderPassCache) GetOrCreateFramebuffer(key FramebufferKey) (vk.Framebuffer, error)

GetOrCreateFramebuffer returns a cached framebuffer or creates a new one.

func (*RenderPassCache) GetOrCreateRenderPass added in v0.9.3 

func (c *RenderPassCache) GetOrCreateRenderPass(key RenderPassKey) (vk.RenderPass, error)

GetOrCreateRenderPass returns a cached render pass or creates a new one.

func (*RenderPassCache) InvalidateFramebuffer added in v0.9.3 

func (c *RenderPassCache) InvalidateFramebuffer(imageView vk.ImageView)

InvalidateFramebuffer removes framebuffers from cache that reference the given image view. Called when swapchain is recreated.

type RenderPassEncoder 

type RenderPassEncoder struct {
	// contains filtered or unexported fields
}

RenderPassEncoder implements hal.RenderPassEncoder for Vulkan.

func (*RenderPassEncoder) Draw 

func (e *RenderPassEncoder) Draw(vertexCount, instanceCount, firstVertex, firstInstance uint32)

Draw draws primitives.

func (*RenderPassEncoder) DrawIndexed 

func (e *RenderPassEncoder) DrawIndexed(indexCount, instanceCount, firstIndex uint32, baseVertex int32, firstInstance uint32)

DrawIndexed draws indexed primitives.

func (*RenderPassEncoder) DrawIndexedIndirect 

func (e *RenderPassEncoder) DrawIndexedIndirect(buffer hal.Buffer, offset uint64)

DrawIndexedIndirect draws indexed primitives with GPU-generated parameters.

func (*RenderPassEncoder) DrawIndirect 

func (e *RenderPassEncoder) DrawIndirect(buffer hal.Buffer, offset uint64)

DrawIndirect draws primitives with GPU-generated parameters.

func (*RenderPassEncoder) End 

func (e *RenderPassEncoder) End()

End finishes the render pass. Returns the encoder to the pool for reuse (VK-PERF-006).

func (*RenderPassEncoder) ExecuteBundle 

func (e *RenderPassEncoder) ExecuteBundle(bundle hal.RenderBundle)

ExecuteBundle executes a pre-recorded render bundle.

func (*RenderPassEncoder) SetBindGroup 

func (e *RenderPassEncoder) SetBindGroup(index uint32, group hal.BindGroup, offsets []uint32)

SetBindGroup sets a bind group.

func (*RenderPassEncoder) SetBlendConstant 

func (e *RenderPassEncoder) SetBlendConstant(color *gputypes.Color)

SetBlendConstant sets the blend constant.

func (*RenderPassEncoder) SetIndexBuffer 

func (e *RenderPassEncoder) SetIndexBuffer(buffer hal.Buffer, format gputypes.IndexFormat, offset uint64)

SetIndexBuffer sets the index buffer.

func (*RenderPassEncoder) SetPipeline 

func (e *RenderPassEncoder) SetPipeline(pipeline hal.RenderPipeline)

SetPipeline sets the render pipeline.

func (*RenderPassEncoder) SetScissorRect 

func (e *RenderPassEncoder) SetScissorRect(x, y, width, height uint32)

SetScissorRect sets the scissor rectangle.

func (*RenderPassEncoder) SetStencilReference 

func (e *RenderPassEncoder) SetStencilReference(ref uint32)

SetStencilReference sets the stencil reference value.

func (*RenderPassEncoder) SetVertexBuffer 

func (e *RenderPassEncoder) SetVertexBuffer(slot uint32, buffer hal.Buffer, offset uint64)

SetVertexBuffer sets a vertex buffer. Uses stack variables instead of slice allocations (VK-PERF-007).

func (*RenderPassEncoder) SetViewport 

func (e *RenderPassEncoder) SetViewport(x, y, width, height, minDepth, maxDepth float32)

SetViewport sets the viewport. NOTE: Applies Y-flip for WebGPU/OpenGL coordinate system compatibility (matches Rust wgpu).

type RenderPassKey added in v0.9.3 

type RenderPassKey struct {
	ColorFormat      vk.Format
	ColorLoadOp      vk.AttachmentLoadOp
	ColorStoreOp     vk.AttachmentStoreOp
	DepthFormat      vk.Format
	DepthLoadOp      vk.AttachmentLoadOp
	DepthStoreOp     vk.AttachmentStoreOp
	StencilLoadOp    vk.AttachmentLoadOp
	StencilStoreOp   vk.AttachmentStoreOp
	SampleCount      vk.SampleCountFlagBits
	ColorFinalLayout vk.ImageLayout
	HasResolve       bool // true when MSAA resolve target is present
}

RenderPassKey uniquely identifies a render pass configuration. Used for caching VkRenderPass objects.

type RenderPipeline 

type RenderPipeline struct {
	// contains filtered or unexported fields
}

RenderPipeline implements hal.RenderPipeline for Vulkan.

func (*RenderPipeline) Destroy 

func (p *RenderPipeline) Destroy()

Destroy releases the render pipeline.

type Sampler 

type Sampler struct {
	// contains filtered or unexported fields
}

Sampler implements hal.Sampler for Vulkan.

func (*Sampler) Destroy 

func (s *Sampler) Destroy()

Destroy releases the sampler.

func (*Sampler) Handle 

func (s *Sampler) Handle() vk.Sampler

Handle returns the VkSampler handle.

func (*Sampler) NativeHandle added in v0.12.0 

func (s *Sampler) NativeHandle() uintptr

NativeHandle returns the raw VkSampler handle as uintptr.

type ShaderModule 

type ShaderModule struct {
	// contains filtered or unexported fields
}

ShaderModule implements hal.ShaderModule for Vulkan.

func (*ShaderModule) Destroy 

func (m *ShaderModule) Destroy()

Destroy releases the shader module.

func (*ShaderModule) Handle 

func (m *ShaderModule) Handle() vk.ShaderModule

Handle returns the VkShaderModule handle.

type Surface 

type Surface struct {
	// contains filtered or unexported fields
}

Surface implements hal.Surface for Vulkan.

func (*Surface) AcquireTexture 

func (s *Surface) AcquireTexture(_ hal.Fence) (*hal.AcquiredSurfaceTexture, error)

AcquireTexture acquires the next surface texture for rendering. Returns hal.ErrNotReady if no image is available (non-blocking mode).

func (*Surface) Configure 

func (s *Surface) Configure(device hal.Device, config *hal.SurfaceConfiguration) error

Configure configures the surface for presentation.

Returns hal.ErrZeroArea if width or height is zero. This commonly happens when the window is minimized or not yet fully visible. Wait until the window has valid dimensions before calling Configure again.

func (*Surface) Destroy 

func (s *Surface) Destroy()

Destroy releases the surface.

func (*Surface) DiscardTexture 

func (s *Surface) DiscardTexture(_ hal.SurfaceTexture)

DiscardTexture discards a surface texture without presenting it.

func (*Surface) Unconfigure 

func (s *Surface) Unconfigure(_ hal.Device)

Unconfigure removes surface configuration.

type Swapchain 

type Swapchain struct {
	// contains filtered or unexported fields
}

Swapchain manages Vulkan swapchain for a surface.

func (*Swapchain) Destroy 

func (sc *Swapchain) Destroy()

Destroy destroys the swapchain completely.

func (*Swapchain) SetImageLayout added in v0.26.4 

func (sc *Swapchain) SetImageLayout(imageIndex uint32, layout vk.ImageLayout)

SetImageLayout updates the tracked layout for a swapchain image. Called from BeginRenderPass when the render pass finalLayout is known for a swapchain color attachment. This allows present() to skip the barrier when the render pass already transitions to PRESENT_SRC_KHR.

BUG-WGPU-VK-006: Without this tracking, present() would either always insert a barrier (unnecessary overhead) or never insert one (the bug).

type SwapchainTexture 

type SwapchainTexture struct {
	// contains filtered or unexported fields
}

SwapchainTexture wraps a swapchain image as a SurfaceTexture.

func (*SwapchainTexture) AddPendingRef added in v0.23.4 

func (t *SwapchainTexture) AddPendingRef()

func (*SwapchainTexture) CurrentUsage added in v0.23.4 

func (t *SwapchainTexture) CurrentUsage() gputypes.TextureUsage

CurrentUsage returns 0 — Vulkan swapchain images are managed by the swapchain.

func (*SwapchainTexture) DecPendingRef added in v0.23.4 

func (t *SwapchainTexture) DecPendingRef()

func (*SwapchainTexture) Destroy 

func (t *SwapchainTexture) Destroy()

Destroy implements hal.Texture.

func (*SwapchainTexture) NativeHandle added in v0.12.0 

func (t *SwapchainTexture) NativeHandle() uintptr

NativeHandle returns the raw VkImage handle as uintptr.

type Texture 

type Texture struct {
	// contains filtered or unexported fields
}

Texture implements hal.Texture for Vulkan.

func (*Texture) AddPendingRef added in v0.23.4 

func (t *Texture) AddPendingRef()

func (*Texture) CurrentUsage added in v0.23.4 

func (t *Texture) CurrentUsage() gputypes.TextureUsage

CurrentUsage returns 0 — Vulkan uses pipeline barriers managed by the caller.

func (*Texture) DecPendingRef added in v0.23.4 

func (t *Texture) DecPendingRef()

func (*Texture) Destroy 

func (t *Texture) Destroy()

Destroy releases the texture.

func (*Texture) Handle 

func (t *Texture) Handle() vk.Image

Handle returns the VkImage handle.

func (*Texture) NativeHandle added in v0.12.0 

func (t *Texture) NativeHandle() uintptr

NativeHandle returns the raw VkImage handle as uintptr.

type TextureView 

type TextureView struct {
	// contains filtered or unexported fields
}

TextureView implements hal.TextureView for Vulkan.

func (*TextureView) Destroy 

func (v *TextureView) Destroy()

Destroy releases the texture view.

func (*TextureView) Handle 

func (v *TextureView) Handle() vk.ImageView

Handle returns the VkImageView handle.

func (*TextureView) NativeHandle added in v0.12.0 

func (v *TextureView) NativeHandle() uintptr

NativeHandle returns the raw VkImageView handle as uintptr.

Source Files

View all Source files

Directories

Path Synopsis
Package memory provides GPU memory allocation for Vulkan backend.
 Package memory provides GPU memory allocation for Vulkan backend.
Package vk provides Pure Go Vulkan bindings using goffi for FFI calls.
 Package vk provides Pure Go Vulkan bindings using goffi for FFI calls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.