fix(msl): pass-through globals for helper functions

MSL helper functions cannot access entry point resource bindings
(textures, samplers, uniforms, storage buffers) directly. This adds
analysis to detect which globals each function references and passes
them as extra parameters at declaration and extra arguments at call
sites, matching the Rust naga reference implementation.

Fixes gogpu/ui#23 (black screen on M3 Mac due to undeclared
msdf_atlas/msdf_sampler in MSDF text shader helper functions).

Author: kolkov

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.6] - 2026-03-06
+
+### Fixed
+
+#### MSL Backend
+- **Pass-through globals for helper functions** — textures, samplers, uniforms, and storage buffers used by non-entry-point functions are now passed as extra parameters and arguments; previously MSL helper functions could not access entry point resource bindings, causing `undeclared identifier` errors (e.g., `msdf_atlas`, `msdf_sampler`, `sh_scratch`) for any shader with helper functions referencing global resources ([gogpu/ui#23](https://github.com/gogpu/ui/issues/23))
+
 ## [0.14.5] - 2026-03-04
 
 ### Fixed

msl/backend_test.go

@@ -548,3 +548,168 @@ func TestCompile_EntryPointReturnAttributePlacement(t *testing.T) {
 		t.Error("[[position]] should be on struct member, not on function signature")
 	}
 }
+
+// TestMSL_PassThroughGlobals verifies that helper functions receiving
+// texture/sampler globals get them as extra parameters, and call sites
+// pass them as extra arguments. This is the fix for gogpu/ui#23 where
+// MSL helper functions couldn't access entry point resource bindings.
+func TestMSL_PassThroughGlobals(t *testing.T) {
+	// Type handles:
+	// 0: f32, 1: vec2f, 2: vec4f, 3: texture2d, 4: sampler
+	tF32 := ir.TypeHandle(0)
+	tVec2 := ir.TypeHandle(1)
+	tVec4 := ir.TypeHandle(2)
+	tTex := ir.TypeHandle(3)
+	tSamp := ir.TypeHandle(4)
+
+	binding0 := &ir.ResourceBinding{Group: 0, Binding: 0}
+	binding1 := &ir.ResourceBinding{Group: 0, Binding: 1}
+
+	module := &ir.Module{
+		Types: []ir.Type{
+			{Name: "f32", Inner: ir.ScalarType{Kind: ir.ScalarFloat, Width: 4}},
+			{Name: "vec2f", Inner: ir.VectorType{Size: ir.Vec2, Scalar: ir.ScalarType{Kind: ir.ScalarFloat, Width: 4}}},
+			{Name: "vec4f", Inner: ir.VectorType{Size: ir.Vec4, Scalar: ir.ScalarType{Kind: ir.ScalarFloat, Width: 4}}},
+			{Name: "tex2d", Inner: ir.ImageType{Dim: ir.Dim2D, Class: ir.ImageClassSampled}},
+			{Name: "samp", Inner: ir.SamplerType{Comparison: false}},
+		},
+		GlobalVariables: []ir.GlobalVariable{
+			{Name: "my_texture", Space: ir.SpaceHandle, Type: tTex, Binding: binding0},
+			{Name: "my_sampler", Space: ir.SpaceHandle, Type: tSamp, Binding: binding1},
+		},
+		Functions: []ir.Function{
+			{
+				// Helper function: sample_tex(uv: vec2f) -> vec4f
+				// References globals: my_texture (0), my_sampler (1)
+				Name: "sample_tex",
+				Arguments: []ir.FunctionArgument{
+					{Name: "uv", Type: tVec2},
+				},
+				Result: &ir.FunctionResult{Type: tVec4},
+				Expressions: []ir.Expression{
+					{Kind: ir.ExprFunctionArgument{Index: 0}},  // 0: uv
+					{Kind: ir.ExprGlobalVariable{Variable: 0}}, // 1: my_texture
+					{Kind: ir.ExprGlobalVariable{Variable: 1}}, // 2: my_sampler
+					{Kind: ir.ExprImageSample{ // 3: textureSample
+						Image: 1, Sampler: 2, Coordinate: 0,
+						Level: ir.SampleLevelAuto{},
+					}},
+				},
+				ExpressionTypes: []ir.TypeResolution{
+					{Handle: &tVec2}, // 0: uv
+					{Handle: &tTex},  // 1: texture
+					{Handle: &tSamp}, // 2: sampler
+					{Handle: &tVec4}, // 3: sample result
+				},
+				Body: []ir.Statement{
+					{Kind: ir.StmtEmit{Range: ir.Range{Start: 0, End: 4}}},
+					{Kind: ir.StmtReturn{Value: ptrExpr(3)}},
+				},
+			},
+			{
+				// Entry point function: calls sample_tex with hardcoded UV
+				Name: "fs_entry",
+				Result: &ir.FunctionResult{
+					Type:    tVec4,
+					Binding: bindingPtr(ir.LocationBinding{Location: 0}),
+				},
+				Expressions: []ir.Expression{
+					{Kind: ir.Literal{Value: ir.LiteralF32(0.5)}}, // 0: 0.5
+					{Kind: ir.Literal{Value: ir.LiteralF32(0.5)}}, // 1: 0.5
+					{Kind: ir.ExprCompose{ // 2: vec2(0.5, 0.5)
+						Type: tVec2, Components: []ir.ExpressionHandle{0, 1},
+					}},
+					{Kind: ir.ExprCallResult{Function: 0}}, // 3: result of call
+				},
+				ExpressionTypes: []ir.TypeResolution{
+					{Handle: &tF32},  // 0: literal
+					{Handle: &tF32},  // 1: literal
+					{Handle: &tVec2}, // 2: compose
+					{Handle: &tVec4}, // 3: call result
+				},
+				Body: []ir.Statement{
+					{Kind: ir.StmtEmit{Range: ir.Range{Start: 0, End: 3}}},
+					{Kind: ir.StmtCall{
+						Function:  0, // call sample_tex
+						Arguments: []ir.ExpressionHandle{2},
+						Result:    ptrExpr(3),
+					}},
+					{Kind: ir.StmtReturn{Value: ptrExpr(3)}},
+				},
+			},
+		},
+		EntryPoints: []ir.EntryPoint{
+			{
+				Name: "fs_main", Stage: ir.StageFragment,
+				Function: 1, // references Functions[1]
+			},
+		},
+	}
+
+	result, _, err := Compile(module, DefaultOptions())
+	if err != nil {
+		t.Fatalf("Compile failed: %v", err)
+	}
+
+	// Helper function should have texture and sampler as extra params (no [[binding]])
+	if !strings.Contains(result, "sample_tex(") {
+		t.Fatal("Expected helper function sample_tex in output")
+	}
+
+	// Check that helper function has pass-through params
+	if !strings.Contains(result, "my_texture") {
+		t.Error("Expected my_texture in helper function params")
+	}
+	if !strings.Contains(result, "my_sampler") {
+		t.Error("Expected my_sampler in helper function params")
+	}
+
+	// Helper function params should NOT have [[texture(N)]] or [[sampler(N)]] attributes
+	// (those belong only on entry point params)
+	lines := strings.Split(result, "\n")
+	inHelper := false
+	for _, line := range lines {
+		if strings.Contains(line, "sample_tex(") {
+			inHelper = true
+		}
+		if inHelper && strings.Contains(line, ") {") {
+			inHelper = false
+		}
+		if inHelper {
+			if strings.Contains(line, "[[texture(") || strings.Contains(line, "[[sampler(") {
+				t.Errorf("Helper function should not have binding attributes, got: %s", line)
+			}
+		}
+	}
+
+	// Entry point should have [[texture(0)]] and [[sampler(1)]]
+	if !strings.Contains(result, "[[texture(0)]]") {
+		t.Error("Expected [[texture(0)]] on entry point param")
+	}
+	if !strings.Contains(result, "[[sampler(1)]]") {
+		t.Error("Expected [[sampler(1)]] on entry point param")
+	}
+
+	// Call site should pass globals as extra arguments
+	// Look for something like: sample_tex(vec2f_expr, my_texture, my_sampler)
+	foundCallWithGlobals := false
+	for _, line := range lines {
+		if strings.Contains(line, "sample_tex(") && strings.Contains(line, "my_texture") && strings.Contains(line, "my_sampler") {
+			foundCallWithGlobals = true
+			break
+		}
+	}
+	if !foundCallWithGlobals {
+		t.Error("Expected call site to pass my_texture and my_sampler as extra arguments")
+	}
+
+	t.Logf("Generated MSL:\n%s", result)
+}
+
+func ptrExpr(h ir.ExpressionHandle) *ir.ExpressionHandle {
+	return &h
+}
+
+func bindingPtr(b ir.Binding) *ir.Binding {
+	return &b
+}

msl/functions.go

@@ -13,6 +13,98 @@ const (
 	spaceDevice   = "device"
 )
 
+// needsPassThrough returns true if global variables in this address space
+// must be passed as function arguments in MSL. MSL doesn't have true globals
+// for resources — they must be passed through from entry points.
+func needsPassThrough(space ir.AddressSpace) bool {
+	switch space {
+	case ir.SpaceUniform, ir.SpaceStorage, ir.SpaceHandle, ir.SpacePrivate, ir.SpaceWorkGroup:
+		return true
+	default:
+		return false
+	}
+}
+
+// analyzeFuncPassThroughGlobals scans each non-entry-point function to determine
+// which global variables it references. These globals must be added as extra
+// parameters since MSL helper functions cannot access entry point bindings.
+// Uses memoization to handle transitive calls (A calls B which uses globals).
+func (w *Writer) analyzeFuncPassThroughGlobals() {
+	for handle := range w.module.Functions {
+		w.getPassThroughGlobals(ir.FunctionHandle(handle))
+	}
+}
+
+// getPassThroughGlobals returns (and caches) the list of global variable handles
+// that a function needs as pass-through parameters.
+func (w *Writer) getPassThroughGlobals(handle ir.FunctionHandle) []uint32 {
+	if cached, ok := w.funcPassThroughGlobals[handle]; ok {
+		return cached
+	}
+
+	// Mark as visited (empty slice) to prevent infinite recursion
+	w.funcPassThroughGlobals[handle] = []uint32{}
+
+	fn := &w.module.Functions[handle]
+	seen := make(map[uint32]struct{})
+	var result []uint32
+
+	addGlobal := func(h uint32) {
+		if _, already := seen[h]; already {
+			return
+		}
+		if int(h) < len(w.module.GlobalVariables) {
+			gvar := &w.module.GlobalVariables[h]
+			if needsPassThrough(gvar.Space) {
+				seen[h] = struct{}{}
+				result = append(result, h)
+			}
+		}
+	}
+
+	// Direct global variable references in expressions
+	for _, expr := range fn.Expressions {
+		if gv, ok := expr.Kind.(ir.ExprGlobalVariable); ok {
+			addGlobal(uint32(gv.Variable))
+		}
+	}
+
+	// Transitive: globals used by called functions
+	w.walkStmts(fn.Body, func(call ir.StmtCall) {
+		if int(call.Function) < len(w.module.Functions) {
+			for _, h := range w.getPassThroughGlobals(call.Function) {
+				addGlobal(h)
+			}
+		}
+	})
+
+	w.funcPassThroughGlobals[handle] = result
+	return result
+}
+
+// walkStmts walks all statements (including nested blocks) and calls
+// the visitor for each StmtCall found.
+func (w *Writer) walkStmts(stmts ir.Block, visitCall func(ir.StmtCall)) {
+	for _, stmt := range stmts {
+		switch s := stmt.Kind.(type) {
+		case ir.StmtCall:
+			visitCall(s)
+		case ir.StmtBlock:
+			w.walkStmts(s.Block, visitCall)
+		case ir.StmtIf:
+			w.walkStmts(s.Accept, visitCall)
+			w.walkStmts(s.Reject, visitCall)
+		case ir.StmtSwitch:
+			for _, c := range s.Cases {
+				w.walkStmts(c.Body, visitCall)
+			}
+		case ir.StmtLoop:
+			w.walkStmts(s.Body, visitCall)
+			w.walkStmts(s.Continuing, visitCall)
+		}
+	}
+}
+
 // writeFunctions writes all non-entry-point function definitions.
 func (w *Writer) writeFunctions() error {
 	for handle := range w.module.Functions {
@@ -68,13 +160,26 @@ func (w *Writer) writeFunction(handle ir.FunctionHandle, fn *ir.Function) error
 	w.write("%s %s(", returnType, funcName)
 
 	// Parameters
+	paramCount := 0
 	for i, arg := range fn.Arguments {
-		if i > 0 {
+		if paramCount > 0 {
 			w.write(", ")
 		}
 		argName := w.getName(nameKey{kind: nameKeyFunctionArgument, handle1: uint32(handle), handle2: uint32(i)})
 		argType := w.writeTypeName(arg.Type, StorageAccess(0))
 		w.write("%s %s", argType, argName)
+		paramCount++
+	}
+
+	// Pass-through global resources (textures, samplers, buffers)
+	if globals, ok := w.funcPassThroughGlobals[handle]; ok {
+		for _, gHandle := range globals {
+			if paramCount > 0 {
+				w.write(",\n    ")
+			}
+			w.writePassThroughParam(gHandle)
+			paramCount++
+		}
 	}
 
 	w.write(") {\n")
@@ -498,6 +603,34 @@ func (w *Writer) writeEntryPointOutputStruct(epIdx int, ep *ir.EntryPoint, fn *i
 	return structName, true
 }
 
+// writePassThroughParam writes a global variable as a pass-through parameter
+// for a helper function. Unlike entry point params, these have no [[binding]] attributes.
+func (w *Writer) writePassThroughParam(handle uint32) {
+	global := &w.module.GlobalVariables[handle]
+	name := w.getName(nameKey{kind: nameKeyGlobalVariable, handle1: handle})
+	typeInfo := &w.module.Types[global.Type]
+
+	switch inner := typeInfo.Inner.(type) {
+	case ir.SamplerType:
+		w.write("%ssampler %s", Namespace, name)
+
+	case ir.ImageType:
+		typeName := w.imageTypeName(inner, StorageAccess(0))
+		w.write("%s %s", typeName, name)
+
+	default:
+		// Buffer types (uniform, storage)
+		space := addressSpaceName(global.Space)
+		typeName := w.writeTypeName(global.Type, StorageAccess(0))
+
+		if space == spaceConstant || space == spaceDevice {
+			w.write("%s %s& %s", space, typeName, name)
+		} else {
+			w.write("%s %s", typeName, name)
+		}
+	}
+}
+
 // writeGlobalResourceParam writes a global resource as an entry point parameter.
 func (w *Writer) writeGlobalResourceParam(handle uint32, global *ir.GlobalVariable) error {
 	name := w.getName(nameKey{kind: nameKeyGlobalVariable, handle1: handle})

msl/statements.go

@@ -473,6 +473,18 @@ func (w *Writer) writeCall(call ir.StmtCall) error {
 		}
 	}
 
+	// Pass-through global resources (textures, samplers, buffers)
+	if globals, ok := w.funcPassThroughGlobals[call.Function]; ok {
+		hasArgs := len(call.Arguments) > 0
+		for i, gHandle := range globals {
+			if hasArgs || i > 0 {
+				w.write(", ")
+			}
+			name := w.getName(nameKey{kind: nameKeyGlobalVariable, handle1: gHandle})
+			w.write("%s", name)
+		}
+	}
+
 	w.write(");\n")
 	return nil
 }