TexturePagePool

Remarks

A page is a fixed byte-size slice of a file's level data, numbered from the front. That is the decision the whole design turns on, and the alternatives were worse. A page per mip level maps onto IPageStore most obviously and is unusable: PageSize is one number, mip levels differ by factors of thousands, and PageResidency charges the budget residentPages × PageSize — so a 1×1 level would occupy, and be billed for, a slot big enough for a 2048×2048 one. A pool per texture gives every texture its own budget and its own eviction order, which is the failure PageResidency's own remarks name: three budgets to tune means there is no budget at all, and here it would be three thousand.

Fixed-size slices work because KTX2 stores level data smallest first. Page n is bytes [n·PageSize, (n+1)·PageSize) of the level data, and the level data runs from the 1×1 level upwards — so a contiguous prefix of pages is exactly a complete mip tail. "Pages 0 to k are resident" and "levels L and smaller are resident" are the same statement, which is what makes the accounting exact and the residency question answerable by counting.

Page 0 is pinned, and that is the floor the whole degradation story rests on. It holds the first PageSize bytes of level data, which is always at least the smallest levels, so a registered texture always has something complete to sample. A texture whose entire level data fits in one page is therefore never streamed at all.

⚠ The bytes stay in host memory and the pool never refuses. This is a byte pool, not a staging ring — Place is a copy into an array this owns, so the refusal Place allows for cannot arise here. What can still fail is a request, when the budget is full of pinned pages; that is Rejections and it is counted there.

Fields and properties (4)

• public int PageSize

  How many bytes one page occupies in the pool.

• public int SlotCount

  How many slots the pool has.

• public long Placements

  How many pages have been placed since this was created.

• public long Evictions

  How many have been evicted.

Methods (9)

• public TexturePagePool(ITextureStreamSource source, int slotCount, int pageSize = 65536)

  Creates a pool over a source.

• public void Register(int texture, Ktx2Layout layout)

  Says a texture exists and where its levels are.

• public bool TryGetLayout(int texture, out Ktx2Layout layout)

  What a texture's file said about itself, if it was registered.

• public int PageCount(int texture)

  How many pages a texture's level data occupies.

• public int PagesFor(int texture, int firstLevel)

  How many pages cover a tail down from a level.

• public ValueTask<int> LoadAsync(PageKey key, Memory<byte> destination, CancellationToken cancellation)

  Reads a page's bytes.

• public bool Place(PageKey key, int slot, ReadOnlySpan<byte> bytes)

  Puts a loaded page's bytes into a slot.

• public void Evict(PageKey key, int slot)
• public ReadOnlySpan<byte> Slot(int slot, out int length)

  One slot's bytes.

Used by (1)

• TextureStreamerVixen.Engine.Renderer