Lysa  0.0
Lysa 3D Engine
Resources Management

Lysa starts its global image, mesh and material pools at configurable capacities. Their CPU slots and device buffers grow geometrically on demand and scene buffers also grow per frame. Samplers, shadow-map tables and vector-renderer pools retain explicit fixed limits. Growth remains subject to device limits, GPU memory availability and the image descriptor budget.

Table of contents


Global Resource Pools

Global resource pools are shared across all scenes and render targets. Their initial capacities are configured through lysa::ResourcesCapacity, which is embedded in lysa::ContextConfiguration:

.images = 500,
.samplers = 20,
.material = 100,
.meshes = 1000,
.surfaces = 5000,
.vertices = 5000000,
.indices = 50000000,
},
};
Field Default Description
images 128 Initial image slot and allocated descriptor table capacity. Images themselves have independent GPU allocations.
maxImages 16384 Maximum sampled image table size declared in the stable layout, clamped to the device limit. Does not allocate textures or the whole descriptor table at startup.
samplers 20 Maximum number of GPU image samplers that can be created. Each unique combination of filtering and address-mode settings consumes one entry.
material 64 Initial slots and GPU data capacity for standard and shader materials together.
shaderMaterialParameters 512 Initial float4 parameter buffer capacity shared by shader materials.
meshes 64 Initial mesh slot and GPU metadata capacity.
surfaces 256 Initial capacity for mesh surfaces across all meshes. A surface maps to one draw call and carries one material assignment.
vertices 65536 Initial capacity for vertices across all surfaces, stored in a single shared GPU vertex buffer.
indices 196608 Initial capacity for indices across all surfaces, stored in a single shared GPU index buffer.

Override each field when a known asset workload needs more space at startup.

Global GPU arrays reserve each upload batch before recording copies. When a contiguous allocation cannot fit, a larger buffer is created and the old content is copied at identical offsets on the main graphics queue.


Explicit Memory Release

Call lysa::Lysa::releaseUnusedMemory on the main thread between frames, after stopping concurrent resource loading and mutation:

const auto releasedBytes = lysa.releaseUnusedMemory();

Per-Scene Initial Capacities

Each lysa::Scene owns one GPU resource slot per frame in flight:

auto scene = std::make_shared<lysa::Scene>(lysa::SceneConfiguration {
.initialLights = 16,
.initialMeshInstances = 128,
.initialSurfaceInstances = 512,
.initialSurfaceInstancesPerPipeline = 256,
});
Field Default Description
preCreatePipelines true Prepare pipeline data when materials are created.
asyncObjectUpdatesPerFrame 50 Maximum asynchronous instance additions processed per scene update.
initialLights 16 Initial capacity of the dynamic light storage buffer. Only visible lights are uploaded and counted.
initialMeshInstances 128 Initial persistent mesh-instance array capacity per frame.
initialSurfaceInstances 512 Initial persistent surface-instance array capacity shared by all pipelines in one frame.
initialSurfaceInstancesPerPipeline 256 Initial active-group and surface-command capacities per pipeline.

These capacities grow geometrically while preserving persistent allocation offsets.

Unlike global mesh buffers, scene allocations are multiplied by the number of frames in flight. Device memory, descriptor budgets and GPU index/address limits still bound growth. ContextConfiguration::maxShadowMapsPerScene remains an explicit limit independent of the number of lights.


Other Engine-Level Limits

The following fields in lysa::ContextConfiguration affect global runtime behaviour:

Field Default Description
framesInFlight 2 Number of frames rendered concurrently. Affects the size of all per-frame GPU ring-buffers. Values above 3 are unlikely to improve throughput and increase latency and memory usage.
maxShadowMapsPerScene 20 Maximum number of shadow maps allocated per scene. One map is consumed per shadow-casting light; cascaded shadow maps consume one map per cascade.
eventsReserveCapacity 100 Initial capacity of the event queue. The queue grows dynamically, so this is only a hint to avoid early reallocations.
commandsReserveCapacity 1000 Initial capacity of the deferred command buffer. Like the event queue, it grows on demand.

Sizing Guidelines

Choose initial capacities close to the expected startup workload to avoid unnecessary growth during loading. Count distinct meshes and their geometry for global pools and count mesh instances and their surface instances for scene pools. Materials and textures shared by instances consume global slots only once.

Small initial capacities reduce startup allocation, while growth keeps larger scenes valid. Budget scene memory for every frame in flight and allow temporary room for old buffers retained by commands currenly running.