SceneManager

The SceneManager class controls the initialization and management of all scene-specific resources. It provides an efficient mechanism for uploading scalar and storage buffers, supports CPU callbacks for GPU-driven scene graphs, and includes a shader printf system. It also allows access to internal resources like RadixSort and SpatialTree for reuse in user environments.

#include <scene/TellusimSceneManager.h>

Constructors

SceneManager()

Methods

Clear manager.

void clear()

---

Check manager.

bool isCreated() const

---

Terminated flag.

bool isTerminated() const

---

Manager flags.

Flags getFlags() const
bool hasFlag(Flags flags) const
bool hasFlags(Flags flags) const
String getFlagsName() const

---

Set default texture parameters.

void set2DTextureParameters(const Device &device, uint32_t size = 2048, uint32_t layers = 256, uint32_t pools = 8)
void setCubeTextureParameters(const Device &device, uint32_t size = 1024, uint32_t layers = 64, uint32_t pools = 4)

Type	Name	Description
uint32_t	size	Maximum texture size.
uint32_t	layers	Number of array layers.
uint32_t	pools	Number of texture pools.

---

Set default environment parameters.

void setEnvironmentParameters(const Device &device, uint32_t brdf = 256, uint32_t diffuse = 32, uint32_t specular = 1024, uint32_t samples = 1024)

Type	Name	Description
uint32_t	brdf	BRDF texture size.
uint32_t	diffuse	Diffuse texture size.
uint32_t	specular	Specular texture size.
uint32_t	samples	Number of samples.

---

Set default buffer parameters.

void setBufferParameters(const Device &device, size_t memory = (size_t) 1024 * 1024 * 512, uint32_t storage = 0, uint32_t scalar = 0, uint32_t vertex = 0, uint32_t index = 0, uint32_t build = 0, Flags flags = FlagNone)
void setBufferParameters(const Device &device, size_t memory, Flags flags)

Type	Name	Description
size_t	memory	Total buffer memory allocation.
uint32_t	storage	Storage buffer split ratio.
uint32_t	scalar	Scalar buffer split ratio.
uint32_t	vertex	Vertex buffer split ratio.
uint32_t	index	Index buffer split ratio.
uint32_t	build	Build buffer split ratio.

---

2D texture parameters.

void set2DTextureParameters(Format format = FormatBC7RGBAu8n, uint32_t size = 2048, uint32_t layers = 256, uint32_t pools = 8)
Format get2DTextureFormat() const
uint32_t get2DTextureSize() const
uint32_t get2DTextureLayers() const
uint32_t get2DTexturePools() const
uint32_t getNum2DPoolTextures() const
Texture get2DPoolTexture(uint32_t index)

Type	Name	Description
Format	format	2D texture format.
uint32_t	size	Maximum texture size.
uint32_t	layers	Number of 2D texture layers.
uint32_t	pools	Number of 2D texture pool (total number of textures).

---

Cube texture parameters.

void setCubeTextureParameters(Format format = FormatBC6RGBf16u, uint32_t size = 1024, uint32_t layers = 64, uint32_t pools = 4)
Format getCubeTextureFormat() const
uint32_t getCubeTextureSize() const
uint32_t getCubeTextureLayers() const
uint32_t getCubeTexturePools() const
uint32_t getNumCubePoolTextures() const
Texture getCubePoolTexture(uint32_t index)

Type	Name	Description
Format	format	Cube texture format.
uint32_t	size	Maximum Cube texture size.
uint32_t	layers	Number of Cube texture layers.
uint32_t	pools	Number of Cube texture pool (total number of textures).

---

Environment parameters.

void setEnvironmentParameters(Format format = FormatRGBAf16, uint32_t brdf = 256, uint32_t diffuse = 32, uint32_t specular = 1024, uint32_t samples = 1024)
Format getEnvironmentBRDFFormat() const
uint32_t getEnvironmentBRDFSize() const
uint32_t getEnvironmentDiffuseSize() const
uint32_t getEnvironmentSpecularSize() const
uint32_t getEnvironmentSamples() const

