composition

Documentation

Overview

Package composition provides the postprocessing composition and tone-mapping subsystem.

Index

• Variables
• type GPUBloomParams
  • func (p *GPUBloomParams) Marshal() []byte
  • func (p *GPUBloomParams) Size() int
• type GPUCompositionParams
  • func (p *GPUCompositionParams) Marshal() []byte
  • func (p *GPUCompositionParams) Size() int
• type GPULuminanceParams
  • func (p *GPULuminanceParams) Marshal() []byte
  • func (p *GPULuminanceParams) Size() uint64
• type Handler
  • func NewHandler(opts ...HandlerOption) Handler
• type HandlerOption
  • func WithAdaptSpeed(speed float32) HandlerOption
  • func WithAutoExposure(enabled bool) HandlerOption
  • func WithBloomEnabled(enabled bool) HandlerOption
  • func WithBloomIntensity(intensity float32) HandlerOption
  • func WithBloomThreshold(threshold float32) HandlerOption
  • func WithCompositionScreenSize(width, height int) HandlerOption
  • func WithExposure(exposure float32) HandlerOption
  • func WithLuminanceWorkgroupSize(size int) HandlerOption
  • func WithMaxExposure(max float32) HandlerOption
  • func WithMinExposure(min float32) HandlerOption
  • func WithToneMappingEnabled(enabled bool) HandlerOption

Variables

var GPUBloomParamsSource string

GPUBloomParamsSource is the canonical WGSL definition of the BloomParams struct. Matches GPUBloomParams layout exactly (16 bytes, std140 aligned).

var GPUCompositionParamsSource string

GPUCompositionParamsSource is the canonical WGSL definition of the CompositionParams struct. Matches GPUCompositionParams layout exactly (32 bytes, std140 aligned).

var GPULuminanceParamsSource string

GPULuminanceParamsSource is the canonical WGSL definition of the LuminanceParams struct. Matches GPULuminanceParams layout exactly (32 bytes, std430 aligned).

Types

type GPUBloomParams

type GPUBloomParams struct {
	Threshold float32
	// contains filtered or unexported fields
}

GPUBloomParams is the GPU-aligned uniform data for the bloom downsample compute shader. Contains the brightness threshold that controls which pixels contribute to the bloom effect. Set to 0 to disable threshold filtering (used for downsample passes after the first). Matches the WGSL BloomParams struct layout exactly (see GPUBloomParamsSource). Size: 16 bytes.

Layout:

f32 threshold (4 bytes, offset  0)
u32 _pad0     (4 bytes, offset  4)
u32 _pad1     (4 bytes, offset  8)
u32 _pad2     (4 bytes, offset 12)

func (*GPUBloomParams) Marshal

func (p *GPUBloomParams) Marshal() []byte

Marshal serializes the GPUBloomParams struct into a byte buffer suitable for GPU uniform buffer upload.

Returns:

• []byte: the marshaled buffer ready for GPU upload

func (*GPUBloomParams) Size

func (p *GPUBloomParams) Size() int

Size returns the size of the GPUBloomParams struct in bytes.

Returns:

• int: the size in bytes (16)

type GPUCompositionParams

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

GPUCompositionParams is the GPU-aligned uniform data for the composition fragment shader. Contains tone mapping, exposure, auto-exposure, and bloom configuration. When auto-exposure is enabled the fragment shader reads the adapted exposure from the luminance storage buffer instead of the static value. Matches the WGSL CompositionParams struct layout exactly (see GPUCompositionParamsSource). Size: 32 bytes.

Layout:

u32 tone_mapping_enabled  (4 bytes, offset  0)
f32 exposure              (4 bytes, offset  4)
u32 auto_exposure_enabled (4 bytes, offset  8)
u32 bloom_enabled         (4 bytes, offset 12)
f32 bloom_intensity       (4 bytes, offset 16)
u32 _pad5                 (4 bytes, offset 20)
u32 _pad6                 (4 bytes, offset 24)
u32 _pad7                 (4 bytes, offset 28)

func (*GPUCompositionParams) Marshal

func (p *GPUCompositionParams) Marshal() []byte

Marshal serializes the GPUCompositionParams struct into a byte buffer suitable for GPU uniform buffer upload.

Returns:

• []byte: the marshaled buffer ready for GPU upload

func (*GPUCompositionParams) Size

func (p *GPUCompositionParams) Size() int

Size returns the size of the GPUCompositionParams struct in bytes.

Returns:

• int: the size in bytes (32)

type GPULuminanceParams

