Skip to content

Colossal.Rendering.DebugCustomPass

Assembly:
Namespace: Colossal.Rendering

Type: class

Base: UnityEngine.Rendering.HighDefinition.CustomPass

Summary: DebugCustomPass is an HD Render Pipeline CustomPass used by Cities: Skylines 2 to display various internal debug textures (terrain height maps, splat maps, water simulation buffers, wind texture, snow/rain accumulation, CBT tessellation debug view, selection outline buffer, etc.) as an on-screen overlay. It exposes a TextureDebugMode enum to choose which texture to display and supports slice selection for array/volume textures, value range remapping, zoom, an "extra" toggle for additional rendering options, and an adjustable overlay size/position based on UI scaling.

Fields

  • private const int kPadding = 10
    {{ The UI padding (pixels) used when positioning the debug overlay; scaled by UI scaling in RemToPxScale when computing runtime padding. }}

  • public const TextureDebugMode kGlobalMapStart = TextureDebugMode.HeightMap
    {{ Marker constant indicating the start of the global texture range in the TextureDebugMode enum. }}

  • public const TextureDebugMode kGlobalMapEnd = TextureDebugMode.Wind
    {{ Marker constant indicating the end of the global texture range in the TextureDebugMode enum. }}

  • public const TextureDebugMode kWaterSimulationMapStart = TextureDebugMode.WaterSurfaceSpectrum
    {{ Marker constant indicating the start of water simulation related texture modes. }}

  • public const TextureDebugMode kWaterSimulationMapEnd = TextureDebugMode.WaterSurfaceCaustics
    {{ Marker constant indicating the end of water simulation related texture modes. }}

  • private Material m_DebugBlitMaterial
    {{ Material used to blit the selected debug texture to the screen quad. Created in Setup via Hidden/BH/CustomPass/DebugBlitQuad shader. }}

  • private MaterialPropertyBlock m_MaterialPropertyBlock
    {{ MaterialPropertyBlock used to pass per-draw properties (zoom, slice, valid range, mode, exposure flag, input texture) into the debug blit draw. }}

  • private ComputeBuffer m_TopViewRenderIndirectArgs
    {{ ComputeBuffer used as an indirect draw argument buffer for procedural CBT tessellation debug rendering. Allocated in Setup and disposed in Cleanup. }}

  • private Material m_TopViewMaterial
    {{ Material used to draw the top-down CBT tessellation debug view. Created in Setup from HDRenderPipeline resources. }}

  • private RTHandle m_TopViewRenderTexture
    {{ Render target (RTHandle) used as temporary render texture for CBT top-down visualization. Managed by CheckResources / Release in Cleanup. }}

Properties

  • public int activeInstance { get; set; }
    {{ Index used to select which WaterSurface instance to query when multiple water instances are present (for water simulation debug textures). }}

  • public int sliceIndex { get; set; }
    {{ Selected array/volume slice index for textures that support slices (Tex2DArray / 3D / RenderTexture volume). Used to pick a layer to display. }}

  • public float debugOverlayRatio { get; set; } = 1f / 3f
    {{ Fraction (0..1) of the min(screenWidth, screenHeight) used as the overlay size. Default is 1/3. }}

  • public TextureDebugMode textureDebugMode { get; set; }
    {{ Currently selected debug texture mode (see nested TextureDebugMode enum). }}

  • public float zoom { get; set; }
    {{ Zoom factor applied when displaying the texture in the overlay. Passed to the debug blit material. }}

  • public bool showExtra { get; set; }
    {{ Toggles additional debug visuals/features for modes that support it (e.g., extra overlays for WaterVelocity). }}

  • public float minValue { get; set; }
    {{ Minimum value used for remapping the texture value range before display (valid range lower bound). }}

  • public float maxValue { get; set; }
    {{ Maximum value used for remapping the texture value range before display (valid range upper bound). }}

Constructors

  • public DebugCustomPass()
    {{ Implicit/default constructor. This class does not declare a custom constructor; it relies on the default initialization semantics of CustomPass. Instances are typically created/serialized through CustomPassVolume assets in the editor. }}