Type	Name	Description
Format	format	BRDF texture format.
uint32_t	brdf	BRDF texture size.
uint32_t	diffuse	Diffuse texture size.
uint32_t	specular	Specular texture size.
uint32_t	samples	Number of samples.

---

Storage buffer parameters.

void setStorageBufferParameters(size_t size, Flags flags = SceneBuffer::FlagNone)
size_t getStorageBufferSize() const
SceneBuffer getStorageBuffer()
Buffer getStorageHeapBuffer()

Type	Name	Description
size_t	size	Storage buffer size in bytes.
SceneBuffer::Flags	flags	Additional storage buffer flags.

---

Scalar buffer parameters.

void setScalarBufferParameters(size_t size, Flags flags = SceneBuffer::FlagNone)
size_t getScalarBufferSize() const
SceneBuffer getScalarBuffer()
Buffer getScalarHeapBuffer()

Type	Name	Description
size_t	size	Scalar buffer size in bytes.
SceneBuffer::Flags	flags	Additional scalar buffer flags.

---

Vertex buffer parameters.

void setVertexBufferParameters(size_t size, Flags flags = SceneBuffer::FlagNone)
size_t getVertexBufferSize() const
SceneBuffer getVertexBuffer()
Buffer getVertexHeapBuffer()

Type	Name	Description
size_t	size	Vertex buffer size in bytes.
SceneBuffer::Flags	flags	Additional vertex buffer flags.

---

Index buffer parameters.

void setIndexBufferParameters(size_t size, Flags flags = SceneBuffer::FlagNone)
size_t getIndexBufferSize() const
SceneBuffer getIndexBuffer()
Buffer getIndexHeapBuffer()

Type	Name	Description
size_t	size	Index buffer size in bytes.
SceneBuffer::Flags	flags	Additional index buffer flags.

---

Build buffer parameters.

void setBuildBufferParameters(size_t size, Flags flags = Buffer::FlagNone)
size_t getBuildBufferSize() const
Buffer getBuildBuffer()

Type	Name	Description
size_t	size	Build buffer size in bytes.

---

Animator parameters.

void setAnimatorParameters(const Device &device, uint32_t stack = 8, uint32_t cache = 4, Flags flags = SceneAnimator::DefaultFlags)
void setAnimatorFlags(const Device &device, Flags flags)
Flags getAnimatorFlags() const
uint32_t getAnimatorStack() const
uint32_t getAnimatorCache() const
SceneAnimator getAnimator() const

Type	Name	Description
uint32_t	stack	Animation stack depth.
uint32_t	cache	Animation cache size.
SceneAnimator::Flags	flags	Additional animator flags.

---

Spatial parameters.

void setSpatialParameters(const Device &device, uint32_t nodes = 1024 * 512, uint32_t steps = 5, Flags flags = SceneSpatial::DefaultFlags)
void setSpatialFlags(const Device &device, Flags flags)
Flags getSpatialFlags() const
uint32_t getSpatialNodes() const
uint32_t getSpatialSteps() const
SceneSpatial getSpatial() const

Type	Name	Description
uint32_t	nodes	Maximum number of next step nodes (not the maximal number of nodes).
uint32_t	steps	Number of spatial transform steps.
SceneSpatial::Flags	flags	Additional spatial flags.

---

Tracer parameters.

void setTracerParameters(const Device &device, uint32_t rays = 1024 * 256, uint32_t steps = 5, Flags flags = SceneTracer::DefaultFlags)
void setTracerFlags(const Device &device, Flags flags)
Flags getTracerFlags() const
uint32_t getTracerRays() const
uint32_t getTracerSteps() const
SceneTracer getTracer() const

Type	Name	Description
uint32_t	rays	Maximum number of rays (including internal).
uint32_t	steps	Number of tracer intersection steps.
SceneTracer::Flags	flags	Additional tracer flags.

---

