renderer

type MSAASampleCount uint32

type PresentMode int

type Renderer interface {
	common.Delegate[Renderer]

	// Pipeline retrieves the cached Pipeline associated with the given key.
	// If the Pipeline does not exist, this will return nil.
	//
	// Parameters:
	//   - key: the unique identifier for the Pipeline to retrieve
	//
	// Returns:
	//   - pipeline.Pipeline: the Pipeline associated with the key, or nil if not found
	Pipeline(key string) pipeline.Pipeline

	// Pipelines retrieves the entire cache of Pipelines.
	//
	// Returns:
	//   - map[string]pipeline.Pipeline: a map of pipeline keys to their corresponding Pipeline objects
	Pipelines() map[string]pipeline.Pipeline

	// RegisterPipelines registers one or more pipelines by creating the corresponding GPU
	// pipeline objects (render or compute) via the backend, then caching them by PipelineKey.
	// Pipelines whose keys are already registered are skipped to avoid duplicate GPU resource creation.
	//
	// Parameters:
	//   - pipelines: the Pipelines to register
	//
	// Returns:
	//   - error: an error if pipeline creation fails
	RegisterPipelines(pipelines ...pipeline.Pipeline) error

	// SetPipeline adds or updates a Pipeline in the cache with the given key.
	//
	// Parameters:
	//   - key: the unique identifier for the Pipeline to add or update in the cache
	//   - p: the Pipeline to add or update in the cache
	SetPipeline(key string, p pipeline.Pipeline)

	// SetPipelines replaces the entire pipeline cache with the provided map of Pipelines.
	//
	// Parameters:
	//   - pipelines: a map of pipeline keys to their corresponding Pipeline objects to set as the new cache
	SetPipelines(pipelines map[string]pipeline.Pipeline)

	// Resize configures the underlying backend to handle a new surface size.
	// This should be called when re-sizing the window or when the surface size should change.
	//
	// Parameters:
	//   - width: the new width of the surface in pixels
	//   - height: the new height of the surface in pixels
	Resize(width, height int)

	// InitMeshBuffers creates GPU vertex and index buffers from raw byte data and stores them
	// on the given BindGroupProvider for later use in draw calls.
	//
	// Parameters:
	//   - provider: the BindGroupProvider to store the created buffers on
	//   - vertexData: the raw vertex data bytes to upload to the GPU
	//   - indexData: the raw index data bytes to upload to the GPU
	//   - indexCount: the number of indices, used for draw calls
	//
	// Returns:
	//   - error: an error if buffer creation fails
	InitMeshBuffers(provider bind_group_provider.BindGroupProvider, vertexData, indexData []byte, indexCount int) error

	// InitBindGroup creates GPU buffers and a bind group from a layout descriptor and stores them
	// on the given BindGroupProvider. Textures and samplers must be initialized via InitTextureView
	// and InitSampler before calling this method. Buffer usage and size can be overridden per binding.
	//
	// Parameters:
	//   - provider: the BindGroupProvider to store the created bind group on
	//   - descriptor: the layout descriptor defining the bind group entries
	//   - bufferUsageOverrides: additional buffer usage flags to OR into the derived usage, keyed by binding index (nil safe)
	//   - bufferSizeOverrides: custom buffer sizes to use instead of MinBindingSize, keyed by binding index (nil safe)
	//
	// Returns:
	//   - error: an error if bind group creation fails
	InitBindGroup(provider bind_group_provider.BindGroupProvider, descriptor wgpu.BindGroupLayoutDescriptor, bufferUsageOverrides map[int]wgpu.BufferUsage, bufferSizeOverrides map[int]uint64) error

	// InitTextureView creates a GPU texture from staging data and stores the resulting texture view
	// on the given BindGroupProvider at the specified binding index. Must be called before InitBindGroup
	// for any texture bindings.
	//
	// Parameters:
	//   - provider: the BindGroupProvider to store the created texture view on
	//   - bindingKey: the binding index for this texture
	//   - stagingData: the pixel data and dimensions for the texture
	//
	// Returns:
	//   - error: an error if texture creation fails
	InitTextureView(provider bind_group_provider.BindGroupProvider, bindingKey int, stagingData common.TextureStagingData) error

	// InitSampler creates a GPU sampler from staging data and stores it on the given BindGroupProvider
	// at the specified binding index. Must be called before InitBindGroup for any sampler bindings.
	//
	// Parameters:
	//   - provider: the BindGroupProvider to store the created sampler on
	//   - bindingKey: the binding index for this sampler
	//   - samplerStagingData: the sampler configuration
	//
	// Returns:
	//   - error: an error if sampler creation fails
	InitSampler(provider bind_group_provider.BindGroupProvider, bindingKey int, samplerStagingData common.SamplerStagingData) error

	// CreateBuffer creates a GPU buffer with the specified label, size, and usage flags.
	// This is a low-level operation for creating buffers outside of BindGroupProviders,
	// such as staging buffers for GPU→CPU readback.
	//
	// Parameters:
	//   - label: a debug label for the buffer
	//   - size: the buffer size in bytes
	//   - usage: the buffer usage flags (e.g. MapRead | CopyDst for staging)
	//
	// Returns:
	//   - *wgpu.Buffer: the created GPU buffer
	//   - error: an error if buffer creation fails
	CreateBuffer(label string, size uint64, usage wgpu.BufferUsage) (*wgpu.Buffer, error)

	// CopyBufferToBuffer encodes a buffer-to-buffer copy on the current compute frame encoder.
	// Must be called between BeginComputeFrame and EndComputeFrame, outside of any compute pass.
	//
	// Parameters:
	//   - src: the source buffer to copy from
	//   - dst: the destination buffer to copy to
	//   - srcOffset: byte offset in the source buffer
	//   - dstOffset: byte offset in the destination buffer
	//   - size: the number of bytes to copy
	CopyBufferToBuffer(src, dst *wgpu.Buffer, srcOffset, dstOffset, size uint64)

	// ReadMappedBuffer synchronously maps a buffer for reading, copies the data into a new
	// byte slice, and unmaps the buffer. Blocks via Device.Poll until the mapping completes.
	// The buffer must have been created with BufferUsageMapRead and the GPU work that wrote
	// to it must have been submitted before this call.
	//
	// Parameters:
	//   - buf: the buffer to map and read (must have MapRead usage)
	//   - offset: byte offset to start reading from
	//   - size: number of bytes to read
	//
	// Returns:
	//   - []byte: a copy of the mapped buffer data
	//   - error: an error if mapping fails
	ReadMappedBuffer(buf *wgpu.Buffer, offset, size uint64) ([]byte, error)

	// WriteBuffers writes all staged buffer writes to the GPU queue.
	// Each BufferWrite targets a specific buffer on a BindGroupProvider at a given binding and offset.
	//
	// Parameters:
	//   - writes: a slice of BufferWrite structs describing the data to write
	WriteBuffers(writes []bind_group_provider.BufferWrite)

	// WriteRawBuffer writes data directly to a GPU buffer at the given byte offset
	// using the device queue. This bypasses the BindGroupProvider lookup and is
	// useful for updating standalone buffers not yet associated with any provider.
	//
	// Parameters:
	//   - buf: the GPU buffer to write to
	//   - offset: byte offset within the buffer
	//   - data: the raw bytes to upload
	WriteRawBuffer(buf *wgpu.Buffer, offset uint64, data []byte)

	// WriteTexture queues a data upload to a GPU texture region. Wraps
	// wgpu.Queue.WriteTexture for raw texture writes (e.g. noise data).
	//
	// Parameters:
	//   - tex: the destination texture
	//   - data: the raw byte data to write
	//   - width: the width of the region in texels
	//   - height: the height of the region in texels
	//   - bytesPerRow: the stride in bytes between consecutive rows
	WriteTexture(tex *wgpu.Texture, data []byte, width, height, bytesPerRow uint32)

	// BeginComputeFrame creates a single command encoder for batching all compute dispatches
	// within a frame into one GPU submission. Must be paired with EndComputeFrame after all
	// DispatchCompute calls for the frame.
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginComputeFrame() error

	// EndComputeFrame finishes the batched compute command encoder and submits the resulting
	// command buffer to the GPU queue. Must be called after BeginComputeFrame and all
	// DispatchCompute calls for the frame.
	EndComputeFrame()

	// DispatchCompute looks up the cached compute Pipeline by key, then encodes a compute pass
	// within the current batched compute frame started by BeginComputeFrame.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached compute Pipeline to use
	//   - computeProvider: the BindGroupProvider whose BindGroup will be set on the compute pass
	//   - workGroupCount: the number of workgroups to dispatch in the x, y, and z dimensions
	DispatchCompute(pipelineKey string, computeProvider bind_group_provider.BindGroupProvider, workGroupCount [3]uint32)

	// BeginFrame acquires the swapchain texture and begins the main render pass.
	// Must be paired with EndFrame after all DrawCall invocations within a single frame.
	//
	// Returns:
	//   - error: an error if the swapchain texture could not be acquired
	BeginFrame() error

	// DrawCall encodes a single instanced draw command within the current render pass.
	// Multiple DrawCall invocations can be made between BeginFrame and EndFrame.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached render Pipeline to use
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - instanceCount: the number of instances to draw
	//   - bindGroups: a slice of BindGroupProviders whose BindGroups will be set on the render pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	DrawCall(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, instanceCount uint32, bindGroups []bind_group_provider.BindGroupProvider) error

	// DrawCallIndirect encodes a single indirect instanced draw command within the current render pass.
	// The instance count is read from the indirectBuffer on the GPU, allowing the compute shader to
	// control how many instances are drawn without CPU readback.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached render Pipeline to use
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - indirectBuffer: the GPU buffer containing DrawIndexedIndirect arguments (20 bytes)
	//   - bindGroups: a slice of BindGroupProviders whose BindGroups will be set on the render pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	DrawCallIndirect(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, indirectBuffer *wgpu.Buffer, bindGroups []bind_group_provider.BindGroupProvider) error

	// EndFrame ends the current render pass and submits the command buffer to the GPU.
	// Does not present the surface — call Present() after EndFrame to display the frame.
	// Must be called after BeginFrame and all DrawCall invocations within a single frame.
	EndFrame()

	// Present presents the surface to the display and releases the swapchain texture.
	// Must be called once per frame after EndFrame.
	Present()

	// SetPresentMode sets the surface present mode which controls how frames are delivered to the display.
	// A call to Resize is required after changing this for the new mode to take effect.
	//
	// Parameters:
	//   - mode: the PresentMode to use (VSync, Uncapped, or TripleBuffered)
	SetPresentMode(mode PresentMode)

	// RegisterMaterial creates GPU resources (textures, samplers, bind group) for a Material
	// and optionally registers a new render pipeline from the supplied pipeline builder options.
	// When pipelineOpts are provided and no pipeline exists for the material's PipelineKey,
	// a new render pipeline is created, registered, and the material's PipelineKey is updated.
	//
	// When no pipelineOpts are provided but the pipeline does not yet exist and the material
	// has a FragmentShaderPath set, RegisterMaterial automatically derives a new pipeline by
	// cloning the vertex shader from the best-matching existing pipeline (longest pipeline key
	// that is a prefix of the material's PipelineKey) and pairing it with a new fragment shader
	// built from the material's FragmentShaderPath. This allows callers to create variant
	// pipelines without referencing internal engine shader paths.
	//
	// The fragment shader from the resolved pipeline is inspected for @oxy:provider annotations
	// with the "material" identity to determine per-binding texture and sampler assignments.
	//
	// Parameters:
	//   - mat: the Material to initialize GPU resources for
	//   - key: a unique identifier prefix for the GPU bind group provider
	//   - pipelineOpts: optional pipeline builder options for creating and registering a new render pipeline
	//
	// Returns:
	//   - error: an error if GPU resource creation or pipeline registration fails
	RegisterMaterial(mat material.Material, key string, pipelineOpts ...pipeline.PipelineBuilderOption) error

	// Material returns the associated material from the material cache by name, provided it has already been registered.
	//
	// Parameters:
	//   - name: the unique identifier for the Material to retrieve
	//
	// Returns:
	//   - material.Material: the Material associated with the name, or nil if not found
	Material(name string) material.Material

	// BeginGeometryFrame opens a shared command encoder that merges shadow and G-Buffer
	// render passes into a single GPU submission, reducing per-frame driver overhead.
	// Uses reference counting so nested Begin/End pairs are safe. Must be paired with
	// EndGeometryFrame after all shadow and G-Buffer passes.
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginGeometryFrame() error

	// EndGeometryFrame decrements the geometry frame reference count and, when it
	// reaches zero, finishes the shared command encoder and submits the resulting
	// command buffer to the GPU queue.
	EndGeometryFrame()

	// BeginShadowFrame creates a command encoder for batching shadow depth passes.
	// Must be paired with EndShadowFrame. When a geometry frame is active, the
	// shadow encoder aliases the shared geometry encoder.
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginShadowFrame() error

	// ShadowDrawCall encodes a single instanced draw command within the current shadow pass.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached shadow Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - instanceCount: the number of instances to draw
	//   - bindGroups: bind group providers for the shadow pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	ShadowDrawCall(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, instanceCount uint32, bindGroups []bind_group_provider.BindGroupProvider) error

	// ShadowDrawCallIndirect encodes a single indirect instanced draw command within the
	// current shadow pass. The instance count is read from the indirectBuffer on the GPU.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached shadow Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - indirectBuffer: the GPU buffer containing DrawIndexedIndirect arguments
	//   - bindGroups: bind group providers for the shadow pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	ShadowDrawCallIndirect(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, indirectBuffer *wgpu.Buffer, bindGroups []bind_group_provider.BindGroupProvider) error

	// EndShadowPass ends the current shadow depth render pass.
	EndShadowPass()

	// EndShadowFrame finishes the shadow command encoder and submits to the GPU queue.
	EndShadowFrame()

	// CreateVSMTextures creates the GPU textures required for variance shadow mapping:
	// an RG32Float color texture for depth moments, a Depth32Float auxiliary depth texture
	// for hardware z-testing, and an RG32Float scratch texture for the intermediate blur result.
	//
	// Parameters:
	//   - width: shadow map width in texels
	//   - height: shadow map height in texels
	//
	// Returns:
	//   - vsmView: texture view for the VSM moments texture
	//   - vsmTex: the underlying VSM moments texture
	//   - scratchView: texture view for the scratch blur texture
	//   - scratchTex: the underlying scratch blur texture
	//   - depthView: texture view for the auxiliary depth texture
	//   - depthTex: the underlying auxiliary depth texture
	//   - err: an error if texture creation fails
	CreateVSMTextures(width, height int) (vsmView *wgpu.TextureView, vsmTex *wgpu.Texture, scratchView *wgpu.TextureView, scratchTex *wgpu.Texture, depthView *wgpu.TextureView, depthTex *wgpu.Texture, err error)

	// CreateLinearSampler creates a linear filtering sampler suitable for VSM texture lookups.
	// Unlike the comparison sampler used for PCF, this sampler performs standard bilinear
	// filtering on the RG32Float moments texture.
	//
	// Returns:
	//   - *wgpu.Sampler: the linear sampler
	//   - error: an error if sampler creation fails
	CreateLinearSampler() (*wgpu.Sampler, error)

	// RegisterVSMShadowPipeline registers a render pipeline for VSM shadow map generation.
	// Unlike the depth-only PCF pipeline, this pipeline includes a fragment shader that
	// outputs depth moments to an RG32Float color target, uses a Depth32Float depth-stencil
	// for hardware z-testing, and applies no hardware depth bias.
	//
	// Parameters:
	//   - p: the pipeline object containing the VSM vertex and fragment shaders
	//
	// Returns:
	//   - error: an error if pipeline creation fails
	RegisterVSMShadowPipeline(p pipeline.Pipeline) error

	// BeginVSMShadowPass starts a render pass targeting both the VSM color texture (RG32Float)
	// and the auxiliary depth texture (Depth32Float). Must be called between BeginShadowFrame
	// and EndShadowFrame.
	//
	// Parameters:
	//   - vsmView: the VSM moments texture view (color attachment)
	//   - depthView: the auxiliary depth texture view (depth-stencil attachment)
	BeginVSMShadowPass(vsmView *wgpu.TextureView, depthView *wgpu.TextureView)

	// CreateSATTextures creates two RGBA32Float textures for the Summed-Area Table
	// ping-pong passes used by PCSS. Each texture has TextureBinding + StorageBinding
	// usage. Returns the texture views and textures for both ping-pong targets.
	//
	// Parameters:
	//   - width: the SAT texture width in texels
	//   - height: the SAT texture height in texels
	//
	// Returns:
	//   - satAView: texture view for SAT texture A
	//   - satATex: SAT texture A
	//   - satBView: texture view for SAT texture B
	//   - satBTex: SAT texture B
	//   - err: error if texture creation fails
	CreateSATTextures(width, height int) (satAView *wgpu.TextureView, satATex *wgpu.Texture, satBView *wgpu.TextureView, satBTex *wgpu.Texture, err error)

	// BeginGBufferFrame creates a command encoder for batching G-Buffer geometry
	// pre-pass draw calls. Must be paired with EndGBufferFrame.
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginGBufferFrame() error

	// GBufferDrawCall encodes a single instanced draw command within the current
	// G-Buffer MRT render pass.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached G-Buffer Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - instanceCount: the number of instances to draw
	//   - bindGroups: bind group providers for the G-Buffer pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	GBufferDrawCall(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, instanceCount uint32, bindGroups []bind_group_provider.BindGroupProvider) error

	// GBufferDrawCallIndirect encodes a single indirect instanced draw command within
	// the current G-Buffer MRT render pass. The instance count is read from the
	// indirectBuffer on the GPU.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached G-Buffer Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - indirectBuffer: the GPU buffer containing DrawIndexedIndirect arguments
	//   - bindGroups: bind group providers for the G-Buffer pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	GBufferDrawCallIndirect(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, indirectBuffer *wgpu.Buffer, bindGroups []bind_group_provider.BindGroupProvider) error

	// EndGBufferPass ends the current G-Buffer MRT render pass.
	EndGBufferPass()

	// EndGBufferFrame finishes the G-Buffer command encoder and submits to the GPU queue.
	EndGBufferFrame()

	// BeginGBufferPass starts an MRT render pass targeting the G-Buffer textures.
	// Must be called between BeginGBufferFrame and EndGBufferFrame.
	//
	// Parameters:
	//   - normView: texture view for the normal MRT attachment
	//   - albedoView: texture view for the albedo MRT attachment
	//   - depthView: texture view for the depth-stencil attachment
	BeginGBufferPass(normView, albedoView, depthView *wgpu.TextureView)

	// CreateGBufferTextures creates the GPU textures required for the G-Buffer
	// geometry pre-pass.
	//
	// Parameters:
	//   - width: texture width in pixels
	//   - height: texture height in pixels
	//
	// Returns:
	//   - normView: texture view for the normal texture
	//   - normTex: the underlying normal texture
	//   - albedoView: texture view for the albedo texture
	//   - albedoTex: the underlying albedo texture
	//   - depthView: texture view for the depth texture
	//   - depthTex: the underlying depth texture
	//   - err: an error if texture creation fails
	CreateGBufferTextures(width, height int) (normView *wgpu.TextureView, normTex *wgpu.Texture, albedoView *wgpu.TextureView, albedoTex *wgpu.Texture, depthView *wgpu.TextureView, depthTex *wgpu.Texture, err error)

	// RegisterGBufferPipeline registers a render pipeline for the G-Buffer
	// geometry pre-pass with MRT color targets and caches it.
	//
	// Parameters:
	//   - p: the pipeline object containing the G-Buffer vertex and fragment shaders
	//
	// Returns:
	//   - error: an error if pipeline creation fails
	RegisterGBufferPipeline(p pipeline.Pipeline) error

	// CreateSSAOTextures creates the GPU textures required for screen-space
	// ambient occlusion.
	//
	// Parameters:
	//   - width: texture width in pixels (screen resolution)
	//   - height: texture height in pixels (screen resolution)
	//
	// Returns:
	//   - rawView: texture view for the raw SSAO texture
	//   - rawTex: the underlying raw SSAO texture
	//   - blurredView: texture view for the blurred SSAO texture
	//   - blurredTex: the underlying blurred SSAO texture
	//   - scratchView: texture view for the scratch blur texture
	//   - scratchTex: the underlying scratch blur texture
	//   - noiseView: texture view for the 4×4 noise texture
	//   - noiseTex: the underlying noise texture
	//   - err: an error if texture creation fails
	CreateSSAOTextures(width, height int) (rawView *wgpu.TextureView, rawTex *wgpu.Texture, blurredView *wgpu.TextureView, blurredTex *wgpu.Texture, scratchView *wgpu.TextureView, scratchTex *wgpu.Texture, noiseView *wgpu.TextureView, noiseTex *wgpu.Texture, err error)

	// CreateProbeBakeTextures creates the GPU textures required for rendering
	// cubemap faces during irradiance probe baking.
	//
	// Parameters:
	//   - resolution: the cubemap face edge size in pixels
	//
	// Returns:
	//   - colorView: texture view for the bake color texture
	//   - colorTex: the underlying bake color texture
	//   - depthView: texture view for the bake depth texture
	//   - depthTex: the underlying bake depth texture
	//   - err: an error if texture creation fails
	CreateProbeBakeTextures(resolution int) (colorView *wgpu.TextureView, colorTex *wgpu.Texture, depthView *wgpu.TextureView, depthTex *wgpu.Texture, err error)

	// RegisterProbeBakePipeline registers a render pipeline for irradiance
	// probe cubemap baking and caches it by PipelineKey. The pipeline writes
	// to a single RGBA8Unorm color target and Depth24Plus depth-stencil.
	//
	// Parameters:
	//   - p: the pipeline containing vertex and fragment shaders for probe baking
	//
	// Returns:
	//   - error: an error if pipeline creation fails
	RegisterProbeBakePipeline(p pipeline.Pipeline) error

	// BeginProbeBakeFrame creates a command encoder for batching probe bake
	// draw calls. Must be paired with EndProbeBakeFrame.
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginProbeBakeFrame() error

	// BeginProbeBakePass starts a render pass targeting the probe bake textures.
	// Must be called between BeginProbeBakeFrame and EndProbeBakeFrame.
	//
	// Parameters:
	//   - colorView: texture view for the RGBA8Unorm bake color attachment
	//   - depthView: texture view for the Depth24Plus bake depth attachment
	BeginProbeBakePass(colorView, depthView *wgpu.TextureView)

	// ProbeBakeDrawCall encodes a single instanced draw command within the
	// current probe bake render pass.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached probe bake Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - instanceCount: the number of instances to draw
	//   - bindGroups: bind group providers for the probe bake pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	ProbeBakeDrawCall(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, instanceCount uint32, bindGroups []bind_group_provider.BindGroupProvider) error

	// ProbeBakeDrawCallIndirect encodes a single indirect instanced draw
	// command within the current probe bake render pass.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached probe bake Pipeline
	//   - meshProvider: the BindGroupProvider holding vertex and index buffers
	//   - indirectBuffer: the GPU buffer containing DrawIndexedIndirect arguments
	//   - bindGroups: bind group providers for the probe bake pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	ProbeBakeDrawCallIndirect(pipelineKey string, meshProvider bind_group_provider.BindGroupProvider, indirectBuffer *wgpu.Buffer, bindGroups []bind_group_provider.BindGroupProvider) error

	// EndProbeBakePass ends the current probe bake render pass.
	EndProbeBakePass()

	// EndProbeBakeFrame finishes the probe bake command encoder and submits
	// to the GPU queue.
	EndProbeBakeFrame()

	// BeginHDRFrame creates a command encoder and begins a render pass targeting an
	// offscreen RGBA16Float HDR texture instead of the swapchain. When MSAA is active,
	// colorView is the multi-sampled texture and resolveView is the single-sample HDR
	// resolve target. Uses the main frame state so that DrawCall and EndFrame work
	// without modification.
	//
	// Parameters:
	//   - colorView: the render target texture view (MSAA or HDR)
	//   - resolveView: the HDR resolve target (nil when MSAA is off)
	//   - depthView: the depth-stencil attachment texture view
	//   - sampleCount: the MSAA sample count (1 when disabled)
	//
	// Returns:
	//   - error: an error if the command encoder could not be created
	BeginHDRFrame(colorView, resolveView, depthView *wgpu.TextureView, sampleCount uint32) error

	// CreateCompositionTextures creates the GPU textures required for the HDR
	// composition pipeline: an RGBA16Float HDR texture, an optional MSAA texture,
	// and a Depth24Plus depth texture.
	//
	// Parameters:
	//   - width: texture width in pixels
	//   - height: texture height in pixels
	//   - sampleCount: the MSAA sample count (1 when disabled)
	//
	// Returns:
	//   - hdrView: texture view for the HDR texture
	//   - hdrTex: the underlying HDR texture
	//   - msaaView: texture view for the MSAA texture (nil when sampleCount <= 1)
	//   - msaaTex: the underlying MSAA texture (nil when sampleCount <= 1)
	//   - depthView: texture view for the depth texture
	//   - depthTex: the underlying depth texture
	//   - err: an error if texture creation fails
	CreateCompositionTextures(width, height int, sampleCount uint32) (hdrView *wgpu.TextureView, hdrTex *wgpu.Texture, msaaView *wgpu.TextureView, msaaTex *wgpu.Texture, depthView *wgpu.TextureView, depthTex *wgpu.Texture, err error)

	// CreateSSRTextures creates the GPU texture required for screen-space
	// reflection output.
	//
	// Parameters:
	//   - width: texture width in pixels
	//   - height: texture height in pixels
	//
	// Returns:
	//   - ssrView: texture view for the SSR output texture
	//   - ssrTex: the underlying SSR output texture
	//   - err: an error if texture creation fails
	CreateSSRTextures(width, height int) (ssrView *wgpu.TextureView, ssrTex *wgpu.Texture, err error)

	// CreateHiZTextures creates the R32Float Hi-Z depth pyramid texture with a
	// full mip chain, plus per-mip read and storage texture views.
	//
	// Parameters:
	//   - width: texture width in pixels (should match G-Buffer depth width)
	//   - height: texture height in pixels (should match G-Buffer depth height)
	//
	// Returns:
	//   - hizView: full mip chain texture view for SSR reads
	//   - hizTex: the underlying Hi-Z texture
	//   - mipReadViews: per-mip texture views for downsample input
	//   - mipStorageViews: per-mip storage texture views for downsample output
	//   - mipCount: the number of mip levels generated
	//   - err: an error if texture creation fails
	CreateHiZTextures(width, height int) (hizView *wgpu.TextureView, hizTex *wgpu.Texture, mipReadViews []*wgpu.TextureView, mipStorageViews []*wgpu.TextureView, mipCount int, err error)

	// RegisterCompositionPipeline registers a render pipeline for the fullscreen
	// composition / tone mapping pass and caches it by PipelineKey.
	//
	// Parameters:
	//   - p: the pipeline containing vertex and fragment shaders for composition
	//
	// Returns:
	//   - error: an error if pipeline creation fails
	RegisterCompositionPipeline(p pipeline.Pipeline) error

	// BeginCompositionFrame acquires the swapchain texture and creates a command
	// encoder for the composition pass. Must be paired with EndCompositionFrame.
	//
	// Returns:
	//   - error: an error if the swapchain texture could not be acquired
	BeginCompositionFrame() error

	// BeginCompositionPass starts a render pass targeting the swapchain for
	// the fullscreen composition draw.
	BeginCompositionPass()

	// CompositionDrawCall encodes a fullscreen triangle draw command within the
	// current composition render pass.
	//
	// Parameters:
	//   - pipelineKey: the unique identifier for the cached composition Pipeline
	//   - bindGroups: bind group providers for the composition pass
	//
	// Returns:
	//   - error: an error if the pipeline is not found
	CompositionDrawCall(pipelineKey string, bindGroups []bind_group_provider.BindGroupProvider) error

	// EndCompositionPass ends the current composition render pass.
	EndCompositionPass()

	// EndCompositionFrame finishes the composition command encoder and submits
	// to the GPU queue.
	EndCompositionFrame()

	// SampleCount returns the MSAA sample count for the main render pass.
	//
	// Returns:
	//   - uint32: the MSAA sample count (1 when disabled)
	SampleCount() uint32

	// SetRenderTargetFormat overrides the color target format used when creating
	// render pipelines. Defaults to the swapchain surface format. Set to
	// RGBA16Float when composition (HDR tone mapping) is active so that the
	// lit render pass targets the offscreen HDR texture instead of the swapchain.
	//
	// Parameters:
	//   - format: the wgpu.TextureFormat to use for render pipeline color targets
	SetRenderTargetFormat(format wgpu.TextureFormat)
}

type RendererBackend interface {
	// contains filtered or unexported methods
}

type RendererBackendType int

type RendererBuilderOption func(*renderer)