type GPULuminanceParams struct {
	ScreenWidth         uint32
	ScreenHeight        uint32
	AdaptSpeed          float32
	DeltaTime           float32
	MinExposure         float32
	MaxExposure         float32
	KeyValue            float32
	AutoExposureEnabled uint32
}

GPULuminanceParams is the GPU-aligned uniform data for the luminance compute shader. Each frame, the compute shader samples a 16x16 grid of HDR texels, computes the log-average luminance, derives a target exposure via the key-value formula, and smoothly adapts the persistent exposure storage buffer. Matches the WGSL LuminanceParams struct layout exactly (see GPULuminanceParamsSource). Size: 32 bytes.

Layout:

u32 screen_width          (4 bytes, offset  0)
u32 screen_height         (4 bytes, offset  4)
f32 adapt_speed           (4 bytes, offset  8)
f32 delta_time            (4 bytes, offset 12)
f32 min_exposure          (4 bytes, offset 16)
f32 max_exposure          (4 bytes, offset 20)
f32 key_value             (4 bytes, offset 24)
u32 auto_exposure_enabled (4 bytes, offset 28)

func (*GPULuminanceParams) Marshal

func (p *GPULuminanceParams) Marshal() []byte

Marshal serializes the GPULuminanceParams struct into a byte buffer suitable for GPU uniform buffer upload.

Returns:

• []byte: 32-byte buffer ready for GPU upload

func (*GPULuminanceParams) Size

func (p *GPULuminanceParams) Size() uint64

Size returns the size of the GPULuminanceParams struct in bytes.

Returns:

• uint64: the struct size in bytes (32)

type Handler