Collider parameters.

void setColliderParameters(const Device &device, uint32_t collisions = 1024 * 256, uint32_t steps = 5, Flags flags = SceneCollider::DefaultFlags)
void setColliderFlags(const Device &device, Flags flags)
Flags getColliderFlags() const
uint32_t getColliderCollisions() const
uint32_t getColliderSteps() const
SceneCollider getCollider() const

Type	Name	Description
uint32_t	collisions	Maximum number of collisions (including internal).
uint32_t	steps	Number of collider intersection steps.
SceneCollider::Flags	flags	Additional collider flags.

---

Cloner parameters.

void setClonerParameters(const Device &device, uint32_t nodes = 1024 * 128, Flags flags = SceneCloner::DefaultFlags)
void setClonerFlags(const Device &device, Flags flags)
Flags getClonerFlags() const
uint32_t getClonerNodes() const
SceneCloner getCloner() const

Type	Name	Description
uint32_t	nodes	Maximum number of cloned nodes.
SceneCloner::Flags	flags	Additional cloner flags.

---

Stream parameters.

void setStreamParameters(uint32_t texcoords = 4, uint32_t colors = 2, float64_t fps = 30.0, Flags flags = SceneStream::DefaultFlags)
void setStreamFlags(Flags flags)
Flags getStreamFlags() const
uint32_t getStreamTexCoords() const
uint32_t getStreamColors() const
float64_t getStreamFps() const
SceneStream getStream() const

Type	Name	Description
uint32_t	texcoords	Maimum number of texture coordinates.
uint32_t	colors	Maimum number of vertex colors.
float64_t	fps	Animation frames per second.
SceneStream::Flags	flags	Additional stream flags.

---

Prefix scan parameters.

void setPrefixScanParameters(const Device &device, uint32_t groups = 256, uint32_t regions = 16)
uint32_t getPrefixScanGroups() const
uint32_t getPrefixScanRegions() const
PrefixScan getPrefixScan() const

Type	Name	Description
uint32_t	groups	Kernel group size.
uint32_t	regions	Number of parallel regions.

---

Radix sort parameters.

void setRadixSortParameters(const Device &device, uint32_t size = 1024 * 1024, uint32_t groups = 256, uint32_t regions = 16)
uint32_t getRadixSortSize() const
uint32_t getRadixSortGroups() const
uint32_t getRadixSortRegions() const
RadixSort getRadixSort() const

Type	Name	Description
uint32_t	size	Maximum number of sorted elements.
uint32_t	groups	Kernel group size.
uint32_t	regions	Number of parallel regions (size multiplicator).

---

Bitonic sort parameters (local sort only).

void setBitonicSortParameters(const Device &device, uint32_t groups = 1024, uint32_t regions = 1024 * 64)
uint32_t getBitonicSortGroups() const
uint32_t getBitonicSortRegions() const
BitonicSort getBitonicSort() const

Type	Name	Description
uint32_t	groups	Kernel group size.
uint32_t	regions	Number of parallel regions (size multiplicator).

---

Spatial tree parameters.

void setSpatialTreeParameters(const Device &device, uint32_t size = 1024 * 1024, uint32_t groups = 256, uint32_t regions = 16)
uint32_t getSpatialTreeSize() const
uint32_t getSpatialTreeGroups() const
uint32_t getSpatialTreeRegions() const
SpatialTree getSpatialTree() const

Type	Name	Description
uint32_t	size	Maximum spatial tree size.
uint32_t	groups	Kernel group size.
uint32_t	regions	Number of parallel regions (size multiplicator).

---

Cube filter parameters.

void setCubeFilterParameters(const Device &device, uint32_t order = 3, uint32_t size = 1024, uint32_t groups = 256)
uint32_t getCubeFilterOrder() const
uint32_t getCubeFilterSize() const
uint32_t getCubeFilterGroups() const
CubeFilter getCubeFilter() const

