vulkan

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Dec 26, 2025 License: MIT Imports: 9 Imported by: 0

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 types.Features, limits types.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 types.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() types.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

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) 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.

func (*CommandBuffer) Destroy

func (c *CommandBuffer) Destroy()

Destroy releases the command buffer resources.

type CommandEncoder

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

CommandEncoder implements hal.CommandEncoder for Vulkan.

func (*CommandEncoder) BeginComputePass

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

BeginComputePass begins a compute pass.

func (*CommandEncoder) BeginEncoding

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

BeginEncoding begins command recording.

func (*CommandEncoder) BeginRenderPass

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

BeginRenderPass begins a render pass using dynamic rendering (Vulkan 1.3+).

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) DiscardEncoding

func (e *CommandEncoder) DiscardEncoding()

DiscardEncoding discards the encoder.

func (*CommandEncoder) EndEncoding

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

EndEncoding finishes command recording and returns a command buffer.

func (*CommandEncoder) ResetAll

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

ResetAll resets command buffers for reuse.

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 CommandPool

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

CommandPool manages command buffer allocation.

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.

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

Allocate allocates a descriptor set from the given layout.

func (*DescriptorAllocator) Destroy

func (a *DescriptorAllocator) Destroy()

Destroy releases all descriptor pools.

func (*DescriptorAllocator) Free

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.

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) 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) 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) 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.

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 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 an X11 surface from display and window handles. Parameters:

  • display: X11 Display pointer (Display*)
  • window: X11 Window handle (Window)

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 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) Present

func (q *Queue) Present(surface hal.Surface, texture hal.SurfaceTexture) error

Present presents a surface texture to the screen.

func (*Queue) Submit

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

Submit submits command buffers to the GPU.

func (*Queue) SubmitForPresent

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

SubmitForPresent submits command buffers with swapchain synchronization.

func (*Queue) WriteBuffer

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

WriteBuffer writes data to a buffer immediately.

func (*Queue) WriteTexture

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

WriteTexture writes data to a texture immediately.

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.

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 *types.Color)

SetBlendConstant sets the blend constant.

func (*RenderPassEncoder) SetIndexBuffer

func (e *RenderPassEncoder) SetIndexBuffer(buffer hal.Buffer, format types.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.

func (*RenderPassEncoder) SetViewport

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

SetViewport sets the viewport.

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.

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.

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.

type SwapchainTexture

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

SwapchainTexture wraps a swapchain image as a SurfaceTexture.

func (*SwapchainTexture) Destroy

func (t *SwapchainTexture) Destroy()

Destroy implements hal.Texture.

type Texture

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

Texture implements hal.Texture for Vulkan.

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.

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.

Directories

Path Synopsis
Package memory provides GPU memory allocation for Vulkan backend.
Package memory provides GPU memory allocation for Vulkan backend.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL