class

FPointCloudAccumulator

The persistent half of a scanned world: every point that landed on something that cannot move, held chunked by sector so it can be culled, thinned, evicted and written to disk a piece at a time.

Module
Game
Header
#include "PointCloud/PointCloudAccumulator.h"
Namespace
Mowo

Type aliases

AliasDescription
using FGpuStoreReadbackFn = bool (*)(void* gpuState, std::vector<FPointCloudSample>& out)

Properties

TypeNameDescription
static constexpr floatkEphemeralTicksPerSecondThe ephemeral half's clock. It is deliberately NOT the shot tick: a shot tick is part of the shot's identity (two machines re-tracing it must get the same rays) and it only advances while somebody is firing, whereas a silhouette has to keep fading after the trigger is released. Advance it from the frame clock at a fixed rate so the fade is the same length on every machine. Default 60.0f.
static constexpr floatkMaxFadeSecondsThe PERSISTENT half's fade clock. A scanned surface that never dims turns a scanner game into a lighting pass done once, so a point carries the moment it was revealed and the shader derives its remaining life from that — no per-frame CPU decay and no re-upload, which is the only way this stays affordable at millions of points. The stamp is a u16 of kBirthTicksPerSecond ticks. A point dark for longer than the longest fade a cloud can author is clamped to exactly that age by the expiry sweep, long before its stamp could wrap round and read as freshly scanned. Default 600.0f.
static constexpr uint32_tkMinEphemeralLifetimeTicks350 ms at the ephemeral ring's 60 Hz: the shortest fade-out allowed. Default 21.
static constexpr uint32_tkBirthClampTicksDefault static_cast<uint32_t>(kMaxFadeSeconds * FPointCloudLayout::kBirthTicksPerSecond).
static constexpr uint32_tkAgeSweepChunksPerUpdateDefault 2.
static constexpr uint32_tkFileVersion1 stored world-space float positions and an RGBA colour; it still loads, converted on the way in. Default 2.
static constexpr uint32_tkLegacyWorldSpaceVersionDefault 1.

Public functions

ReturnsNameDescription
voidConfigure
const FPointCloudBudget&GetBudget
uint32_tAddHitsAdmits a trace's hits and splits them: static ones join the persistent chunks, dynamic ones go to the owned ephemeral ring, which decays them.
uint32_tAddPoints
uint32_tAddScanPointsThe Embree scan hierarchy's output.
FPointCloudSampleSampleFromHit
voidSetGpuStoreThe GPU point store mode (r.PointCloud.GpuStore): the persistent cloud lives in a GPU hash table that inserts, dedups and fades it there, and this accumulator only forwards the new static samples — no CPU chunk, dedup table or page is touched.
boolIsGpuStore
voidTakeGpuPendingHands over every sample forwarded since the last call.
uint64_tGetGpuForwardedTotal forwarded samples, for the cost readout.
voidClear
voidFlushOrders every touched chunk by rank and refreshes its LOD prefix table.
voidCollectVisible
uint32_tGpuBufferPointsThe buffer a component needs for a cloud of maxPoints plus its ring: the page pool rounded down to whole pages (never below one) and the ring on top.
voidAdvanceEphemeral
voidAdvanceAllEphemeralsAdvances every cloud in the world.
uint64_tGetEphemeralTick
voidAdvanceAgefadeSeconds <= 0 turns ageing off and nothing is stamped.
voidAdvanceAllAges
boolIsAgeing
floatGetBirthClock
uint16_tGetBirthStamp
floatLifeOfBirthThe remaining life the shader will compute for a stamp, for tests and for gameplay that wants to know whether a sector has gone dark.
PointCloudDrawStyleMakePersistentStyleDraw style for the persistent half: the component's authored splat and fade rows plus this accumulator's live fade clock.
const FPointCloudEphemeral&GetEphemeral
FPointCloudEphemeral&GetEphemeral
uint32_tGetEphemeralFirstPointFirst point of the region the ring writes: immediately past the last page, i.e.
const std::unordered_map<uint64_t, FPointCloudChunk>&GetChunks
std::unordered_map<uint64_t, FPointCloudChunk>&GetChunks
FPointCloudSectorSectorOf
uint32_tExtractChunksInRectWorld streaming's half of the cloud.
uint32_tExtractAllChunks
uint32_tAdoptChunksTakes as many chunks as the page pool has room for and leaves the rest in chunks — a caller that ignores the remainder is dropping player-scanned points, which is why they are handed back rather than silently discarded.
const FPointCloudStats&GetStats
uint32_tGetTotalPoints
FPointCloudMemoryMeasureMemory
boolSaveToMemoryA scanned world is far too big to live in the component's MDF node, so it persists as its own chunk stream — zstd over a flat record per sector.
boolCaptureSavePayloadSaveToMemory in two halves, for a save that must not stall the game thread on zstd: the capture copies the chunk records (the only part that reads the live cloud), the compression turns that capture into exactly the bytes SaveToMemory would have written, on any thread.
boolCompressSavePayload
boolLoadFromMemory
boolSaveToFile
boolLoadFromFile
voidSetGpuStoreReadbackHook
FGpuStoreReadbackFnGetGpuStoreReadbackHook
boolDecodeGpuStoreSlot
boolHoldsGpuStorePoints
boolCaptureSavePayloadWithGpuStore
boolSaveToMemoryWithGpuStore
uint32_tGetLastGpuStoreReadbackCount
uint32_tRankOfRank of a point, from the dedup cell it occupies.
uint32_tDedupCellQuantaThe dedup cell edge in position quanta for a range band: the largest whole number of quanta that does not exceed that band's step, so two points one step apart never share a cell.
Vec3WorldPositionWorld position of a record held by a chunk of sector.
PointCloudPointEncodeThe record a sample becomes in sector's chunk, stamped with this accumulator's current birth time.