Type	Name	Description
uint32_t	order	Maximum filter order (2, 3, 5).
uint32_t	size	Maximum filter size.
uint32_t	groups	Reduction group size.

---

Printf buffer parameters.

void setPrintfParameters(uint32_t size = 1024)
uint32_t getPrintfBufferSize() const
uint32_t getPrintfBufferID() const
uint32_t getPrintfBufferIndex() const

---

Create scene manager.

bool create(const Device &device, Flags flags = DefaultFlags, const CreateCallback *func = nullptr, Async *async = nullptr)

Type	Name	Description
SceneManager::Flags	flags	Manager flags

---

Copy buffer data.

void copyStorageData(uint32_t index, uint32_t src, size_t size)
void copyScalarData(uint32_t index, uint32_t src, size_t size)

Type	Name	Description
uint32_t	index	Buffer element index.
uint32_t	src	Buffer source element index.
size_t	size	Data size in bytes.

---

Set buffer data.

void setStorageData(uint32_t index, const void *src, size_t size)
void setScalarData(uint32_t index, const void *src, size_t size)
template<> void setStorage(uint32_t index, const Type &data)
template<> void setScalar(uint32_t index, const Type &data)

Type	Name	Description
uint32_t	index	Buffer element index.
void	src	Data pointer.
size_t	size	Data size in bytes.

---

Set buffer data.

void setStorageData(uint32_t index, uint32_t swizzle, uint32_t data)
void setScalarData(uint32_t index, uint32_t data)

Type	Name	Description
uint32_t	index	Buffer element index.
uint32_t	swizzle	Storage buffer swizzle index.
uint32_t	data	Data value.

---

Fetch buffer data.

void fetchBufferData(Buffer &buffer, size_t offset, size_t size, const FetchedCallback &func, uint32_t id = 0)
void printStorageData(uint32_t index, size_t size, const char *name = nullptr)
void printScalarData(uint32_t index, size_t size, const char *name = nullptr)
void printBufferData(Buffer &buffer, size_t offset, size_t size, const char *name = nullptr)
void printBufferData(Buffer &buffer, size_t size, const char *name = nullptr)

Type	Name	Description
uint32_t	id	Fetch identifier.
uint32_t	index	Buffer element index.
SceneManager::FetchedCallback	func	Fetch callback function.

---

Trace scene.

bool traceScene(const Scene &scene, const Ray *rays, uint32_t num, const TracedCallback &func, uint32_t id = 0)
bool traceScene(const Scene &scene, Ray ray, const TracedCallback &func, uint32_t id = 0)
bool printRay(const Scene &scene, Ray ray, const char *name = nullptr)

Type	Name	Description
uint32_t	id	Trace identifier.
SceneTracer::Ray	rays	Rays array.
uint32_t	num	Number of rays.
SceneManager::TracedCallback	func	Traced callback function.

---

Collide scene.

bool collideScene(const Scene &scene, const Collision *collisions, uint32_t num, const CollidedCallback &func, uint32_t id = 0)
bool collideScene(const Scene &scene, Collision collision, const CollidedCallback &func, uint32_t id = 0)
bool printCollision(const Scene &scene, Collision collision, const char *name = nullptr)

Type	Name	Description
uint32_t	id	Collide identifier.
SceneCollider::Collision	collisions	Collisions array.
uint32_t	num	Number of collisions.
SceneManager::CollidedCallback	func	Collided callback function.

---

Clone scene.

uint32_t addClonedCallback(const ClonedCallback &func)
bool removeClonedCallback(uint32_t index)
uint32_t getNumClonedCallbacks() const

Type	Name	Description
	id	Callback identifier.
	clones	Cloned nodes array.
	num	Number of cloned nodes.
	payload	Payload data.

---

Update scene manager.

bool update(const Device &device, Async &async, uint64_t frame = 0, size_t memory = 0, uint64_t usec = 10000, Flags flags = FlagNone)

Type	Name	Description
Async	async	Async pointer.
uint64_t	frame	Incremental frame number.
size_t	memory	Memory allocation limit.
uint64_t	usec	Maximum update time in microseconds (total).

