light

type CompositionHandler interface {
	// Enabled returns whether the composition subsystem has been GPU-initialized
	// and is ready for rendering.
	//
	// Returns:
	//   - bool: true if composition GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the composition subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// ScreenWidth returns the current screen width in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen width
	ScreenWidth() int

	// ScreenHeight returns the current screen height in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen height
	ScreenHeight() int

	// ToneMappingEnabled returns whether ACES tone mapping is applied during composition.
	//
	// Returns:
	//   - bool: true if tone mapping is enabled
	ToneMappingEnabled() bool

	// Exposure returns the exposure multiplier applied to HDR values before tone mapping.
	//
	// Returns:
	//   - float32: the current exposure value
	Exposure() float32

	// SetExposure sets the exposure multiplier applied to HDR values before tone mapping.
	//
	// Parameters:
	//   - exposure: the exposure multiplier (1.0 = neutral)
	SetExposure(exposure float32)

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// Bgp retrieves the bind group provider associated with the given key.
	// Returns nil if the key does not exist.
	//
	// Parameters:
	//   - key: the bind group provider name
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of bind group providers.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all registered providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// SetBgp stores a bind group provider under the given key.
	//
	// Parameters:
	//   - key: the bind group provider name
	//   - bgp: the bind group provider
	SetBgp(key string, bgp bind_group_provider.BindGroupProvider)

	// HDRTexture returns the RGBA16Float offscreen render target that the lit
	// pass writes to when composition is active.
	//
	// Returns:
	//   - *wgpu.Texture: the HDR texture, or nil if not initialized
	HDRTexture() *wgpu.Texture

	// SetHDRTexture sets the HDR offscreen render target texture.
	//
	// Parameters:
	//   - t: the HDR texture
	SetHDRTexture(t *wgpu.Texture)

	// HDRTextureView returns the texture view for the HDR render target.
	//
	// Returns:
	//   - *wgpu.TextureView: the HDR texture view, or nil if not initialized
	HDRTextureView() *wgpu.TextureView

	// SetHDRTextureView sets the texture view for the HDR render target.
	//
	// Parameters:
	//   - tv: the HDR texture view
	SetHDRTextureView(tv *wgpu.TextureView)

	// MSAATexture returns the multi-sampled RGBA16Float texture used as the
	// lit pass color attachment when MSAA is enabled. Resolves into the HDR texture.
	//
	// Returns:
	//   - *wgpu.Texture: the MSAA texture, or nil if MSAA is off or not initialized
	MSAATexture() *wgpu.Texture

	// SetMSAATexture sets the MSAA resolve source texture.
	//
	// Parameters:
	//   - t: the MSAA texture
	SetMSAATexture(t *wgpu.Texture)

	// MSAATextureView returns the texture view for the MSAA texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the MSAA texture view, or nil if MSAA is off or not initialized
	MSAATextureView() *wgpu.TextureView

	// SetMSAATextureView sets the texture view for the MSAA texture.
	//
	// Parameters:
	//   - tv: the MSAA texture view
	SetMSAATextureView(tv *wgpu.TextureView)

	// DepthTexture returns the depth texture for the offscreen HDR render pass.
	//
	// Returns:
	//   - *wgpu.Texture: the depth texture, or nil if not initialized
	DepthTexture() *wgpu.Texture

	// SetDepthTexture sets the depth texture for the offscreen HDR render pass.
	//
	// Parameters:
	//   - t: the depth texture
	SetDepthTexture(t *wgpu.Texture)

	// DepthTextureView returns the texture view for the offscreen depth texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the depth texture view, or nil if not initialized
	DepthTextureView() *wgpu.TextureView

	// SetDepthTextureView sets the texture view for the offscreen depth texture.
	//
	// Parameters:
	//   - tv: the depth texture view
	SetDepthTextureView(tv *wgpu.TextureView)

	// LinearSampler returns the linear sampler used for sampling the HDR and SSR
	// textures in the composition fragment shader.
	//
	// Returns:
	//   - *wgpu.Sampler: the linear sampler, or nil if not initialized
	LinearSampler() *wgpu.Sampler

	// SetLinearSampler sets the linear sampler for composition texture sampling.
	//
	// Parameters:
	//   - s: the linear sampler
	SetLinearSampler(s *wgpu.Sampler)

	// Resize updates the screen dimensions for texture sizing. Existing
	// textures are not automatically recreated — call the appropriate texture
	// creation method if the dimensions change while the handler is enabled.
	//
	// Parameters:
	//   - width: the new screen width in pixels
	//   - height: the new screen height in pixels
	Resize(width, height int)
}

type CompositionHandlerOption func(*compositionHandlerImpl)