Methods

  • public enum TextureDebugMode
    {{ Enum of all supported debug texture modes (None, SelectionOutlines, HeightMap, HeightMapCascades, TerrainOverlay, SplatMap, WaterDepth, WaterVelocity, WaterPolution, SnowAccumulation, RainAccumulation, WaterRawVelocity, Wind, TerrainTesselation, WaterSurfaceSpectrum, WaterSurfaceDisplacement, WaterSurfaceGradient, WaterSurfaceJacobianSurface, WaterSurfaceJacobianDeep, WaterSurfaceCaustics). Used by textureDebugMode property. }}

  • public float GetDefaultMinValue()
    {{ Returns a sensible default lower bound depending on the selected textureDebugMode (special-cased for WaterRawVelocity and WaterVelocity; otherwise calls GetMinValue). }}

  • public float GetDefaultMaxValue()
    {{ Returns a sensible default upper bound depending on the selected textureDebugMode (special-cased for WaterVelocity; otherwise calls GetMaxValue). }}

  • public float GetMinValue()
    {{ Returns mode-specific minimum value; currently a default of 0f for all modes. }}

  • public float GetMaxValue()
    {{ Returns mode-specific maximum value; special-case: WaterDepth returns 4096f, otherwise 1f. }}

  • public bool HasExtra()
    {{ Returns whether the currently selected texture mode supports the "extra" overlay toggle. Currently true for WaterVelocity, false otherwise. }}

  • protected override void Setup(ScriptableRenderContext renderContext, CommandBuffer cmd)
    {{ Called by HDRP when the custom pass is set up. Allocates/creates materials, MaterialPropertyBlock and the indirect draw compute buffer, and creates the top-view material from pipeline resources. }}

  • protected override void Cleanup()
    {{ Releases/destroys created resources: debug blit material, RTHandle, compute buffer, and top-view material. }}

  • private static T GetSystem<T>() where T : ComponentSystemBase
    {{ Convenience helper to get or create a managed ECS system from the default world (World.DefaultGameObjectInjectionWorld.GetOrCreateSystemManaged()). Many Texture sources are retrieved via GetSystem(). }}

  • private static float RemToPxScale(HDCamera hdCamera)
    {{ Converts the "rem" UI scale to pixels based on interface scaling user setting and camera viewport aspect. Used to scale the overlay and padding to match UI scaling. }}

  • private static int GetRuntimeDebugPanelWidth(HDCamera hdCamera)
    {{ Computes the x-offset for the overlay by considering whether the in-game debug UI (DebugUISystem) is visible and applying RemToPxScale. Returns a clamped width so the overlay doesn't exceed the camera width. }}

  • private static int GetRuntimePadding(HDCamera hdCamera)
    {{ Returns UI padding in pixels scaled by RemToPxScale (uses a base of 10 rem). }}

  • private static T GetCustomPass<T>(string passName, CustomPassInjectionPoint injectionPoint) where T : CustomPass
    {{ Helper that iterates active CustomPassVolume instances for the given injection point and returns the first custom pass whose name matches passName and can be cast to T. Used internally to query the outline pass for SelectionOutlines mode. }}

  • public bool SetupTexture(out Texture tex, out int sliceCount)
    {{ Core method that, based on textureDebugMode, retrieves the source Texture (or GPU buffer exposed as a Texture) to display, sets slice and valid range values into the MaterialPropertyBlock, and returns true if a texture was found. Populates sliceCount for array/3D textures. Sources include TerrainSystem, TerrainRenderSystem, TerrainMaterialSystem, WaterRenderSystem, WaterSurface instances (simulation buffers), SnowSystem, WindTextureSystem, and the selection Outlines pass. }}

  • private Texture GetDebugTesselationTexture()
    {{ Produces a top-down CBT tessellation debug texture by dispatching a compute shader that fills an indirect draw buffer and then drawing procedurally into m_TopViewRenderTexture with GL.wireframe enabled. Returns the RTHandle texture or null when no valid surface/camera buffer is available. }}

  • private void CheckResources(int size)
    {{ Ensures m_TopViewRenderTexture exists and has the requested square size. Re-allocates the RTHandle with the configured format and parameters if needed. }}

  • protected override void Execute(CustomPassContext ctx)
    {{ Main execution entry called per-frame for the custom pass. When the camera is the Game camera, computes overlay size & position, ensures resources, fills material property block with zoom/showExtra, calls SetupTexture to obtain the selected texture, then calls DisplayTexture to draw it using the blit material. }}

  • private static void DisplayTexture(CommandBuffer cmd, Rect viewportSize, Texture texture, Material debugMaterial, int mode, MaterialPropertyBlock mpb, bool applyExposure)
    {{ Static helper that sets shader property IDs (apply exposure, mipmap, input texture, mode), toggles a shader keyword if the source is a Tex2DArray, sets the viewport on the command buffer, and issues a DrawProcedural using the provided debugMaterial and MaterialPropertyBlock. }}

Usage Example

// Example: find active DebugCustomPass instances and configure display mode.
// This code can be used in a mod script (e.g. editor or runtime tool) to toggle/debug views.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Rendering;
using Colossal.Rendering;

// gather active custom pass volumes for the injection point used by debug passes
List<CustomPassVolume> volumes = new List<CustomPassVolume>();
CustomPassVolume.GetActivePassVolumes(CustomPassInjectionPoint.AfterPostProcess, volumes);

foreach (var vol in volumes)
{
    foreach (var pass in vol.customPasses)
    {
        if (pass is DebugCustomPass debugPass)
        {
            // Show the terrain heightmap in the overlay
            debugPass.textureDebugMode = DebugCustomPass.TextureDebugMode.HeightMap;
            debugPass.debugOverlayRatio = 0.33f;
            debugPass.zoom = 1.0f;
            debugPass.showExtra = false;
            debugPass.minValue = debugPass.GetDefaultMinValue();
            debugPass.maxValue = debugPass.GetDefaultMaxValue();
        }
    }
}

{{ Notes: - The pass is intended for development and modding diagnostics; many texture sources are read from internal game systems and GPU buffers.
- Some sources (water simulation buffers, CBT camera buffers) require active simulation instances and only work if the relevant systems are present/initialized.
- The class relies on HDRenderPipeline resources and specific project shaders; ensure the proper RD/HD resources are available in the running environment. }}