shader

Documentation

Overview

Package shader compiles WGSL compute shaders to SPIR-V for Vulki's direct Vulkan path and for callers using the low-level vk package.

Compile uses validated SPIR-V 1.3 output by default. Functional options can select another supported version, include debug information, or explicitly disable validation without exposing the compiler implementation's types. Successful compilations are cached in-process, so repeatedly compiling the same source with the same options does not rerun the compiler.

Index

• Variables
• func Compile(wgslSource string, options ...Option) ([]byte, error)
• type CompileError
  • func (e *CompileError) Error() string
• type CompileStage
• type Option
  • func WithSPIRVVersion(version SPIRVVersion) Option
• type SPIRVVersion

Examples

• Compile
• Compile (Options)
• CompileError

Variables

var WithDebugInfo = withDebugInfo()

WithDebugInfo includes source names and line information in the generated SPIR-V module.

var WithoutValidation = withoutValidation()

WithoutValidation disables intermediate-representation validation before SPIR-V generation. Validation is enabled by default and should normally remain enabled.

Functions

func Compile

func Compile(wgslSource string, options ...Option) ([]byte, error)

Compile compiles WGSL source code to SPIR-V. With no options it targets SPIR-V 1.3, includes no debug information, and validates the shader.

Successful compilations are cached process-wide, keyed by the source and the resolved options. Every call returns a module the caller owns, so modifying a returned module cannot affect later compilations.

Example

package main

import (
	"github.com/srlehn/vulki/shader"
)

const computeWGSL = `
@compute @workgroup_size(1)
fn main() {}
`

func main() {
	_, _ = shader.Compile(computeWGSL)
}

Example (Options)

package main

import (
	"github.com/srlehn/vulki/shader"
)

const computeWGSL = `
@compute @workgroup_size(1)
fn main() {}
`

func main() {
	_, _ = shader.Compile(
		computeWGSL,
		shader.WithSPIRVVersion(shader.SPIRV1_0),
		shader.WithDebugInfo,
	)
}

Types

type CompileError

type CompileError struct {
	Stage   CompileStage
	Message string
}

CompileError reports a WGSL compilation failure without exposing the underlying compiler implementation's error types.

Example

package main

import (
	"errors"

	"github.com/srlehn/vulki/shader"
)

func main() {
	_, err := shader.Compile("not WGSL")
	var compileError *shader.CompileError
	if errors.As(err, &compileError) {
		_ = compileError.Stage
		_ = compileError.Message
	}
}

func (*CompileError) Error

func (e *CompileError) Error() string

type CompileStage

type CompileStage string

CompileStage identifies the stage that rejected shader compilation.

const (
	// CompileStageOptions validates Compile options before invoking the compiler.
	CompileStageOptions CompileStage = "options"
	// CompileStageCompiler parses, validates, and generates the shader module.
	CompileStageCompiler CompileStage = "compiler"
)

type Option

type Option func(*compileConfig) error

Option configures WGSL to SPIR-V compilation.

func WithSPIRVVersion

func WithSPIRVVersion(version SPIRVVersion) Option

WithSPIRVVersion selects the generated SPIR-V version.

type SPIRVVersion

type SPIRVVersion uint8

SPIRVVersion identifies a supported SPIR-V output version.

const (
	// SPIRV1_0 targets SPIR-V 1.0.
	SPIRV1_0 SPIRVVersion = iota
	// SPIRV1_3 targets SPIR-V 1.3 and is the default.
	SPIRV1_3
)