type GBufferHandler interface {
	// Enabled returns whether the G-Buffer subsystem has been GPU-initialized
	// and is ready for rendering.
	//
	// Returns:
	//   - bool: true if G-Buffer GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the G-Buffer subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// ScreenWidth returns the current screen width in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen width
	ScreenWidth() int

	// ScreenHeight returns the current screen height in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen height
	ScreenHeight() int

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// PositionTexture returns the RGBA16Float texture storing world-space
	// position (XYZ) and linear depth (W).
	//
	// Returns:
	//   - *wgpu.Texture: the position texture, or nil if not initialized
	PositionTexture() *wgpu.Texture

	// SetPositionTexture sets the position MRT texture.
	//
	// Parameters:
	//   - t: the position texture
	SetPositionTexture(t *wgpu.Texture)

	// PositionTextureView returns the texture view for the position texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the position texture view, or nil if not initialized
	PositionTextureView() *wgpu.TextureView

	// SetPositionTextureView sets the texture view for the position texture.
	//
	// Parameters:
	//   - tv: the position texture view
	SetPositionTextureView(tv *wgpu.TextureView)

	// NormalTexture returns the RGBA16Float texture storing world-space
	// normals (XYZ packed to [0,1]) and roughness (W).
	//
	// Returns:
	//   - *wgpu.Texture: the normal texture, or nil if not initialized
	NormalTexture() *wgpu.Texture

	// SetNormalTexture sets the normal MRT texture.
	//
	// Parameters:
	//   - t: the normal texture
	SetNormalTexture(t *wgpu.Texture)

	// NormalTextureView returns the texture view for the normal texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the normal texture view, or nil if not initialized
	NormalTextureView() *wgpu.TextureView

	// SetNormalTextureView sets the texture view for the normal texture.
	//
	// Parameters:
	//   - tv: the normal texture view
	SetNormalTextureView(tv *wgpu.TextureView)

	// AlbedoTexture returns the RGBA8Unorm texture storing albedo (RGB)
	// and metallic (A).
	//
	// Returns:
	//   - *wgpu.Texture: the albedo texture, or nil if not initialized
	AlbedoTexture() *wgpu.Texture

	// SetAlbedoTexture sets the albedo MRT texture.
	//
	// Parameters:
	//   - t: the albedo texture
	SetAlbedoTexture(t *wgpu.Texture)

	// AlbedoTextureView returns the texture view for the albedo texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the albedo texture view, or nil if not initialized
	AlbedoTextureView() *wgpu.TextureView

	// SetAlbedoTextureView sets the texture view for the albedo texture.
	//
	// Parameters:
	//   - tv: the albedo texture view
	SetAlbedoTextureView(tv *wgpu.TextureView)

	// DepthTexture returns the Depth24Plus texture used for depth testing
	// during the G-Buffer pass.
	//
	// Returns:
	//   - *wgpu.Texture: the depth texture, or nil if not initialized
	DepthTexture() *wgpu.Texture

	// SetDepthTexture sets the depth texture for the G-Buffer pass.
	//
	// Parameters:
	//   - t: the depth texture
	SetDepthTexture(t *wgpu.Texture)

	// DepthTextureView returns the texture view for the G-Buffer depth texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the depth texture view, or nil if not initialized
	DepthTextureView() *wgpu.TextureView

	// SetDepthTextureView sets the texture view for the G-Buffer depth texture.
	//
	// Parameters:
	//   - tv: the depth texture view
	SetDepthTextureView(tv *wgpu.TextureView)

	// Resize updates the screen dimensions for texture sizing. Existing
	// textures are not automatically recreated — call the appropriate texture
	// creation method if the dimensions change while the handler is enabled.
	//
	// Parameters:
	//   - width: the new screen width in pixels
	//   - height: the new screen height in pixels
	Resize(width, height int)
}

type GBufferHandlerOption func(*gBufferHandlerImpl)

type GPUBlurParams struct {
	Direction    [2]int32 // (1,0) for horizontal, (0,1) for vertical
	Radius       int32    // half-width of the box filter kernel in texels
	GBufferScale int32    // coordinate multiplier for depth texture lookups (1 = full-res, 2 = half-res SSAO)
}

type GPUCompositionParams struct {
	ToneMappingEnabled uint32
	Exposure           float32
	// contains filtered or unexported fields
}

type GPUGBufferOutput struct {
	Position [4]float32 // offset  0: world XYZ + linear depth in W (16 bytes)
	Normal   [4]float32 // offset 16: world normal XYZ (packed [0,1]) + roughness in W (16 bytes)
	Albedo   [4]float32 // offset 32: albedo RGB + metallic in A (16 bytes)
}

type GPUIrradianceProbe struct {
	Position [4]float32  // offset   0: world xyz + status flags in w (0=inactive, 1=active)
	SH_R     [12]float32 // offset  16: L2 SH coefficients for red (indices 0-8 used, 9-11 padding)
	SH_G     [12]float32 // offset  64: L2 SH coefficients for green (indices 0-8 used, 9-11 padding)
	SH_B     [12]float32 // offset 112: L2 SH coefficients for blue (indices 0-8 used, 9-11 padding)
}

type GPULight struct {
	Position     [3]float32 // offset  0: world-space position (point/spot) or unused (directional)
	LightType    uint32     // offset 12: 0 = directional, 1 = point, 2 = spot
	Color        [3]float32 // offset 16: RGB color
	Intensity    float32    // offset 28: scalar multiplier
	Direction    [3]float32 // offset 32: normalized direction (directional/spot) or unused (point)
	LightRange   float32    // offset 44: attenuation cutoff distance
	InnerCone    float32    // offset 48: cos(inner half-angle) for spot
	OuterCone    float32    // offset 52: cos(outer half-angle) for spot
	CastsShadows uint32     // offset 56: 1 = casts shadows, 0 = does not
	// contains filtered or unexported fields
}

type GPULightCullUniforms struct {
	InvProj      [16]float32 // inverse projection matrix
	ViewMatrix   [16]float32 // camera view matrix
	TileCountX   uint32
	TileCountY   uint32
	ScreenWidth  uint32
	ScreenHeight uint32
	LightCount   uint32
	Near         float32
	Far          float32
	// contains filtered or unexported fields
}

type GPULightHeader struct {
	AmbientColor [3]float32 // offset 0: scene ambient RGB
	LightCount   uint32     // offset 12: number of active lights following the header
}

type GPUProbeBakeCamera struct {
	ViewProj       [16]float32 // offset  0: cubemap face view-projection matrix (column-major)
	CameraPosition [3]float32  // offset 64: probe world-space position
	// contains filtered or unexported fields
}

type GPUProbeGridParams struct {
	GridMin     [3]float32 // offset  0: world-space minimum corner of the probe grid
	ProbeCountX uint32     // offset 12: number of probes along the X axis
	GridMax     [3]float32 // offset 16: world-space maximum corner of the probe grid
	ProbeCountY uint32     // offset 28: number of probes along the Y axis
	Spacing     [3]float32 // offset 32: world-space distance between adjacent probes per axis
	ProbeCountZ uint32     // offset 44: number of probes along the Z axis
	TotalProbes uint32     // offset 48: total number of probes (X × Y × Z)
	// contains filtered or unexported fields
}

type GPUSATParams struct {
	Direction [2]int32 // (1,0) for horizontal, (0,1) for vertical
	Offset    int32    // 2^k step offset for recursive doubling; 0 = precision distribution pass
	// contains filtered or unexported fields
}

type GPUSHProjectParams struct {
	ProbeIndex uint32
	FaceIndex  uint32
	Resolution uint32
	// contains filtered or unexported fields
}

