shader

type Array = []Value

type BindingKey struct {
	Group   uint32
	Binding uint32
}

type BufferPointer struct {
	Buffer []byte    // raw buffer data
	Offset uint32    // byte offset within the buffer
	Type   *TypeInfo // type of the pointed-to element
}

type DebugAction int

type DebugContext struct {
	// OnInstruction is called before each instruction executes (when stepping
	// or when a watched variable changed). The returned DebugAction controls
	// whether to continue, step, or abort.
	OnInstruction func(event InstructionEvent) DebugAction

	// OnBreakpoint is called when execution reaches a breakpoint instruction
	// index. If both OnBreakpoint and OnInstruction are set, OnBreakpoint fires
	// first, then OnInstruction fires and its return value controls flow.
	OnBreakpoint func(event InstructionEvent)

	// OnError is called when an instruction produces a runtime error (e.g.,
	// exceeding max iterations). The error is still returned from ExecuteWithDebug.
	OnError func(event ErrorEvent)

	// Breakpoints maps instruction index (0-based within the function) to
	// a boolean indicating whether a breakpoint is set. The instruction at
	// the given index triggers the OnBreakpoint callback before execution.
	Breakpoints map[int]bool

	// WatchVariables maps SSA result IDs to watch status. When a watched
	// variable's value changes after an instruction, OnInstruction is called
	// with DebugStep regardless of breakpoints.
	WatchVariables map[uint32]bool

	// TraceEnabled enables JSON-lines trace output. Each instruction that
	// produces a result writes one JSON line to TraceWriter after execution.
	TraceEnabled bool

	// TraceWriter receives JSON-lines trace output when TraceEnabled is true.
	// Each line is a self-contained JSON object terminated by a newline.
	TraceWriter io.Writer
}

type EntryPoint struct {
	ExecutionModel uint32
	FunctionID     uint32
	Name           string
	InterfaceIDs   []uint32 // IDs of interface variables
}

type ErrorEvent struct {
	// PC is the instruction index where the error occurred.
	PC int

	// Instruction is the instruction that caused the error.
	Instruction Instruction

	// Err is the runtime error.
	Err error
}

type ExecutionContext struct {
	// Inputs maps variable ID to its value (builtin inputs like vertex_index).
	Inputs map[uint32]Value

	// Buffers maps (group, binding) to raw buffer data for uniform/storage buffers.
	Buffers map[BindingKey][]byte

	// Textures maps (group, binding) to a 2D texture.
	Textures map[BindingKey]*Texture2D

	// Samplers maps (group, binding) to sampler parameters.
	Samplers map[BindingKey]*Sampler

	// WorkgroupSharedMemory is shared memory for compute shader workgroups.
	// Maps variable ID to a byte slice shared across all invocations.
	WorkgroupSharedMemory map[uint32][]byte

	// ComputeBuiltins provides compute shader built-in values.
	GlobalInvocationID   [3]uint32
	LocalInvocationID    [3]uint32
	WorkgroupID          [3]uint32
	NumWorkgroups        [3]uint32
	WorkgroupSize        [3]uint32
	LocalInvocationIndex uint32
}

type Float32 = float32

type FragmentShaderFunc func(
	fragment raster.Fragment,
	uniforms any,
) [4]float32

type Function struct {
	ID           uint32
	ReturnType   uint32
	FunctionType uint32
	Instructions []Instruction

	// Labels maps label ID to instruction index. Built once during ParseModule
	// to avoid rebuilding on every Execute call. OpBranch and OpBranchConditional
	// use this for control flow.
	Labels map[uint32]int
}

type Instruction struct {
	Opcode   uint16
	ResultID uint32   // 0 if instruction produces no result
	TypeID   uint32   // 0 if instruction has no result type
	Operands []uint32 // remaining operands after result/type
}

type InstructionEvent struct {
	// PC is the 0-based instruction index within the current function.
	PC int

	// Instruction is the SPIR-V instruction about to execute (for OnInstruction
	// and OnBreakpoint) or just executed (for watch triggers).
	Instruction Instruction

	// Values is the current SSA value slice indexed by SPIR-V ID. This is a
	// direct reference to the interpreter's live values -- callers should
	// treat it as read-only.
	Values []Value

	// BlockLabel is the result ID of the current basic block's OpLabel.
	BlockLabel uint32
}

type Int32 = int32

type Mat4 = [4]Vec4