---

Dispatch scene manager.

void dispatch(const Device &device, Compute &compute, Flags flags = FlagNone)

Type	Name	Description
Compute	compute	Compute interface.

---

Build scene manager.

void build(const Device &device, Flags flags = FlagNone)

---

Flush scene manager.

void flush(const Device &device)

---

Process scene manager.

bool process(Async &async, uint64_t usec = 100000)
void terminate()

Type	Name	Description
Async	async	Async pointer.
uint64_t	usec	Maximum process time in microseconds (per-class).

---

Memory usage.

size_t getTextureMemory(bool usage = true) const
size_t getBufferMemory(bool usage = true) const
size_t getMemory(bool usage = true) const

Type	Name	Description
bool	usage	Current memory usage if true.

---

Load scene manager.

bool load(const Xml &xml)
bool load(const Json &json)
bool load(Stream &stream)

---

Save scene manager.

bool save(Xml &xml, bool force = false, bool comment = false) const
bool save(Json &json, bool force = false) const
bool save(Stream &stream) const

Type	Name	Description
bool	force	Keep default values.
bool	comment	Comment default values.

---

Global shader cache.

static bool hasShaderCache()
static bool setShaderCache(const char *name)
static bool setShaderCache(const String &name)
static void clearShaderCache()

---

Global texture cache.

static bool hasTextureCache()
static bool setTextureCache(const char *name)
static bool setTextureCache(const String &name)
static void clearTextureCache()

Types

using CreateCallback = Function<void(uint32_t progress)>
using FetchedCallback = Function<void(uint32_t id, const void *src, size_t size)>
using TracedCallback = Function<void(uint32_t id, const SceneTracer::Ray *rays, uint32_t num)>
using CollidedCallback = Function<void(uint32_t id, const SceneCollider::Collision *collisions, uint32_t num)>
using ClonedCallback = Function<void(uint32_t id, const SceneCloner::Clone *clones, uint32_t num, uint32_t payload)>

Enums

Flags

Manager flags.

Name	Value	Description
FlagNone	0
FlagVerbose	(1 << 0)	Verbose processing.
FlagQuery	(1 << 1)	Time query profiler.
FlagMTime	(1 << 2)	Check modification time.
FlagPrintf	(1 << 3)	Create printf resources.
FlagTracer	(1 << 4)	Create spatial tracer.
FlagCollider	(1 << 5)	Create spatial collider.
FlagCloner	(1 << 6)	Create spatial cloner.
FlagRaster	(1 << 7)	Create raster resources.
FlagMeshlet	(1 << 8)	Create meshlet resources.
FlagTracing	(1 << 9)	Create tracing resources.
FlagAuxiliaryBuffer	(1 << 10)	Create auxilairy buffer resources.
FlagMotionBuffer	(1 << 11)	Create motion buffer resources.
FlagBufferSparse	(1 << 12)	Create sparse buffer resources.
FlagBufferInterop	(1 << 13)	Create interop buffer resources.
FlagTextureSparse	(1 << 14)	Create sparse texture resources.
FlagTextureInterop	(1 << 15)	Create interop texture resources.
FlagDecodeCompute	(1 << 16)	Compute texture decoding.
FlagEncodeCompute	(1 << 17)	Compute texture encoding.
FlagEncodeFast	(1 << 18)	Fast CPU texture encoding.
FlagEncodeBest	(1 << 19)	Best CPU texture encoding.
FlagFilterMip	(1 << 20)	Mip mipmap filter, otherwise box filter is used.
FlagFilterSinc	(1 << 21)	Sinc minification filter, otherwise box filter is used.
FlagFilterCubic	(1 << 22)	Cubic magnification filter, otherwise linear filter is used.
DefaultFlags	(FlagQuery | FlagDecodeCompute | FlagEncodeCompute | FlagFilterMip | FlagFilterSinc)
NumFlags	23