type GPUSSAOParams struct {
	Projection   [16]float32 // offset   0: view-projection matrix (column-major)
	InvViewProj  [16]float32 // offset  64: inverse view-projection matrix (column-major)
	Radius       float32     // offset 128: hemisphere sample radius in world units
	Bias         float32     // offset 132: depth comparison bias to prevent self-occlusion
	Power        float32     // offset 136: exponent applied to the final AO value
	SampleCount  uint32      // offset 140: number of hemisphere samples (max 32)
	ScreenWidth  float32     // offset 144: screen width in pixels (SSAO output resolution)
	ScreenHeight float32     // offset 148: screen height in pixels (SSAO output resolution)
	GBufferScale float32     // offset 152: coordinate multiplier for G-Buffer texture lookups (1.0 = full-res, 2.0 = half-res)

	CameraPosition [3]float32 // offset 160: world-space camera position for linear depth computation
	// contains filtered or unexported fields
}

type GPUSSRParams struct {
	Projection      [16]float32 // offset   0: projection matrix (column-major)
	InvProjection   [16]float32 // offset  64: inverse projection matrix (column-major)
	View            [16]float32 // offset 128: view matrix (column-major)
	MaxDistance     float32     // offset 192: maximum ray march distance in view space
	Thickness       float32     // offset 196: depth thickness tolerance for hit detection
	Stride          float32     // offset 200: step stride multiplier for ray march (unused in Hi-Z mode)
	MaxSteps        uint32      // offset 204: maximum number of ray march steps
	ScreenWidth     float32     // offset 208: screen width in pixels
	ScreenHeight    float32     // offset 212: screen height in pixels
	RoughnessCutoff float32     // offset 216: roughness above which SSR is skipped
	HiZMipCount     uint32      // offset 220: number of Hi-Z mip levels in the depth pyramid
}

type GPUShadowData struct {
	LightVP             [16]float32 // orthographic view-projection from light's perspective
	LightView           [16]float32 // view-only matrix (no projection) for linear depth
	TexelSize           [2]float32  // 1.0 / shadow_map_resolution for VSM texel calculations
	Bias                float32     // depth comparison bias to reduce shadow acne
	NormalBias          float32     // world-space normal-offset distance for shadow lookup
	ShadowNear          float32     // near plane for linear depth normalization
	ShadowFar           float32     // far plane for linear depth normalization
	MinVariance         float32     // minimum variance clamp for Chebyshev's inequality (VSM)
	LightBleedReduction float32     // exponent to reduce light-bleeding artifacts (VSM)
	LightSize           float32     // world-space light size for PCSS penumbra estimation
	ShadowHalfExtent    float32     // orthographic frustum half-size for PCSS world-to-texel conversion
	// contains filtered or unexported fields
}

type GPUShadowUniform struct {
	LightVP    [16]float32 // orthographic view-projection from light's perspective
	LightView  [16]float32 // view-only matrix (no projection) for linear depth in VSM
	ShadowNear float32     // near plane for linear depth normalization
	ShadowFar  float32     // far plane for linear depth normalization
}

type GPUTileUniforms struct {
	TileCountX       uint32
	MaxLightsPerTile uint32
}

