Skip to content

MappingLUT

Source: MappingLUT.h

MappingLUT

class MappingLUT
src/light/layers/MappingLUT.h:35

The table mapping each logical light to the physical lights it drives.

A logical light can map to one physical light, to none, or to many. The sequential identity case needs no table at all and is the fast path.

Public Methods

MappingLUT() = default : An empty table, in identity mode until one is built.

inline ~MappingLUT() : Release whatever the table allocated.

MappingLUT(const MappingLUT &) = delete : Never copied: the table owns its allocations and two owners would double-free them.

inline void setIdentity(nrOfLightsType count) : Fast path: logical == physical, no table needed. hasLUT returns false.

inline bool build(nrOfLightsType logicalCount, nrOfLightsType maxDestinations) : Allocate the table, returning false only when memory genuinely cannot hold it.

inline void setMapping(nrOfLightsType logicalIdx, const nrOfLightsType * physicals, nrOfLightsType count) : Fill one logical entry's destinations (call sequentially, idx 0..logicalCount-1)

inline void finalize() : Call after all setMapping calls to close the last offset.

inline void free() : Release the table and return to the identity fast path.

inline bool hasLUT() const : Whether a table is allocated, rather than the identity fast path.

inline bool isPaged() const : Whether the destinations are split into pages.

inline nrOfLightsType logicalCount() const : How many logical lights the table covers.

inline nrOfLightsType destinationCount() const : How many physical destinations the table holds in total.

inline bool overwrites() const : Whether each physical destination is written by at most one logical light.

inline void setOverwrites(bool v) : Declare whether destinations are distinct, which chooses the copy or additive blend.

inline size_t memoryUsed() const : The bytes the table uses, which is zero in identity mode.

template<typename F> inline void forEachDestination(nrOfLightsType logicalIdx, F && callback) const : Walk the physical destinations of one logical light, on the hot path.

Public Static Attributes

constexpr nrOfLightsType kPageEntries = 4096 : How many destinations one page holds, sized to fit a fragmented heap.

constexpr nrOfLightsType kPageShift = 12 : The shift that turns a destination index into a page number.

constexpr nrOfLightsType kPageMask = - 1 : The mask that turns a destination index into a slot within its page.

constexpr int kMaxPages = 64 : How many pages the table can hold, capping it at 256K destinations.

Public Static Methods

static inline size_t estimateBytes(nrOfLightsType logicalCount, nrOfLightsType maxDest) : The bytes a prospective build would take, which paging does not change.

More info

Four mapping kinds

Identity means the logical index is the physical index, which a plain grid gives. A shuffled map reorders, as a serpentine grid does. An unmapped logical light has no physical output, which a sparse layout produces. A multimap drives several physical lights from one logical light, which mirroring produces. The last three need a table.

Compressed sparse row

Two arrays: one indexes each logical light into a run, the other holds the flat destinations. The container supplies the total, so every destination is in bounds by construction.

Paged destinations

A large map on a board without PSRAM can exceed the largest contiguous block while heap remains. The destinations then split into power-of-two pages that each fit a fragmented heap. Paging is the exception: output is identical either way, so it stays an allocation detail.