VirtualShadowAtlas

Remarks

The atlas outlives the frame, and that is the whole point. Every other target in this renderer is a graph transient — declared, aliased and forgotten — because its contents are about one frame. A shadow page's contents are about the world: a page whose slot it still holds, whose level's projection did not move, and whose casters did not move, holds depths that are still correct, and redrawing it is the cost a cascade pays four times a frame for nothing. So this owns its texture, and VirtualShadowPages owns the bookkeeping that says which pages are still true.

The marks come back a frame late, exactly as the cluster traversal's page requests do. What writes them is a dispatch this host has submitted and not waited for, so reading them where they were written would be the one stall a GPU-driven frame is arranged to avoid. Reading them at the head of the next frame costs a page a frame of latency, which is a surface briefly shadowed by the cascades instead — see ClusteredShading.Shadow, which falls through when a page is not there.

A bitset rather than a request list, for the reason VirtualShadowMark.rvn gives: the whole address space is sixteen maps of a thousand and twenty-four pages, so one bit each is two kilobytes of readback — against a compacted list that would need an atomic per pixel and a deduplication pass after it. A million pixels asking for the same page is one atomicOr that changes nothing.

Fields and properties (14)

• public const int MarkWords

  How many words the mark bitset occupies.

• public const PixelFormat Format

  The format the physical page atlas is.

• public VirtualShadowPages Pages

  The physical pages and the table that finds them.

• public PageResidency Residency

  What decides which pages are allocated — PageResidency, shared with geometry.

• public EffectSystem? Effects

  Where the marking variant is resolved from. Null marks nothing.

• public ComputePipelineCache? Pipelines

  Where the compute pipeline comes from. Null marks nothing.

• public float FirstTexel

  How many world units one texel of clipmap level zero covers.

• public int LevelCount

  How many maps this frame has, and how many of them are the clipmap's.

• public int ClipmapLevels

  How many of them are the directional clipmap's, which are always first.

• public int MarkedPages

  How many pages the last ServiceMarks saw asked for.

• public TextureHandle Texture

  The atlas, for a pass that draws into it.

• public TextureViewHandle View

  Its view.

• public bool IsBuilt

  Whether the atlas has been created and cleared at least once.

• public static EffectKey Key

  The effect key selecting the marking pass.

Methods (9)

• public VirtualShadowAtlas(IGraphicsDevice device, int pagesPerSide = 32)

  Creates an atlas on a device.

• public void Begin(ReadOnlySpan<VirtualShadowLevel> records, int clipmap, float firstTexel)

  Sets this frame's maps and uploads them.

• public void UploadTable()

  Hands the page table to the device, as the shading pass will read it.

• public bool Mark(ICommandList list, TextureViewHandle depth, RenderView camera, Int2 size)

  Records the marking dispatch, and clears the bitset it is about to fill.

• public int ServiceMarks(int maxLoads = 16)

  Reads the previous frame's marks and asks the residency service for what they named.

• public void Publish(ParameterCollection parameters, IReadOnlyList<string> passes, SamplerCache? samplers, RenderView camera, int height)

  Puts what a shading pass needs where it can find it.

• public bool EnsureAtlas()

  Creates the atlas, if it does not exist.

• public void MarkCleared()

  Says the atlas has been cleared, so a shading pass may read it.

• public void Dispose()

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Used by (5)

• ArenaThirdPersonShooter
• ArenaIlluminationThirdPersonShooter
• FrameDocumentTestsThirdPersonShooter.Frame.Tests
• CompositorBuilderVixen.Rendering
• VirtualShadowRendererVixen.Rendering