type IrradianceProbeGrid interface {
	// Enabled returns whether the probe grid subsystem has been GPU-initialized
	// and is ready for rendering.
	//
	// Returns:
	//   - bool: true if probe grid GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the probe grid subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// CountX returns the number of probes along the X axis.
	//
	// Returns:
	//   - int: the probe count along X
	CountX() int

	// CountY returns the number of probes along the Y axis.
	//
	// Returns:
	//   - int: the probe count along Y
	CountY() int

	// CountZ returns the number of probes along the Z axis.
	//
	// Returns:
	//   - int: the probe count along Z
	CountZ() int

	// TotalProbes returns the total number of probes in the grid (X × Y × Z).
	//
	// Returns:
	//   - int: the total probe count
	TotalProbes() int

	// GridMin returns the world-space minimum corner of the probe grid.
	//
	// Returns:
	//   - [3]float32: the minimum corner (x, y, z)
	GridMin() [3]float32

	// GridMax returns the world-space maximum corner of the probe grid.
	//
	// Returns:
	//   - [3]float32: the maximum corner (x, y, z)
	GridMax() [3]float32

	// Spacing returns the world-space distance between adjacent probes per axis.
	//
	// Returns:
	//   - [3]float32: the spacing (x, y, z)
	Spacing() [3]float32

	// BakeResolution returns the cubemap face resolution in pixels per edge.
	//
	// Returns:
	//   - int: the cubemap face resolution
	BakeResolution() int

	// ProbeIndex computes the flat array index for the probe at grid position
	// (x, y, z). The layout is: index = x + y*countX + z*countX*countY.
	//
	// Parameters:
	//   - x: the X grid coordinate
	//   - y: the Y grid coordinate
	//   - z: the Z grid coordinate
	//
	// Returns:
	//   - int: the flat array index
	ProbeIndex(x, y, z int) int

	// Probe returns a copy of the probe at the given flat index.
	//
	// Parameters:
	//   - index: the flat probe index
	//
	// Returns:
	//   - GPUIrradianceProbe: the probe data
	Probe(index int) GPUIrradianceProbe

	// Probes returns a reference to the full slice of CPU-side probe data.
	//
	// Returns:
	//   - []GPUIrradianceProbe: all probes in the grid
	Probes() []GPUIrradianceProbe

	// SetProbe writes the given probe data at the specified flat index and
	// marks the probe as dirty for re-baking.
	//
	// Parameters:
	//   - index: the flat probe index
	//   - p: the probe data to set
	SetProbe(index int, p GPUIrradianceProbe)

	// SetProbes replaces the entire CPU-side probe slice.
	//
	// Parameters:
	//   - probes: the new probe data
	SetProbes(probes []GPUIrradianceProbe)

	// DirtyProbes returns the indices of probes that need re-baking.
	//
	// Returns:
	//   - []int: dirty probe indices
	DirtyProbes() []int

	// SetDirtyProbes replaces the dirty probe index list.
	//
	// Parameters:
	//   - indices: the new list of dirty probe indices
	SetDirtyProbes(indices []int)

	// MarkAllDirty adds every probe index to the dirty list.
	MarkAllDirty()

	// ClearDirtyProbes empties the dirty probe list.
	ClearDirtyProbes()

	// ProbeBuffer returns the GPU storage buffer holding the serialized probe array.
	//
	// Returns:
	//   - *wgpu.Buffer: the probe storage buffer, or nil if not initialized
	ProbeBuffer() *wgpu.Buffer

	// SetProbeBuffer sets the GPU storage buffer for probes.
	//
	// Parameters:
	//   - buf: the probe storage buffer
	SetProbeBuffer(buf *wgpu.Buffer)

	// GridParamsBuffer returns the GPU uniform buffer holding the serialized
	// GPUProbeGridParams data.
	//
	// Returns:
	//   - *wgpu.Buffer: the grid params uniform buffer, or nil if not initialized
	GridParamsBuffer() *wgpu.Buffer

	// SetGridParamsBuffer sets the GPU uniform buffer for grid parameters.
	//
	// Parameters:
	//   - buf: the grid params uniform buffer
	SetGridParamsBuffer(buf *wgpu.Buffer)

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// Bgp retrieves the bind group provider associated with the given key.
	// Returns nil if the key does not exist.
	//
	// Valid keys:
	//   - "probe_grid": lit shader bind group (probe buffer + grid params)
	//   - "probe_sh_project": SH projection compute shader bind group
	//   - "probe_bake_camera": bake pass camera uniform bind group
	//
	// Parameters:
	//   - key: the bind group provider name
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of bind group providers.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all registered providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// SetBgp stores a bind group provider under the given key.
	//
	// Parameters:
	//   - key: the bind group provider name
	//   - bgp: the bind group provider
	SetBgp(key string, bgp bind_group_provider.BindGroupProvider)

	// BakeColorTexture returns the RGBA8Unorm texture used as the color
	// attachment during cubemap face baking.
	//
	// Returns:
	//   - *wgpu.Texture: the bake color texture, or nil if not initialized
	BakeColorTexture() *wgpu.Texture

	// SetBakeColorTexture sets the cubemap bake color texture.
	//
	// Parameters:
	//   - t: the bake color texture
	SetBakeColorTexture(t *wgpu.Texture)

	// BakeColorTextureView returns the texture view for the bake color texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the bake color texture view, or nil if not initialized
	BakeColorTextureView() *wgpu.TextureView

	// SetBakeColorTextureView sets the texture view for the bake color texture.
	//
	// Parameters:
	//   - tv: the bake color texture view
	SetBakeColorTextureView(tv *wgpu.TextureView)

	// BakeDepthTexture returns the depth texture used during cubemap face baking.
	//
	// Returns:
	//   - *wgpu.Texture: the bake depth texture, or nil if not initialized
	BakeDepthTexture() *wgpu.Texture

	// SetBakeDepthTexture sets the cubemap bake depth texture.
	//
	// Parameters:
	//   - t: the bake depth texture
	SetBakeDepthTexture(t *wgpu.Texture)

	// BakeDepthTextureView returns the texture view for the bake depth texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the bake depth texture view, or nil if not initialized
	BakeDepthTextureView() *wgpu.TextureView

	// SetBakeDepthTextureView sets the texture view for the bake depth texture.
	//
	// Parameters:
	//   - tv: the bake depth texture view
	SetBakeDepthTextureView(tv *wgpu.TextureView)

	// BuildGPUGridParams computes and returns the GPUProbeGridParams uniform
	// data matching the current grid configuration.
	//
	// Returns:
	//   - GPUProbeGridParams: the serializable grid parameter block
	BuildGPUGridParams() GPUProbeGridParams
}

type IrradianceProbeGridOption func(*irradianceProbeGridImpl)

type Light interface {
	common.Delegate[Light]

	// Type returns the kind of light source.
	//
	// Returns:
	//   - LightType: the light type (directional, point, or spot)
	Type() LightType

	// Position returns the world-space position of the light.
	// Meaningless for directional lights.
	//
	// Returns:
	//   - [3]float32: position as (x, y, z)
	Position() [3]float32

	// Direction returns the normalized direction of the light.
	// For directional lights this is the light direction. For spot lights this
	// is the cone axis. Meaningless for point lights.
	//
	// Returns:
	//   - [3]float32: normalized direction as (x, y, z)
	Direction() [3]float32

	// Color returns the RGB color of the light.
	//
	// Returns:
	//   - [3]float32: color as (r, g, b)
	Color() [3]float32

	// Intensity returns the scalar intensity multiplier for the light.
	//
	// Returns:
	//   - float32: the intensity value
	Intensity() float32

	// Range returns the maximum attenuation distance for point and spot lights.
	// Beyond this distance the light contributes zero energy. Meaningless for
	// directional lights.
	//
	// Returns:
	//   - float32: the range value
	Range() float32

	// InnerCone returns the cosine of the inner cone half-angle for spot lights.
	// Fragments within this angle receive full intensity. Meaningless for
	// directional and point lights.
	//
	// Returns:
	//   - float32: cos(inner half-angle)
	InnerCone() float32

	// OuterCone returns the cosine of the outer cone half-angle for spot lights.
	// Fragments outside this angle receive zero intensity from the spot cone
	// falloff. Meaningless for directional and point lights.
	//
	// Returns:
	//   - float32: cos(outer half-angle)
	OuterCone() float32

	// Enabled returns whether this light is active for rendering.
	// Disabled lights are skipped during GPU buffer marshaling.
	//
	// Returns:
	//   - bool: true if the light is enabled
	Enabled() bool

	// Ephemeral returns whether this light is a short-lived particle-emitted light.
	// Ephemeral lights are not persisted in the scene's light registry and are
	// managed by their owning particle system.
	//
	// Returns:
	//   - bool: true if ephemeral
	Ephemeral() bool

	// CastsShadows returns whether this light is eligible for shadow map generation.
	// Shadow-casting lights have their depth pass rendered each frame, which is
	// expensive. Most ephemeral and distant lights should have this disabled.
	//
	// Returns:
	//   - bool: true if the light casts shadows
	CastsShadows() bool

	// SetPosition sets the world-space position of the light.
	//
	// Parameters:
	//   - x, y, z: position components
	SetPosition(x, y, z float32)

	// SetDirection sets the direction of the light and normalizes it.
	//
	// Parameters:
	//   - x, y, z: direction components (will be normalized)
	SetDirection(x, y, z float32)

	// SetColor sets the RGB color of the light.
	//
	// Parameters:
	//   - r, g, b: color components
	SetColor(r, g, b float32)

	// SetIntensity sets the scalar intensity multiplier.
	//
	// Parameters:
	//   - intensity: the intensity value
	SetIntensity(intensity float32)

	// SetRange sets the maximum attenuation distance.
	//
	// Parameters:
	//   - lightRange: the range value
	SetRange(lightRange float32)

	// SetSpotCone sets the inner and outer cone half-angles for spot lights.
	// Angles are specified in degrees and stored internally as cosines.
	//
	// Parameters:
	//   - innerDeg: inner cone half-angle in degrees
	//   - outerDeg: outer cone half-angle in degrees
	SetSpotCone(innerDeg, outerDeg float32)

	// SetEnabled enables or disables the light for rendering.
	//
	// Parameters:
	//   - enabled: true to enable
	SetEnabled(enabled bool)

	// SetEphemeral marks the light as ephemeral (particle-emitted).
	//
	// Parameters:
	//   - ephemeral: true if ephemeral
	SetEphemeral(ephemeral bool)

	// SetCastsShadows sets whether the light is eligible for shadow mapping.
	//
	// Parameters:
	//   - castsShadows: true to enable shadow casting
	SetCastsShadows(castsShadows bool)
}

