viewport-lib-types 0.2.0

Pure-data types for viewport-lib: submission payloads, handles, and frame config, free of any GPU dependency.
Documentation
//! Debug visualisation configuration.

/// Selects which intermediate quantity to display in a debug channel.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum DebugQuantity {
    /// Constant black (0.0).
    #[default]
    Zero,
    /// Constant white (1.0).
    One,
    /// Cascade index as a hue (0=red, 1=green, 2=blue, 3=yellow).
    CascadeIndex,
    /// Combined shadow factor [0=fully shadowed, 1=fully lit].
    ShadowFactor,
    /// Contact shadow contribution in isolation.
    ContactShadowFactor,
    /// N dot L (clamped 0..1).
    NdotL,
    /// Normal bias magnitude in world units.
    NormalBiasMagnitude,
    /// Atlas UV X coordinate.
    AtlasUvX,
    /// Atlas UV Y coordinate.
    AtlasUvY,
    /// Tile UV X before atlas remapping.
    TileUvX,
    /// Tile UV Y before atlas remapping.
    TileUvY,
    /// Biased depth used in the shadow comparison.
    BiasedDepth,
    /// Unbiased surface depth from the shadow projection.
    SurfaceDepth,
    /// World-space normal X.
    WorldNormalX,
    /// World-space normal Y.
    WorldNormalY,
    /// World-space normal Z.
    WorldNormalZ,
    /// PBR roughness value.
    Roughness,
    /// PBR metallic value.
    Metallic,
    /// Ambient occlusion factor.
    AoFactor,
    /// Direct light luminance (all lights, no ambient).
    DirectLightLuminance,
    /// Hemisphere or IBL ambient luminance.
    AmbientLuminance,
    /// IBL diffuse luminance only.
    IblDiffuseLuminance,
    /// IBL specular luminance only.
    IblSpecularLuminance,
    /// Emissive luminance only.
    EmissiveLuminance,
}

impl DebugQuantity {
    /// Returns the packed u32 index for this quantity (used in the shader).
    pub fn index(self) -> u32 {
        self as u32
    }

    /// Returns all defined variants in enum order.
    pub fn all_variants() -> &'static [DebugQuantity] {
        &[
            DebugQuantity::Zero,
            DebugQuantity::One,
            DebugQuantity::CascadeIndex,
            DebugQuantity::ShadowFactor,
            DebugQuantity::ContactShadowFactor,
            DebugQuantity::NdotL,
            DebugQuantity::NormalBiasMagnitude,
            DebugQuantity::AtlasUvX,
            DebugQuantity::AtlasUvY,
            DebugQuantity::TileUvX,
            DebugQuantity::TileUvY,
            DebugQuantity::BiasedDepth,
            DebugQuantity::SurfaceDepth,
            DebugQuantity::WorldNormalX,
            DebugQuantity::WorldNormalY,
            DebugQuantity::WorldNormalZ,
            DebugQuantity::Roughness,
            DebugQuantity::Metallic,
            DebugQuantity::AoFactor,
            DebugQuantity::DirectLightLuminance,
            DebugQuantity::AmbientLuminance,
            DebugQuantity::IblDiffuseLuminance,
            DebugQuantity::IblSpecularLuminance,
            DebugQuantity::EmissiveLuminance,
        ]
    }
}

/// How the debug channel value is composited over the normal render.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum DebugOutputMode {
    /// Fragment colour is entirely replaced by the debug output.
    #[default]
    Replace,
    /// Debug output is blended over the normal colour at 50% opacity.
    TintOverlay,
    /// Left half shows normal render, right half shows debug quantity.
    /// Split position is set by `DebugVis::split_x`.
    SplitScreen,
}

/// Debug visualisation configuration for the shadow and lighting pipeline.
///
/// Attach to [`EffectsDebug::debug_vis`] to activate per-fragment channel output.
/// When `active` is false the overhead is zero: the lit pipelines compile
/// without the debug code entirely (its per-fragment storage write would
/// disable hardware early depth rejection and slow dense scenes by an order
/// of magnitude). Turning debug vis on or off rebuilds those pipelines, so
/// expect a one-off hitch on the frame the flag flips.
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct DebugVis {
    /// Whether debug visualisation is active.
    pub active: bool,
    /// How the debug value is composited over the normal render.
    pub mode: DebugOutputMode,
    /// Quantity shown in the red channel.
    pub channel_r: DebugQuantity,
    /// Quantity shown in the green channel.
    pub channel_g: DebugQuantity,
    /// Quantity shown in the blue channel.
    pub channel_b: DebugQuantity,
    /// Multiplier applied to the raw quantity value before display.
    /// Use values > 1.0 to bring small quantities (e.g. bias in world units) into visible range.
    pub scale: f32,
    /// Split position for `SplitScreen` mode, in normalised viewport coordinates (0..1).
    /// 0.5 = center. Ignored unless mode is `SplitScreen`.
    pub split_x: f32,
}

