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
| Alias | Description |
|---|---|
using FGpuStoreReadbackFn = bool (*)(void* gpuState, std::vector<FPointCloudSample>& out) |
Properties
| Type | Name | Description |
|---|---|---|
static constexpr float | kEphemeralTicksPerSecond | The 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 float | kMaxFadeSeconds | The 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_t | kMinEphemeralLifetimeTicks | 350 ms at the ephemeral ring's 60 Hz: the shortest fade-out allowed. Default 21. |
static constexpr uint32_t | kBirthClampTicks | Default static_cast<uint32_t>(kMaxFadeSeconds * FPointCloudLayout::kBirthTicksPerSecond). |
static constexpr uint32_t | kAgeSweepChunksPerUpdate | Default 2. |
static constexpr uint32_t | kFileVersion | 1 stored world-space float positions and an RGBA colour; it still loads, converted on the way in. Default 2. |
static constexpr uint32_t | kLegacyWorldSpaceVersion | Default 1. |
Public functions
| Returns | Name | Description |
|---|---|---|
void | Configure | |
const FPointCloudBudget& | GetBudget | |
uint32_t | AddHits | 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. |
uint32_t | AddPoints | |
uint32_t | AddScanPoints | The Embree scan hierarchy's output. |
FPointCloudSample | SampleFromHit | |
void | SetGpuStore | 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. |
bool | IsGpuStore | |
void | TakeGpuPending | Hands over every sample forwarded since the last call. |
uint64_t | GetGpuForwarded | Total forwarded samples, for the cost readout. |
void | Clear | |
void | Flush | Orders every touched chunk by rank and refreshes its LOD prefix table. |
void | CollectVisible | |
uint32_t | GpuBufferPoints | 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. |
void | AdvanceEphemeral | |
void | AdvanceAllEphemerals | Advances every cloud in the world. |
uint64_t | GetEphemeralTick | |
void | AdvanceAge | fadeSeconds <= 0 turns ageing off and nothing is stamped. |
void | AdvanceAllAges | |
bool | IsAgeing | |
float | GetBirthClock | |
uint16_t | GetBirthStamp | |
float | LifeOfBirth | 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. |
PointCloudDrawStyle | MakePersistentStyle | Draw 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_t | GetEphemeralFirstPoint | First 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 | |
FPointCloudSector | SectorOf | |
uint32_t | ExtractChunksInRect | World streaming's half of the cloud. |
uint32_t | ExtractAllChunks | |
uint32_t | AdoptChunks | 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. |
const FPointCloudStats& | GetStats | |
uint32_t | GetTotalPoints | |
FPointCloudMemory | MeasureMemory | |
bool | SaveToMemory | 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. |
bool | CaptureSavePayload | 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. |
bool | CompressSavePayload | |
bool | LoadFromMemory | |
bool | SaveToFile | |
bool | LoadFromFile | |
void | SetGpuStoreReadbackHook | |
FGpuStoreReadbackFn | GetGpuStoreReadbackHook | |
bool | DecodeGpuStoreSlot | |
bool | HoldsGpuStorePoints | |
bool | CaptureSavePayloadWithGpuStore | |
bool | SaveToMemoryWithGpuStore | |
uint32_t | GetLastGpuStoreReadbackCount | |
uint32_t | RankOf | Rank of a point, from the dedup cell it occupies. |
uint32_t | DedupCellQuanta | 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. |
Vec3 | WorldPosition | World position of a record held by a chunk of sector. |
PointCloudPoint | Encode | The record a sample becomes in sector's chunk, stamped with this accumulator's current birth time. |
Function details
Configure
void Configure(const FPointCloudBudget& budget)GetBudget
const FPointCloudBudget& GetBudget() constAddHits
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
uint32_t AddPoints(const FPointCloudSample* samples, uint32_t count, uint64_t tick, const Vec3& viewerPosition)AddScanPoints
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
static FPointCloudSample SampleFromHit(const FLidarHit& hit)SetGpuStore
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
bool IsGpuStore() constTakeGpuPending
void TakeGpuPending(std::vector<FPointCloudSample>& out)Hands over every sample forwarded since the last call.
GetGpuForwarded
uint64_t GetGpuForwarded() constTotal forwarded samples, for the cost readout.
Clear
void Clear()Flush
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
void CollectVisible(const FPointCloudView& view, std::vector<FPointCloudDrawRange>& outRanges) constGpuBufferPoints
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
void AdvanceEphemeral(float deltaSeconds)AdvanceAllEphemerals
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
uint64_t GetEphemeralTick() constAdvanceAge
void AdvanceAge(float deltaSeconds, float fadeSeconds)fadeSeconds <= 0 turns ageing off and nothing is stamped.
AdvanceAllAges
static void AdvanceAllAges(World& world, float deltaSeconds)IsAgeing
bool IsAgeing() constGetBirthClock
float GetBirthClock() constGetBirthStamp
uint16_t GetBirthStamp() constLifeOfBirth
float LifeOfBirth(uint16_t birth) constThe 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
PointCloudDrawStyle MakePersistentStyle(const PointCloudComponent& component) constDraw style for the persistent half: the component's authored splat and fade rows plus this accumulator's live fade clock.
GetEphemeral
const FPointCloudEphemeral& GetEphemeral() constGetEphemeral
FPointCloudEphemeral& GetEphemeral()GetEphemeralFirstPoint
uint32_t GetEphemeralFirstPoint() constFirst point of the region the ring writes: immediately past the last page, i.e. exactly where the component's extra ephemeral capacity begins.
GetChunks
const std::unordered_map<uint64_t, FPointCloudChunk>& GetChunks() constGetChunks
std::unordered_map<uint64_t, FPointCloudChunk>& GetChunks()SectorOf
static FPointCloudSector SectorOf(const Vec3& position)ExtractChunksInRect
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
uint32_t ExtractAllChunks(std::vector<FPointCloudChunk>& outChunks)AdoptChunks
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
const FPointCloudStats& GetStats() constGetTotalPoints
uint32_t GetTotalPoints() constMeasureMemory
FPointCloudMemory MeasureMemory() constSaveToMemory
bool SaveToMemory(std::vector<uint8_t>& outBytes) constA 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
bool CaptureSavePayload(std::vector<uint8_t>& outCapture) constSaveToMemory 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
static bool CompressSavePayload(const std::vector<uint8_t>& capture, std::vector<uint8_t>& outBytes)LoadFromMemory
bool LoadFromMemory(const uint8_t* bytes, size_t size)SaveToFile
bool SaveToFile(const std::string& path) constLoadFromFile
bool LoadFromFile(const std::string& path)SetGpuStoreReadbackHook
static void SetGpuStoreReadbackHook(FGpuStoreReadbackFn fn)GetGpuStoreReadbackHook
static FGpuStoreReadbackFn GetGpuStoreReadbackHook()DecodeGpuStoreSlot
static bool DecodeGpuStoreSlot(uint64_t key, const uint32_t record[4], FPointCloudSample& out)HoldsGpuStorePoints
bool HoldsGpuStorePoints(const void* gpuState) constCaptureSavePayloadWithGpuStore
bool CaptureSavePayloadWithGpuStore(void* gpuState, std::vector<uint8_t>& outCapture) constSaveToMemoryWithGpuStore
bool SaveToMemoryWithGpuStore(void* gpuState, std::vector<uint8_t>& outBytes) constGetLastGpuStoreReadbackCount
uint32_t GetLastGpuStoreReadbackCount() constRankOf
uint32_t RankOf(const FPointCloudSector& sector, const PointCloudPoint& point) constRank 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
uint32_t DedupCellQuanta(uint32_t rangeBand = 0) constThe 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
static Vec3 WorldPosition(const FPointCloudSector& sector, const PointCloudPoint& point)World position of a record held by a chunk of sector.
Encode
PointCloudPoint Encode(const FPointCloudSector& sector, const FPointCloudSample& sample) constThe record a sample becomes in sector's chunk, stamped with this accumulator's current birth time.