type Module struct {
	// Types maps result ID to type information.
	Types map[uint32]*TypeInfo

	// Constants maps result ID to constant value.
	Constants map[uint32]Value

	// Functions maps entry point name to function body.
	Functions map[string]*Function

	// EntryPoints maps entry point name to its metadata.
	EntryPoints map[string]*EntryPoint

	// Decorations maps (target ID, decoration kind) to decoration value.
	Decorations map[decorationKey]uint32

	// MemberDecorations maps (struct type ID, member index, decoration kind) to value.
	// Used for OpMemberDecorate, primarily for struct member Offset decorations.
	MemberDecorations map[memberDecorationKey]uint32

	// Variables maps result ID to variable metadata.
	Variables map[uint32]*VariableInfo

	// FunctionsByID maps function result ID to function body.
	// Used by OpFunctionCall to dispatch to non-entry-point functions.
	FunctionsByID map[uint32]*Function

	// ExtInstImports maps result ID to the imported instruction set name.
	// The primary use is "GLSL.std.450" for math intrinsics.
	ExtInstImports map[uint32]string

	// ExecutionModes maps (function ID, execution mode) to operands.
	// Used for LocalSize in compute shaders.
	ExecutionModes map[executionModeKey][]uint32

	// Bound is the upper bound of all IDs in the module.
	Bound uint32
	// contains filtered or unexported fields
}

type Pointer struct {
	Val Value
}

type SampledImageValue struct {
	Image   Value // BindingKey or *Texture2D (stored as Value)
	Sampler Value // BindingKey or *Sampler (stored as Value)
}

type Sampler struct {
	MinFilter uint32 // 0 = Nearest, 1 = Linear.
	MagFilter uint32 // 0 = Nearest, 1 = Linear.
	WrapU     uint32 // 0 = Repeat, 1 = ClampToEdge, 2 = MirroredRepeat.
	WrapV     uint32 // 0 = Repeat, 1 = ClampToEdge, 2 = MirroredRepeat.
}

type ShaderProgram struct {
	// Vertex is the vertex shader function.
	Vertex VertexShaderFunc

	// Fragment is the fragment shader function.
	Fragment FragmentShaderFunc
}

type SolidColorUniforms struct {
	// MVP is the Model-View-Projection matrix in column-major order.
	MVP [16]float32

	// Color is the RGBA color to render with values in [0, 1].
	Color [4]float32
}

type SubPointer struct {
	Parent  *Pointer // root variable pointer
	Indexes []uint32 // index path from parent to sub-element (literal values, not SSA IDs)
}

type Texture2D struct {
	Width  uint32
	Height uint32
	Data   []byte // RGBA pixel data, row-major, 4 bytes per pixel.
	Format uint32 // Texture format identifier (0 = RGBA8).
}

type TexturedUniforms struct {
	// MVP is the Model-View-Projection matrix in column-major order.
	MVP [16]float32

	// TextureData is the RGBA8 texture data.
	TextureData []byte

	// TextureWidth is the width of the texture in pixels.
	TextureWidth int

	// TextureHeight is the height of the texture in pixels.
	TextureHeight int
}

type TypeInfo struct {
	Kind       TypeKind
	Width      uint32   // bit width for int/float
	Signed     bool     // for OpTypeInt
	Components uint32   // for OpTypeVector
	ElemType   uint32   // element type ID for vector/array/pointer
	Length     uint32   // for OpTypeArray (number of elements)
	Storage    uint32   // for OpTypePointer (storage class)
	ParamIDs   []uint32 // for OpTypeFunction (parameter type IDs)
	ReturnType uint32   // for OpTypeFunction
	MemberIDs  []uint32 // for OpTypeStruct
}

type TypeKind int

type Uint32 = uint32

type Value struct {
	Tag ValueTag
	F   [4]float32     // float scalars + vectors
	U   [4]uint32      // uint/int scalars, bool, binding key
	Ref unsafe.Pointer // Array, Pointer, SubPointer, BufferPointer, SampledImageValue
}

type ValueTag byte

type VariableInfo struct {
	TypeID       uint32 // pointer type ID
	StorageClass uint32
}

type Vec2 = [2]float32

type Vec3 = [3]float32

type Vec4 = [4]float32

type Vertex struct {
	// Position in object/model space.
	Position [3]float32

	// Attributes are additional per-vertex data (colors, UVs, normals, etc.).
	Attributes []float32
}

type VertexColorUniforms struct {
	// MVP is the Model-View-Projection matrix in column-major order.
	MVP [16]float32
}

type VertexShaderFunc func(
	vertexIndex int,
	position [3]float32,
	attributes []float32,
	uniforms any,
) raster.ClipSpaceVertex