type Handler 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)

	// SetSlot selects the active texture slot. Texture and view getters and
	// setters read and write the [slot] index of the underlying arrays.
	//
	// Parameters:
	//   - slot: the slot index (0 or 1)
	SetSlot(slot int)

	// 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)

	// AutoExposureEnabled returns whether the eye-adaptation / auto-exposure system
	// is active. When true, the luminance compute shader drives exposure each frame
	// instead of the static Exposure value.
	//
	// Returns:
	//   - bool: true if auto-exposure is enabled
	AutoExposureEnabled() bool

	// SetAutoExposureEnabled enables or disables the auto-exposure system.
	//
	// Parameters:
	//   - enabled: true to enable eye adaptation
	SetAutoExposureEnabled(enabled bool)

	// AdaptSpeed returns the eye-adaptation rate (exposure change per second).
	//
	// Returns:
	//   - float32: the adaptation speed
	AdaptSpeed() float32

	// SetAdaptSpeed sets the eye-adaptation rate (exposure change per second).
	//
	// Parameters:
	//   - speed: the adaptation speed
	SetAdaptSpeed(speed float32)

	// MinExposure returns the lower clamp boundary for auto-exposure.
	//
	// Returns:
	//   - float32: the minimum exposure value
	MinExposure() float32

	// SetMinExposure sets the lower clamp boundary for auto-exposure.
	//
	// Parameters:
	//   - min: the minimum exposure value
	SetMinExposure(min float32)

	// MaxExposure returns the upper clamp boundary for auto-exposure.
	//
	// Returns:
	//   - float32: the maximum exposure value
	MaxExposure() float32

	// SetMaxExposure sets the upper clamp boundary for auto-exposure.
	//
	// Parameters:
	//   - max: the maximum exposure value
	SetMaxExposure(max float32)

	// LuminanceWorkgroupSize returns the tile dimension of the luminance compute
	// shader workgroup. The shader uses a single (size × size) workgroup where each
	// thread samples one texel of the HDR image to compute log-average luminance.
	//
	// Returns:
	//   - int: the workgroup tile dimension (number of threads per axis)
	LuminanceWorkgroupSize() int

	// ExposureBuffer returns the persistent GPU storage buffer holding the current
	// adapted exposure value written each frame by the luminance compute shader.
	//
	// Returns:
	//   - *wgpu.Buffer: the exposure storage buffer, or nil if not initialized
	ExposureBuffer() *wgpu.Buffer

	// SetExposureBuffer stores the persistent GPU exposure storage buffer.
	//
	// Parameters:
	//   - b: the exposure storage buffer
	SetExposureBuffer(b *wgpu.Buffer)

	// BloomEnabled returns whether the bloom post-processing effect is active.
	//
	// Returns:
	//   - bool: true if bloom is enabled
	BloomEnabled() bool

	// SetBloomEnabled enables or disables the bloom post-processing effect.
	//
	// Parameters:
	//   - enabled: true to enable bloom
	SetBloomEnabled(enabled bool)

	// BloomThreshold returns the brightness threshold for bloom extraction.
	// Pixels below this brightness are excluded from the bloom contribution.
	//
	// Returns:
	//   - float32: the brightness threshold
	BloomThreshold() float32

	// SetBloomThreshold sets the brightness threshold for bloom extraction.
	//
	// Parameters:
	//   - threshold: the brightness threshold (typical range 0.5–2.0)
	SetBloomThreshold(threshold float32)

	// BloomIntensity returns the intensity multiplier applied to the bloom
	// contribution when blended into the final composition.
	//
	// Returns:
	//   - float32: the bloom intensity
	BloomIntensity() float32

	// SetBloomIntensity sets the bloom intensity multiplier.
	//
	// Parameters:
	//   - intensity: the bloom intensity (typical range 0.1–1.0)
	SetBloomIntensity(intensity float32)

	// BloomMipCount returns the number of mip levels in the bloom mip chain.
	//
	// Returns:
	//   - int: the mip level count
	BloomMipCount() int

	// SetBloomMipCount stores the number of mip levels in the bloom mip chain.
	//
	// Parameters:
	//   - count: the mip level count
	SetBloomMipCount(count int)

	// BloomDownTexture returns the bloom downsample chain texture.
	//
	// Returns:
	//   - *wgpu.Texture: the downsample chain texture, or nil if not initialized
	BloomDownTexture() *wgpu.Texture

	// SetBloomDownTexture stores the bloom downsample chain texture.
	//
	// Parameters:
	//   - t: the downsample chain texture
	SetBloomDownTexture(t *wgpu.Texture)

	// BloomDownReadViews returns the per-mip read views for the downsample chain.
	//
	// Returns:
	//   - []*wgpu.TextureView: the per-mip read views
	BloomDownReadViews() []*wgpu.TextureView

	// SetBloomDownReadViews stores the per-mip read views for the downsample chain.
	//
	// Parameters:
	//   - views: the per-mip read views
	SetBloomDownReadViews(views []*wgpu.TextureView)

	// BloomDownStorageViews returns the per-mip storage views for the downsample chain.
	//
	// Returns:
	//   - []*wgpu.TextureView: the per-mip storage views
	BloomDownStorageViews() []*wgpu.TextureView

	// SetBloomDownStorageViews stores the per-mip storage views for the downsample chain.
	//
	// Parameters:
	//   - views: the per-mip storage views
	SetBloomDownStorageViews(views []*wgpu.TextureView)

	// BloomUpTexture returns the bloom upsample chain texture.
	//
	// Returns:
	//   - *wgpu.Texture: the upsample chain texture, or nil if not initialized
	BloomUpTexture() *wgpu.Texture

	// SetBloomUpTexture stores the bloom upsample chain texture.
	//
	// Parameters:
	//   - t: the upsample chain texture
	SetBloomUpTexture(t *wgpu.Texture)

	// BloomUpReadViews returns the per-mip read views for the upsample chain.
	//
	// Returns:
	//   - []*wgpu.TextureView: the per-mip read views
	BloomUpReadViews() []*wgpu.TextureView

	// SetBloomUpReadViews stores the per-mip read views for the upsample chain.
	//
	// Parameters:
	//   - views: the per-mip read views
	SetBloomUpReadViews(views []*wgpu.TextureView)

	// BloomUpStorageViews returns the per-mip storage views for the upsample chain.
	//
	// Returns:
	//   - []*wgpu.TextureView: the per-mip storage views
	BloomUpStorageViews() []*wgpu.TextureView

	// SetBloomUpStorageViews stores the per-mip storage views for the upsample chain.
	//
	// Parameters:
	//   - views: the per-mip storage views
	SetBloomUpStorageViews(views []*wgpu.TextureView)

	// BloomUpMip0View returns the mip 0 read view of the upsample chain texture.
	// This is the final bloom result texture view sampled in the composition shader.
	//
	// Returns:
	//   - *wgpu.TextureView: the mip 0 read view
	BloomUpMip0View() *wgpu.TextureView

	// SetBloomUpMip0View stores the mip 0 read view of the upsample chain.
	//
	// Parameters:
	//   - tv: the mip 0 read view
	SetBloomUpMip0View(tv *wgpu.TextureView)
}

Handler defines the interface for the scene's composition and tone mapping subsystem.