type LightBuilderOption func(*lightImpl)

type LightType int

type LightingHandler interface {
	// Enabled returns whether the lighting subsystem has been GPU-initialized and
	// is ready for rendering.
	//
	// Returns:
	//   - bool: true if lighting GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the lighting subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// Lights returns a copy of the current light list.
	//
	// Returns:
	//   - []Light: a copy of the lights registered with the handler
	Lights() []Light

	// AddLight appends a light to the handler's light list.
	//
	// Parameters:
	//   - l: the Light to add
	AddLight(l Light)

	// RemoveLight removes a light from the handler's list by reference equality.
	//
	// Parameters:
	//   - l: the Light to remove
	RemoveLight(l Light)

	// AmbientColor returns the scene's ambient light color.
	//
	// Returns:
	//   - [3]float32: the ambient RGB color
	AmbientColor() [3]float32

	// SetAmbientColor sets the scene's ambient light color.
	//
	// Parameters:
	//   - color: the ambient RGB color
	SetAmbientColor(color [3]float32)

	// Bgp retrieves the BindGroupProvider associated with the given key.
	// Returns nil if the key does not exist.
	//
	// Known keys:
	//   - "lights": light storage buffer BGP
	//   - "shadow_data": shadow depth pass BGP (light VP uniform)
	//   - "shadow_lit": lit pass shadow sampling BGP (texture + sampler + uniform)
	//   - "light_cull": compute shader cull BGP
	//   - "tile_lit": fragment shader tile data BGP
	//   - "ssao_lit": lit pass SSAO occlusion texture + sampler BGP (real or fallback white)
	//
	// Parameters:
	//   - key: the bind group provider identifier
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of bind group providers.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all registered providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// ShadowHalfExtent returns the orthographic half-extent of the directional shadow frustum
	// in world units.
	//
	// Returns:
	//   - float32: the shadow frustum half-extent
	ShadowHalfExtent() float32

	// ShadowNear returns the near plane distance for the directional shadow projection.
	//
	// Returns:
	//   - float32: the shadow near plane
	ShadowNear() float32

	// ShadowFar returns the far plane distance for the directional shadow projection.
	//
	// Returns:
	//   - float32: the shadow far plane
	ShadowFar() float32

	// ShadowBias returns the constant depth bias applied to shadow comparisons.
	//
	// Returns:
	//   - float32: the shadow bias
	ShadowBias() float32

	// ShadowNormalBiasScale returns the multiplier applied to the shadow map texel
	// world-size to derive the normal-offset bias.
	//
	// Returns:
	//   - float32: the normal bias scale
	ShadowNormalBiasScale() float32

	// ShadowMapResolution returns the width and height in texels of the shadow depth texture.
	//
	// Returns:
	//   - int: the shadow map resolution
	ShadowMapResolution() int

	// VSMTexture returns the RG32Float variance shadow map texture.
	//
	// Returns:
	//   - *wgpu.Texture: the VSM texture, or nil if not initialized
	VSMTexture() *wgpu.Texture

	// SetVSMTexture sets the RG32Float variance shadow map texture.
	//
	// Parameters:
	//   - t: the VSM texture
	SetVSMTexture(t *wgpu.Texture)

	// VSMTextureView returns the texture view for the VSM texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the VSM texture view, or nil if not initialized
	VSMTextureView() *wgpu.TextureView

	// SetVSMTextureView sets the texture view for the VSM texture.
	//
	// Parameters:
	//   - tv: the VSM texture view
	SetVSMTextureView(tv *wgpu.TextureView)

	// VSMScratchTexture returns the scratch RG32Float texture used as intermediate
	// storage during the separable blur pass.
	//
	// Returns:
	//   - *wgpu.Texture: the scratch texture, or nil if not initialized
	VSMScratchTexture() *wgpu.Texture

	// SetVSMScratchTexture sets the scratch texture used during the separable blur pass.
	//
	// Parameters:
	//   - t: the scratch texture
	SetVSMScratchTexture(t *wgpu.Texture)

	// VSMScratchTextureView returns the texture view for the scratch texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the scratch texture view, or nil if not initialized
	VSMScratchTextureView() *wgpu.TextureView

	// SetVSMScratchTextureView sets the texture view for the scratch texture.
	//
	// Parameters:
	//   - tv: the scratch texture view
	SetVSMScratchTextureView(tv *wgpu.TextureView)

	// VSMAuxDepthTexture returns the auxiliary Depth32Float texture used for hardware
	// z-testing during the VSM shadow render pass.
	//
	// Returns:
	//   - *wgpu.Texture: the auxiliary depth texture, or nil if not initialized
	VSMAuxDepthTexture() *wgpu.Texture

	// SetVSMAuxDepthTexture sets the auxiliary depth texture for the VSM shadow pass.
	//
	// Parameters:
	//   - t: the auxiliary depth texture
	SetVSMAuxDepthTexture(t *wgpu.Texture)

	// VSMAuxDepthTextureView returns the texture view for the auxiliary depth texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the auxiliary depth texture view, or nil if not initialized
	VSMAuxDepthTextureView() *wgpu.TextureView

	// SetVSMAuxDepthTextureView sets the texture view for the auxiliary depth texture.
	//
	// Parameters:
	//   - tv: the auxiliary depth texture view
	SetVSMAuxDepthTextureView(tv *wgpu.TextureView)

	// VSMLinearSampler returns the linear sampler used for VSM texture lookups in
	// the lit fragment shader (replaces the comparison sampler used by PCF).
	//
	// Returns:
	//   - *wgpu.Sampler: the linear sampler, or nil if not initialized
	VSMLinearSampler() *wgpu.Sampler

	// SetVSMLinearSampler sets the linear sampler used for VSM texture lookups.
	//
	// Parameters:
	//   - s: the linear sampler
	SetVSMLinearSampler(s *wgpu.Sampler)

	// VSMBlurRadius returns the half-width (in texels) of the separable blur
	// applied to the variance shadow map.
	//
	// Returns:
	//   - int: the blur radius
	VSMBlurRadius() int

	// VSMMinVariance returns the minimum variance clamp for Chebyshev's inequality.
	//
	// Returns:
	//   - float32: the minimum variance
	VSMMinVariance() float32

	// VSMLightBleedReduction returns the exponent applied to the raw Chebyshev shadow
	// probability to reduce light-bleeding artifacts.
	//
	// Returns:
	//   - float32: the light bleed reduction exponent
	VSMLightBleedReduction() float32

	// VSMLightSize returns the world-space area light size used for PCSS penumbra estimation.
	//
	// Returns:
	//   - float32: the light size
	VSMLightSize() float32

	// PCSSEnabled returns whether PCSS contact-hardening soft shadows are enabled.
	// PCSS requires VSM to also be enabled.
	//
	// Returns:
	//   - bool: true if PCSS is enabled
	PCSSEnabled() bool

	// SetPCSSEnabled sets whether PCSS contact-hardening soft shadows are enabled.
	//
	// Parameters:
	//   - enabled: true to enable PCSS
	SetPCSSEnabled(enabled bool)

	// SATTextureA returns the first RGBA32Float SAT ping-pong texture.
	//
	// Returns:
	//   - *wgpu.Texture: SAT texture A, or nil if not initialized
	SATTextureA() *wgpu.Texture

	// SetSATTextureA sets the first SAT ping-pong texture.
	//
	// Parameters:
	//   - t: SAT texture A
	SetSATTextureA(t *wgpu.Texture)

	// SATTextureAView returns the texture view for SAT texture A.
	//
	// Returns:
	//   - *wgpu.TextureView: SAT texture A view, or nil if not initialized
	SATTextureAView() *wgpu.TextureView

	// SetSATTextureAView sets the texture view for SAT texture A.
	//
	// Parameters:
	//   - tv: SAT texture A view
	SetSATTextureAView(tv *wgpu.TextureView)

	// SATTextureB returns the second RGBA32Float SAT ping-pong texture.
	//
	// Returns:
	//   - *wgpu.Texture: SAT texture B, or nil if not initialized
	SATTextureB() *wgpu.Texture

	// SetSATTextureB sets the second SAT ping-pong texture.
	//
	// Parameters:
	//   - t: SAT texture B
	SetSATTextureB(t *wgpu.Texture)

	// SATTextureBView returns the texture view for SAT texture B.
	//
	// Returns:
	//   - *wgpu.TextureView: SAT texture B view, or nil if not initialized
	SATTextureBView() *wgpu.TextureView

	// SetSATTextureBView sets the texture view for SAT texture B.
	//
	// Parameters:
	//   - tv: SAT texture B view
	SetSATTextureBView(tv *wgpu.TextureView)

	// ScreenWidth returns the current screen width in pixels used for tile calculations.
	//
	// Returns:
	//   - int: the screen width
	ScreenWidth() int

	// ScreenHeight returns the current screen height in pixels used for tile calculations.
	//
	// Returns:
	//   - int: the screen height
	ScreenHeight() int

	// TileCountX returns the number of Forward+ tile columns for the current screen width.
	//
	// Returns:
	//   - uint32: the tile column count
	TileCountX() uint32

	// TileCountY returns the number of Forward+ tile rows for the current screen height.
	//
	// Returns:
	//   - uint32: the tile row count
	TileCountY() uint32

	// Resize updates the screen dimensions and recalculates tile counts for Forward+
	// light culling. This should be called when the window is resized.
	//
	// Parameters:
	//   - width: the new screen width in pixels
	//   - height: the new screen height in pixels
	Resize(width, height int)

	// GBufferHandler returns the GBufferHandler attached to this lighting
	// subsystem, or nil if no G-Buffer pre-pass is configured.
	//
	// Returns:
	//   - GBufferHandler: the G-Buffer handler, or nil
	GBufferHandler() GBufferHandler

	// SSAOHandler returns the SSAOHandler attached to this lighting
	// subsystem, or nil if SSAO is not configured.
	//
	// Returns:
	//   - SSAOHandler: the SSAO handler, or nil
	SSAOHandler() SSAOHandler

	// ProbeGrid returns the IrradianceProbeGrid attached to this lighting
	// subsystem, or nil if probe-based GI is not configured.
	//
	// Returns:
	//   - IrradianceProbeGrid: the probe grid handler, or nil
	ProbeGrid() IrradianceProbeGrid

	// CompositionHandler returns the CompositionHandler attached to this lighting
	// subsystem, or nil if composition/tone mapping is not configured.
	//
	// Returns:
	//   - CompositionHandler: the composition handler, or nil
	CompositionHandler() CompositionHandler

	// SSRHandler returns the SSRHandler attached to this lighting
	// subsystem, or nil if screen-space reflections are not configured.
	//
	// Returns:
	//   - SSRHandler: the SSR handler, or nil
	SSRHandler() SSRHandler
}