Function details

Configure

C++
void Configure(const FPointCloudBudget& budget)

GetBudget

C++
const FPointCloudBudget& GetBudget() const

AddHits

C++
uint32_t AddHits(const FLidarHit* hits, uint32_t count, uint64_t tick, const Vec3& viewerPosition, uint8_t owner = 0, uint8_t rangeBand = 0)

Admits a trace's hits and splits them: static ones join the persistent chunks, dynamic ones go to the owned ephemeral ring, which decays them. One sink rather than two because the caller has one list and splitting it at every call site is how the dynamic half ends up dropped — which is exactly what happened: the ring was written, tested, and never fed. Returns the number of STATIC points admitted. owner is the tint slot the points carry (0 = this player's own scan, 1..7 = the others', as the renderer reads it).

AddPoints

C++
uint32_t AddPoints(const FPointCloudSample* samples, uint32_t count, uint64_t tick, const Vec3& viewerPosition)

AddScanPoints

C++
uint32_t AddScanPoints(const FScanPoint* points, uint32_t count, bool dynamic, uint64_t tick, const Vec3& viewerPosition)

The Embree scan hierarchy's output. It carries no motion type, so the caller says whether the pulse hit something that can move.

SampleFromHit

C++
static FPointCloudSample SampleFromHit(const FLidarHit& hit)

SetGpuStore

C++
void SetGpuStore(bool enabled)

The GPU point store mode (r.PointCloud.GpuStore): the persistent cloud lives in a GPU hash table that inserts, dedups and fades it there, and this accumulator only forwards the new static samples — no CPU chunk, dedup table or page is touched. The ephemeral ring stays here. Points held before the switch keep drawing from their pages.

IsGpuStore

C++
bool IsGpuStore() const

TakeGpuPending

C++
void TakeGpuPending(std::vector<FPointCloudSample>& out)

Hands over every sample forwarded since the last call.

GetGpuForwarded

C++
uint64_t GetGpuForwarded() const

Total forwarded samples, for the cost readout.

Clear

C++
void Clear()

Flush

C++
void Flush()

Orders every touched chunk by rank and refreshes its LOD prefix table. Cheap and idempotent; AddHits leaves chunks unsorted so a burst pays one counting sort per chunk instead of one per point.

CollectVisible

C++
void CollectVisible(const FPointCloudView& view, std::vector<FPointCloudDrawRange>& outRanges) const

GpuBufferPoints

C++
static uint32_t GpuBufferPoints(uint32_t maxPoints, uint32_t ephemeralCapacity)

The buffer a component needs for a cloud of maxPoints plus its ring: the page pool rounded down to whole pages (never below one) and the ring on top.

AdvanceEphemeral

C++
void AdvanceEphemeral(float deltaSeconds)

AdvanceAllEphemerals

C++
static void AdvanceAllEphemerals(World& world, float deltaSeconds)

Advances every cloud in the world. The fade has to keep running on a scene tick and not on a draw, because a scene drawn twice in one frame (an editor viewport beside a PIE view, split screen) would otherwise age its points twice as fast as a scene drawn once.

GetEphemeralTick

C++
uint64_t GetEphemeralTick() const

AdvanceAge

C++
void AdvanceAge(float deltaSeconds, float fadeSeconds)

fadeSeconds <= 0 turns ageing off and nothing is stamped.

AdvanceAllAges

C++
static void AdvanceAllAges(World& world, float deltaSeconds)

IsAgeing

C++
bool IsAgeing() const

GetBirthClock

C++
float GetBirthClock() const

GetBirthStamp

C++
uint16_t GetBirthStamp() const

LifeOfBirth

C++
float LifeOfBirth(uint16_t birth) const

The remaining life the shader will compute for a stamp, for tests and for gameplay that wants to know whether a sector has gone dark.

MakePersistentStyle

C++
PointCloudDrawStyle MakePersistentStyle(const PointCloudComponent& component) const

Draw style for the persistent half: the component's authored splat and fade rows plus this accumulator's live fade clock.

GetEphemeral

C++
const FPointCloudEphemeral& GetEphemeral() const

GetEphemeral