impl DebugVis {
    /// Create a new active debug visualisation configuration.
    pub fn new(
        mode: DebugOutputMode,
        channel_r: DebugQuantity,
        channel_g: DebugQuantity,
        channel_b: DebugQuantity,
        scale: f32,
    ) -> Self {
        Self {
            active: true,
            mode,
            channel_r,
            channel_g,
            channel_b,
            scale,
            split_x: 0.5,
        }
    }

    /// Pack the channel selectors, output mode, and active flag into a single u32.
    ///
    /// Bit layout:
    ///   bits 0..5   : channel R quantity index (5 bits, up to 32 quantities)
    ///   bits 5..10  : channel G quantity index
    ///   bits 10..15 : channel B quantity index
    ///   bits 15..17 : output mode (0=Replace, 1=TintOverlay, 2=SplitScreen)
    ///   bit 31      : active flag (0=off, non-zero=on)
    ///
    /// Returns 0 when not active, so the shader exits immediately.
    pub fn pack_mode(&self) -> u32 {
        if !self.active {
            return 0;
        }
        let r = self.channel_r.index() & 0x1f;
        let g = self.channel_g.index() & 0x1f;
        let b = self.channel_b.index() & 0x1f;
        let m = match self.mode {
            DebugOutputMode::Replace => 0u32,
            DebugOutputMode::TintOverlay => 1u32,
            DebugOutputMode::SplitScreen => 2u32,
        };
        (1u32 << 31) | (m << 15) | (b << 10) | (g << 5) | r
    }
}

/// Viewport corner where the shadow atlas viewer overlay is anchored.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum AtlasViewerCorner {
    /// Top-left corner.
    TopLeft,
    /// Top-right corner.
    TopRight,
    /// Bottom-left corner.
    BottomLeft,
    /// Bottom-right corner (default).
    #[default]
    BottomRight,
}

/// Debug overlays and diagnostics for one frame. Grouped on
/// [`EffectsFrame::debug`] to keep debug knobs out of the production effect,
/// lighting, and viewport fields.
///
/// Not `Copy`: it carries the [`DebugVis`]
/// channel-visualisation config, which is a plain (non-`Copy`) struct.
#[non_exhaustive]
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct EffectsDebug {
    /// Show the shadow depth atlas as a corner overlay. Default: false.
    pub show_shadow_atlas: bool,
    /// Corner where the atlas viewer is placed. Default: BottomRight.
    pub atlas_viewer_corner: AtlasViewerCorner,
    /// Atlas viewer size as a fraction of viewport width. Default: 0.3.
    pub atlas_viewer_scale: f32,
    /// Per-fragment channel visualisation (debug view of shadow factor, normals,
    /// and other quantities). Inactive by default; see
    /// [`DebugVis`].
    pub debug_vis: DebugVis,
    /// Force every lit pipeline onto the straight-iteration light loop even when
    /// the active light count is above the cluster-build threshold, so a consumer
    /// can A/B the clustered path against it to spot bugs. Default: false.
    pub force_cluster_fallback: bool,
    /// Trigger a host-visible readback of the cluster cell array at the end of
    /// `prepare_scene`, exposed via
    /// `ViewportRenderer::cluster_stats`.
    /// The readback blocks the calling thread on a device poll, so leave this off
    /// unless a debug panel is actively displaying the numbers. Default: false.
    pub cluster_stats_request: bool,
}

impl Default for EffectsDebug {
    fn default() -> Self {
        Self {
            show_shadow_atlas: false,
            atlas_viewer_corner: AtlasViewerCorner::BottomRight,
            atlas_viewer_scale: 0.3,
            debug_vis: DebugVis::default(),
            force_cluster_fallback: false,
            cluster_stats_request: false,
        }
    }
}