type LightingHandlerOption func(*lightingHandlerImpl)

type SSAOHandler interface {
	// Enabled returns whether the SSAO subsystem has been GPU-initialized
	// and is ready for rendering.
	//
	// Returns:
	//   - bool: true if SSAO GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the SSAO subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// ScreenWidth returns the current screen width in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen width
	ScreenWidth() int

	// ScreenHeight returns the current screen height in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen height
	ScreenHeight() int

	// SampleCount returns the number of hemisphere samples per pixel.
	//
	// Returns:
	//   - int: the sample count (1–32)
	SampleCount() int

	// Radius returns the hemisphere sampling radius in world-space units.
	//
	// Returns:
	//   - float32: the sampling radius
	Radius() float32

	// Bias returns the depth comparison bias used to prevent self-occlusion.
	//
	// Returns:
	//   - float32: the depth bias
	Bias() float32

	// Power returns the exponent applied to the final AO value.
	//
	// Returns:
	//   - float32: the power exponent
	Power() float32

	// BlurRadius returns the half-width of the bilateral blur kernel in texels.
	//
	// Returns:
	//   - int: the blur kernel half-width
	BlurRadius() int

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// Bgp retrieves the bind group provider associated with the given key.
	// Returns nil if the key does not exist.
	//
	// Parameters:
	//   - key: the bind group provider name
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of bind group providers.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all registered providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// SetBgp stores a bind group provider under the given key.
	//
	// Parameters:
	//   - key: the bind group provider name
	//   - bgp: the bind group provider
	SetBgp(key string, bgp bind_group_provider.BindGroupProvider)

	// RawTexture returns the R8Unorm texture storing the raw (pre-blur) SSAO
	// occlusion values.
	//
	// Returns:
	//   - *wgpu.Texture: the raw SSAO texture, or nil if not initialized
	RawTexture() *wgpu.Texture

	// SetRawTexture sets the raw SSAO texture.
	//
	// Parameters:
	//   - t: the raw SSAO texture
	SetRawTexture(t *wgpu.Texture)

	// RawTextureView returns the texture view for the raw SSAO texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the raw SSAO texture view, or nil if not initialized
	RawTextureView() *wgpu.TextureView

	// SetRawTextureView sets the texture view for the raw SSAO texture.
	//
	// Parameters:
	//   - tv: the raw SSAO texture view
	SetRawTextureView(tv *wgpu.TextureView)

	// BlurredTexture returns the R8Unorm texture storing the blurred (final)
	// SSAO occlusion values bound to the lit shader.
	//
	// Returns:
	//   - *wgpu.Texture: the blurred SSAO texture, or nil if not initialized
	BlurredTexture() *wgpu.Texture

	// SetBlurredTexture sets the blurred SSAO texture.
	//
	// Parameters:
	//   - t: the blurred SSAO texture
	SetBlurredTexture(t *wgpu.Texture)

	// BlurredTextureView returns the texture view for the blurred SSAO texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the blurred SSAO texture view, or nil if not initialized
	BlurredTextureView() *wgpu.TextureView

	// SetBlurredTextureView sets the texture view for the blurred SSAO texture.
	//
	// Parameters:
	//   - tv: the blurred SSAO texture view
	SetBlurredTextureView(tv *wgpu.TextureView)

	// ScratchTexture returns the R8Unorm scratch texture used as an intermediate
	// target between the horizontal and vertical blur passes.
	//
	// Returns:
	//   - *wgpu.Texture: the scratch texture, or nil if not initialized
	ScratchTexture() *wgpu.Texture

	// SetScratchTexture sets the scratch texture for the blur passes.
	//
	// Parameters:
	//   - t: the scratch texture
	SetScratchTexture(t *wgpu.Texture)

	// ScratchTextureView returns the texture view for the scratch texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the scratch texture view, or nil if not initialized
	ScratchTextureView() *wgpu.TextureView

	// SetScratchTextureView sets the texture view for the scratch texture.
	//
	// Parameters:
	//   - tv: the scratch texture view
	SetScratchTextureView(tv *wgpu.TextureView)

	// NoiseTexture returns the 4×4 RGBA16Float texture storing random rotation
	// vectors for the SSAO sample kernel.
	//
	// Returns:
	//   - *wgpu.Texture: the noise texture, or nil if not initialized
	NoiseTexture() *wgpu.Texture

	// SetNoiseTexture sets the SSAO noise texture.
	//
	// Parameters:
	//   - t: the noise texture
	SetNoiseTexture(t *wgpu.Texture)

	// NoiseTextureView returns the texture view for the noise texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the noise texture view, or nil if not initialized
	NoiseTextureView() *wgpu.TextureView

	// SetNoiseTextureView sets the texture view for the noise texture.
	//
	// Parameters:
	//   - tv: the noise texture view
	SetNoiseTextureView(tv *wgpu.TextureView)

	// LinearSampler returns the linear sampler used when binding the SSAO
	// blurred texture to the lit fragment shader.
	//
	// Returns:
	//   - *wgpu.Sampler: the linear sampler, or nil if not initialized
	LinearSampler() *wgpu.Sampler

	// SetLinearSampler sets the linear sampler for SSAO texture sampling.
	//
	// Parameters:
	//   - s: the linear sampler
	SetLinearSampler(s *wgpu.Sampler)

	// Resize updates the screen dimensions for texture sizing. Existing
	// textures are not automatically recreated — call the appropriate texture
	// creation method if the dimensions change while the handler is enabled.
	//
	// Parameters:
	//   - width: the new screen width in pixels
	//   - height: the new screen height in pixels
	Resize(width, height int)

	// HalfResolution returns whether SSAO textures are allocated at half the
	// screen resolution for improved performance.
	//
	// Returns:
	//   - bool: true if half-resolution mode is enabled
	HalfResolution() bool

	// SetHalfResolution sets whether SSAO textures should be allocated at half
	// the screen resolution.
	//
	// Parameters:
	//   - enabled: true to enable half-resolution mode
	SetHalfResolution(enabled bool)
}