The Handler manages the offscreen HDR render target, the full-screen composition pipeline, and tone mapping configuration. When composition is active, the lit pass renders to an RGBA16Float offscreen texture instead of the swapchain. A final full-screen pass then samples the HDR result along with any SSR texture, applies ACES tone mapping and gamma correction, and writes to the swapchain.

Thread safety is provided by the owning scene's mutex — the handler itself does not perform internal locking.

func NewHandler

func NewHandler(opts ...HandlerOption) Handler

NewHandler creates a new Handler with sensible defaults and any provided options applied. GPU resources are not allocated until the owning scene calls the appropriate initialization methods.

Default values:

• ToneMappingEnabled: true
• Exposure: 1.0

Parameters:

• opts: variadic list of HandlerOption functions to configure the handler

Returns:

• Handler: a new handler instance ready to be attached to a scene

type HandlerOption

type HandlerOption func(*handlerImpl)

HandlerOption is a functional option for configuring a Handler during construction via NewHandler.

func WithAdaptSpeed

func WithAdaptSpeed(speed float32) HandlerOption

WithAdaptSpeed sets the eye-adaptation rate (exposure change per second). Higher values cause faster adaptation to scene luminance changes.

Parameters:

• speed: the adaptation speed (exposures per second)

Returns:

• HandlerOption: a function that applies the adapt speed option

func WithAutoExposure

func WithAutoExposure(enabled bool) HandlerOption

WithAutoExposure enables or disables the eye-adaptation (auto-exposure) system. When enabled, the luminance compute shader drives exposure each frame.

Parameters:

• enabled: true to enable auto-exposure

Returns:

• HandlerOption: a function that applies the auto-exposure option

func WithBloomEnabled

func WithBloomEnabled(enabled bool) HandlerOption

WithBloomEnabled enables or disables the bloom post-processing effect.

Parameters:

• enabled: true to enable bloom

func WithBloomIntensity

func WithBloomIntensity(intensity float32) HandlerOption

WithBloomIntensity sets the intensity multiplier applied to the bloom contribution when blended into the final composition output.

Parameters:

• intensity: the bloom intensity (typical range 0.1–1.0, default 0.5)

func WithBloomThreshold

func WithBloomThreshold(threshold float32) HandlerOption

WithBloomThreshold sets the brightness threshold for bloom extraction. Pixels below this brightness will not contribute to the bloom effect.

Parameters:

• threshold: the brightness threshold (typical range 0.5–2.0, default 1.0)

func WithCompositionScreenSize

func WithCompositionScreenSize(width, height int) HandlerOption

WithCompositionScreenSize sets the initial screen dimensions used for HDR texture allocation. These should match the surface dimensions at the time of initialization.

Parameters:

• width: the screen width in pixels
• height: the screen height in pixels

Returns:

• HandlerOption: a function that applies the screen size option to a handlerImpl

func WithExposure

func WithExposure(exposure float32) HandlerOption

WithExposure sets the exposure multiplier applied to HDR values before tone mapping. Higher values brighten the final image. A value of 1.0 is neutral.

Parameters:

• exposure: the exposure multiplier

Returns:

• HandlerOption: a function that applies the exposure option to a handlerImpl

func WithLuminanceWorkgroupSize

func WithLuminanceWorkgroupSize(size int) HandlerOption

WithLuminanceWorkgroupSize sets the tile dimension of the luminance compute shader workgroup. The shader dispatches a single (size × size) workgroup where each thread samples one HDR texel to compute log-average luminance. Defaults to 16 (256 threads total).

Parameters:

• size: the workgroup tile dimension (number of threads per axis)

Returns:

• HandlerOption: a function that applies the workgroup size option

func WithMaxExposure

func WithMaxExposure(max float32) HandlerOption

WithMaxExposure sets the upper clamp boundary for the auto-exposure system.

Parameters:

• max: the maximum allowed exposure value

Returns:

• HandlerOption: a function that applies the max exposure option

func WithMinExposure

func WithMinExposure(min float32) HandlerOption

WithMinExposure sets the lower clamp boundary for the auto-exposure system.

Parameters:

• min: the minimum allowed exposure value

Returns:

• HandlerOption: a function that applies the min exposure option

func WithToneMappingEnabled

func WithToneMappingEnabled(enabled bool) HandlerOption

WithToneMappingEnabled enables or disables ACES tone mapping during the composition pass. When disabled, the HDR texture is passed through with only gamma correction applied.

Parameters:

• enabled: true to enable ACES tone mapping

Returns:

• HandlerOption: a function that applies the tone mapping option to a handlerImpl