C++
FPointCloudEphemeral& GetEphemeral()

GetEphemeralFirstPoint

C++
uint32_t GetEphemeralFirstPoint() const

First point of the region the ring writes: immediately past the last page, i.e. exactly where the component's extra ephemeral capacity begins.

GetChunks

C++
const std::unordered_map<uint64_t, FPointCloudChunk>& GetChunks() const

GetChunks

C++
std::unordered_map<uint64_t, FPointCloudChunk>& GetChunks()

SectorOf

C++
static FPointCloudSector SectorOf(const Vec3& position)

ExtractChunksInRect

C++
uint32_t ExtractChunksInRect(float minX, float minZ, float maxX, float maxZ, std::vector<FPointCloudChunk>& outChunks)

World streaming's half of the cloud. A sector that streams out hands its chunks to FSectorCloudResidency, which parks them and hands them back on load; the extract releases the GPU pages and the point memory with them. Membership is by the chunk's sector CENTRE, so a chunk on a cell boundary belongs to exactly one cell and a park and a restore cannot both claim it.

ExtractAllChunks

C++
uint32_t ExtractAllChunks(std::vector<FPointCloudChunk>& outChunks)

AdoptChunks

C++
uint32_t AdoptChunks(std::vector<FPointCloudChunk>& chunks)

Takes as many chunks as the page pool has room for and leaves the rest in chunks — a caller that ignores the remainder is dropping player-scanned points, which is why they are handed back rather than silently discarded. Points landing on a sector that was scanned again while it was parked go through insertion, so the dedup grid decides, not arrival order.

GetStats

C++
const FPointCloudStats& GetStats() const

GetTotalPoints

C++
uint32_t GetTotalPoints() const

MeasureMemory

C++
FPointCloudMemory MeasureMemory() const

SaveToMemory

C++
bool SaveToMemory(std::vector<uint8_t>& outBytes) const

A scanned world is far too big to live in the component's MDF node, so it persists as its own chunk stream — zstd over a flat record per sector. Records are stored exactly as the GPU reads them, page aside, so a round-trip is bit-exact and a reloaded cloud accepts exactly the same new points that the original would have. The file's budget does not travel: a cloud loads into the budget this accumulator already has, thinned densest-chunk-first if it does not fit. Taking the writer's budget is how a component sized for two million points was quietly regrown to the eight million some older save named.

CaptureSavePayload

C++
bool CaptureSavePayload(std::vector<uint8_t>& outCapture) const

SaveToMemory in two halves, for a save that must not stall the game thread on zstd: the capture copies the chunk records (the only part that reads the live cloud), the compression turns that capture into exactly the bytes SaveToMemory would have written, on any thread.

CompressSavePayload

C++
static bool CompressSavePayload(const std::vector<uint8_t>& capture, std::vector<uint8_t>& outBytes)

LoadFromMemory

C++
bool LoadFromMemory(const uint8_t* bytes, size_t size)

SaveToFile

C++
bool SaveToFile(const std::string& path) const

LoadFromFile

C++
bool LoadFromFile(const std::string& path)

SetGpuStoreReadbackHook

C++
static void SetGpuStoreReadbackHook(FGpuStoreReadbackFn fn)

GetGpuStoreReadbackHook

C++
static FGpuStoreReadbackFn GetGpuStoreReadbackHook()

DecodeGpuStoreSlot

C++
static bool DecodeGpuStoreSlot(uint64_t key, const uint32_t record[4], FPointCloudSample& out)

HoldsGpuStorePoints

C++
bool HoldsGpuStorePoints(const void* gpuState) const

CaptureSavePayloadWithGpuStore

C++
bool CaptureSavePayloadWithGpuStore(void* gpuState, std::vector<uint8_t>& outCapture) const

SaveToMemoryWithGpuStore

C++
bool SaveToMemoryWithGpuStore(void* gpuState, std::vector<uint8_t>& outBytes) const

GetLastGpuStoreReadbackCount

C++
uint32_t GetLastGpuStoreReadbackCount() const

RankOf

C++
uint32_t RankOf(const FPointCloudSector& sector, const PointCloudPoint& point) const

Rank of a point, from the dedup cell it occupies. Public because the serializer and the tests both need to agree with insertion about which points a decimated chunk keeps.

DedupCellQuanta

C++
uint32_t DedupCellQuanta(uint32_t rangeBand = 0) const

The dedup cell edge in position quanta for a range band: the largest whole number of quanta that does not exceed that band's step, so two points one step apart never share a cell.

WorldPosition

C++
static Vec3 WorldPosition(const FPointCloudSector& sector, const PointCloudPoint& point)

World position of a record held by a chunk of sector.

Encode

C++
PointCloudPoint Encode(const FPointCloudSector& sector, const FPointCloudSample& sample) const

The record a sample becomes in sector's chunk, stamped with this accumulator's current birth time.

Generated from PointCloud/PointCloudAccumulator.h via game.json · Nov 5, 2026Version 1.0.0