type SSAOHandlerOption func(*ssaoHandlerImpl)

type SSRHandler interface {
	// Enabled returns whether the SSR subsystem has been GPU-initialized
	// and is ready for rendering.
	//
	// Returns:
	//   - bool: true if SSR GPU resources have been initialized
	Enabled() bool

	// SetEnabled sets whether the SSR subsystem is GPU-initialized.
	//
	// Parameters:
	//   - enabled: true to mark as initialized
	SetEnabled(enabled bool)

	// ScreenWidth returns the current screen width in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen width
	ScreenWidth() int

	// ScreenHeight returns the current screen height in pixels used for texture sizing.
	//
	// Returns:
	//   - int: the screen height
	ScreenHeight() int

	// MaxSteps returns the maximum number of ray march steps per pixel.
	//
	// Returns:
	//   - int: the max step count
	MaxSteps() int

	// MaxDistance returns the maximum ray march distance in view-space units.
	//
	// Returns:
	//   - float32: the max distance
	MaxDistance() float32

	// Thickness returns the depth thickness tolerance for hit detection.
	//
	// Returns:
	//   - float32: the thickness value
	Thickness() float32

	// Stride returns the step stride multiplier for the ray march.
	//
	// Returns:
	//   - float32: the stride multiplier
	Stride() float32

	// RoughnessCutoff returns the roughness value above which SSR is skipped.
	//
	// Returns:
	//   - float32: the roughness cutoff
	RoughnessCutoff() float32

	// PipelineKey retrieves the pipeline key associated with the given name.
	// Returns an empty string if the name does not exist.
	//
	// Parameters:
	//   - name: the pipeline name
	//
	// Returns:
	//   - string: the pipeline key, or empty if not found
	PipelineKey(name string) string

	// PipelineKeys returns the full map of pipeline keys.
	//
	// Returns:
	//   - map[string]string: all registered pipeline name-to-key mappings
	PipelineKeys() map[string]string

	// SetPipelineKey stores a pipeline key under the given name.
	//
	// Parameters:
	//   - name: the pipeline name
	//   - key: the pipeline key
	SetPipelineKey(name, key string)

	// Bgp retrieves the bind group provider associated with the given key.
	// Returns nil if the key does not exist.
	//
	// Parameters:
	//   - key: the bind group provider name
	//
	// Returns:
	//   - bind_group_provider.BindGroupProvider: the provider, or nil if not found
	Bgp(key string) bind_group_provider.BindGroupProvider

	// Bgps returns the full map of bind group providers.
	//
	// Returns:
	//   - map[string]bind_group_provider.BindGroupProvider: all registered providers
	Bgps() map[string]bind_group_provider.BindGroupProvider

	// SetBgp stores a bind group provider under the given key.
	//
	// Parameters:
	//   - key: the bind group provider name
	//   - bgp: the bind group provider
	SetBgp(key string, bgp bind_group_provider.BindGroupProvider)

	// SSRTexture returns the RGBA16Float texture storing the SSR ray march result
	// at half resolution. RGB = reflected color, A = confidence.
	//
	// Returns:
	//   - *wgpu.Texture: the SSR result texture, or nil if not initialized
	SSRTexture() *wgpu.Texture

	// SetSSRTexture sets the SSR result texture.
	//
	// Parameters:
	//   - t: the SSR result texture
	SetSSRTexture(t *wgpu.Texture)

	// SSRTextureView returns the texture view for the SSR result texture.
	//
	// Returns:
	//   - *wgpu.TextureView: the SSR texture view, or nil if not initialized
	SSRTextureView() *wgpu.TextureView

	// SetSSRTextureView sets the texture view for the SSR result texture.
	//
	// Parameters:
	//   - tv: the SSR texture view
	SetSSRTextureView(tv *wgpu.TextureView)

	// LinearSampler returns the linear sampler used when the composition shader
	// samples the SSR result texture.
	//
	// Returns:
	//   - *wgpu.Sampler: the linear sampler, or nil if not initialized
	LinearSampler() *wgpu.Sampler

	// SetLinearSampler sets the linear sampler for SSR texture sampling.
	//
	// Parameters:
	//   - s: the linear sampler
	SetLinearSampler(s *wgpu.Sampler)

	// Resize updates the screen dimensions for texture sizing. Existing
	// textures are not automatically recreated — call the appropriate texture
	// creation method if the dimensions change while the handler is enabled.
	//
	// Parameters:
	//   - width: the new screen width in pixels
	//   - height: the new screen height in pixels
	Resize(width, height int)

	// HiZTexture returns the R32Float Hi-Z depth pyramid texture.
	//
	// Returns:
	//   - *wgpu.Texture: the Hi-Z texture, or nil if not initialized
	HiZTexture() *wgpu.Texture

	// SetHiZTexture sets the Hi-Z depth pyramid texture.
	//
	// Parameters:
	//   - t: the Hi-Z texture
	SetHiZTexture(t *wgpu.Texture)

	// HiZTextureView returns the full mip chain texture view for the Hi-Z pyramid,
	// used by the SSR compute shader to sample at arbitrary mip levels.
	//
	// Returns:
	//   - *wgpu.TextureView: the full mip chain view, or nil if not initialized
	HiZTextureView() *wgpu.TextureView

	// SetHiZTextureView sets the full mip chain texture view for the Hi-Z pyramid.
	//
	// Parameters:
	//   - tv: the full mip chain texture view
	SetHiZTextureView(tv *wgpu.TextureView)

	// HiZMipCount returns the number of mip levels in the Hi-Z depth pyramid.
	//
	// Returns:
	//   - int: the mip level count
	HiZMipCount() int

	// SetHiZMipCount sets the number of mip levels in the Hi-Z depth pyramid.
	//
	// Parameters:
	//   - count: the mip level count
	SetHiZMipCount(count int)

	// HiZMipReadViews returns the per-mip-level texture read views used as
	// input for Hi-Z downsample passes.
	//
	// Returns:
	//   - []*wgpu.TextureView: per-mip read views
	HiZMipReadViews() []*wgpu.TextureView

	// SetHiZMipReadViews sets the per-mip-level texture read views.
	//
	// Parameters:
	//   - views: per-mip read views
	SetHiZMipReadViews(views []*wgpu.TextureView)

	// HiZStorageViews returns the per-mip-level storage texture views used as
	// output for Hi-Z downsample passes.
	//
	// Returns:
	//   - []*wgpu.TextureView: per-mip storage write views
	HiZStorageViews() []*wgpu.TextureView

	// SetHiZStorageViews sets the per-mip-level storage texture views.
	//
	// Parameters:
	//   - views: per-mip storage write views
	SetHiZStorageViews(views []*wgpu.TextureView)
}

type SSRHandlerOption func(*ssrHandlerImpl)