Classes
struct	budget_state

struct	config
	Configuration for a single eviction pass. More...

struct	stats
	Cumulative and last-pass statistics reported by the eviction system. More...

Typedefs
using	backing_buffer = std::shared_ptr<std::vector<std::uint8_t>>

Enumerations
enum class	init_status : std::uint8_t { ok , unnecessary , unsupported , failed }
	Result of init. Determines whether the system tracks resources at all. More...

enum class	strategy : std::uint8_t { lru , lfu , largest_first , age_ttl }
	Selection policy used by a sweep to choose eviction victims. More...

enum class	reclaim_result : std::uint8_t { headroom , reclaimed , insufficient }

enum class	reclaim_kind : std::uint8_t { evictable , immediate }
	Controls whether reclaim_for pumps the GPU command buffer after evicting. More...

Functions
auto	init (const config &cfg) -> init_status

auto	is_supported () -> bool

void	shutdown ()

auto	evict (const config &cfg) -> stats

auto	evict () -> stats
	Run a single eviction pass using the config supplied to init.

auto	evict_bytes (std::uint64_t free_bytes, strategy strat, std::uint32_t min_age_frames, std::uint32_t max_evictions) -> stats

auto	evict_all () -> stats

auto	would_allocation_fit (std::uint64_t bytes) -> bool

auto	reclaim_for (std::uint64_t bytes, reclaim_kind kind) -> reclaim_result

auto	peek_queued_bytes () -> std::uint64_t

auto	peek_pending_release_bytes () -> std::uint64_t

auto	peek_external_queued_bytes () -> std::uint64_t

void	note_pending_allocation (std::uint64_t bytes)

void	clear_queued_allocations ()

auto	debug_consume_memory (std::uint64_t bytes) -> std::uint64_t

auto	debug_simulate_budget (std::uint64_t target_free_bytes) -> std::uint64_t

void	debug_release_memory ()

auto	debug_consumed_bytes () -> std::uint64_t
	Total bytes currently reserved by debug_consume_memory.

auto	restore_all () -> stats

void	set_budget (const budget_state &budget, std::uint64_t used_bytes)

auto	current_budget () -> budget_state

auto	get_stats () -> stats
	Snapshot the current statistics.

void	set_frame (std::uint64_t frame)
	Set the global frame counter (call once per presented frame).

void	advance_frame ()
	Advance the global frame counter by one.

void	register_resource (ievictable *resource)
	Begin tracking a resource (assumed resident). Called from handle_impl::make_evictable.

void	register_evicted_resource (ievictable *resource)

void	unregister_resource (ievictable *resource)
	Stop tracking a resource. Called from handle_impl's destructor.

void	restore_resource (ievictable *resource)

auto	make_backing (const void *data, std::uint32_t size) -> backing_buffer

void	release_backing_ref (void , void user_data)

auto	make_backing_ref (const backing_buffer &backing) -> const memory_view *

constexpr auto	to_string (reclaim_result r) -> const char *
	Human-readable name for reclaim_result (for diagnostics / logging).

Detailed Description

GPU resource eviction / paging service.

The registry itself is a static singleton defined entirely in eviction.cpp; only the free functions below are exposed. Resources opt into management through gfx::handle_impl by retaining a CPU-side backing, after which they are tracked here and may be evicted (GPU memory released) and restored on demand.

Typedef Documentation

◆ backing_buffer

using gfx::eviction::backing_buffer = std::shared_ptr<std::vector<std::uint8_t>>

Definition at line 18 of file eviction.h.

Enumeration Type Documentation

◆ init_status

enum class gfx::eviction::init_status : std::uint8_t

strong

Result of init. Determines whether the system tracks resources at all.

Enumerator
ok	Initialized and active.
unnecessary	Eviction is not needed for this backend (driver manages residency).
unsupported	Backend does not report a GPU memory budget; eviction is disabled.
failed	Initialization failed (graphics not ready).

Definition at line 41 of file eviction.h.

◆ reclaim_kind

enum class gfx::eviction::reclaim_kind : std::uint8_t

strong

Controls whether reclaim_for pumps the GPU command buffer after evicting.

Enumerator
evictable	CPU-backed resources (file/memory textures). Check-only via would_allocation_fit; never runs an eviction sweep from the load path.
immediate	Non-evictable, synchronously allocated GPU resources (render targets). Evict and flush so destroyed handles release VRAM before the imminent create on the API thread.

Definition at line 82 of file eviction.h.

◆ reclaim_result

enum class gfx::eviction::reclaim_result : std::uint8_t

strong

Outcome of a reclaim_for call. Callers may log insufficient as a warning but should still proceed with the allocation: a bgfx-side OOM is non-fatal (the handle returns invalid and the resource is just absent) and we prefer the engine to surface its own message rather than fail silently inside the eviction layer.

Enumerator
headroom	Already enough headroom; nothing was done.
reclaimed	Eviction (and possibly a command-buffer pump) freed enough room.
insufficient	Eviction could not free enough room; the allocation may exhaust device memory.

Definition at line 62 of file eviction.h.

◆ strategy

enum class gfx::eviction::strategy : std::uint8_t

strong

Selection policy used by a sweep to choose eviction victims.

Enumerator
lru	Least recently used first (smallest last-use frame).
lfu	Least frequently used first (smallest use count).
largest_first	Largest resources first (fastest headroom recovery).
age_ttl	Every resource idle for longer than config::max_idle_frames.

Definition at line 50 of file eviction.h.

Function Documentation

◆ advance_frame()

void gfx::eviction::advance_frame ( )

Advance the global frame counter by one.

Definition at line 966 of file eviction.cpp.

◆ clear_queued_allocations()

void gfx::eviction::clear_queued_allocations ( )

Clear the queued-allocation counter after bgfx::frame or bgfx::flush has processed the command stream. Called from the graphics layer; user code should not need this.

Definition at line 811 of file eviction.cpp.

◆ current_budget()

auto gfx::eviction::current_budget ( ) -> budget_state

Snapshot the most recently published budget_state. Returns an all-zero struct when no budget has been set yet (start-up frame, or eviction is unsupported / unnecessary).

Definition at line 948 of file eviction.cpp.

◆ debug_consume_memory()

auto gfx::eviction::debug_consume_memory ( std::uint64_t bytes ) -> std::uint64_t

Reserve raw GPU memory to artificially raise device occupancy so the eviction and near-the-limit allocation paths can be exercised on GPUs that have plenty of memory. The reserved memory is plain, non-evictable GPU storage held outside the registry (uninitialized RGBA8 textures), so it genuinely pins VRAM and forces the system to evict real resources. Calls are additive: bytes is added on top of whatever is already reserved (rounded up to whole chunks). Stops early if an allocation fails. Returns the total reserved bytes after the call. Must run on the graphics API thread.

Definition at line 852 of file eviction.cpp.

◆ debug_consumed_bytes()

auto gfx::eviction::debug_consumed_bytes ( ) -> std::uint64_t

Total bytes currently reserved by debug_consume_memory.

Definition at line 918 of file eviction.cpp.

◆ debug_release_memory()

void gfx::eviction::debug_release_memory ( )

Release all memory reserved by debug_consume_memory and reclaim its VRAM immediately. Must run on the graphics API thread.

Definition at line 903 of file eviction.cpp.

◆ debug_simulate_budget()

auto gfx::eviction::debug_simulate_budget ( std::uint64_t target_free_bytes ) -> std::uint64_t

Reserve memory so that the device behaves as if it only had target_free_bytes of GPU memory available, i.e. it reserves (real budget - current usage - target_free_bytes) of VRAM in one call. This is an absolute target: any existing reservation is released first so repeated calls with different targets are stable. Genuinely allocates VRAM (so the engine hits real out-of-memory behavior at the simulated limit). No-op if the backend reports no budget or the target already fits. Returns the total reserved bytes after the call. Must run on the graphics API thread.

Definition at line 875 of file eviction.cpp.

◆ evict() [1/2]

auto gfx::eviction::evict ( ) -> stats

Run a single eviction pass using the config supplied to init.

Definition at line 669 of file eviction.cpp.

◆ evict() [2/2]

auto gfx::eviction::evict ( const config & cfg ) -> stats

Run a single eviction pass with an explicit config. Must be called on the graphics API thread. Returns a snapshot of statistics taken after the pass.

Definition at line 664 of file eviction.cpp.

◆ evict_all()

auto gfx::eviction::evict_all ( ) -> stats

Evict every evictable resource regardless of budget or age. Intended for testing/diagnostics. Must run on the graphics API thread.

Definition at line 680 of file eviction.cpp.

◆ evict_bytes()

auto gfx::eviction::evict_bytes	(	std::uint64_t	free_bytes,
		strategy	strat = strategy::lru,
		std::uint32_t	min_age_frames = 0,
		std::uint32_t	max_evictions = 0 ) -> stats

Evict resources (in strat order) until at least free_bytes have been reclaimed, the candidate pool is exhausted, or max_evictions is reached. This is the byte-pressure driven entry point used when a budget is computed externally (e.g. from the GPU memory stats). min_age_frames protects recently used resources (0 disables the protection). Must run on the graphics API thread.

Definition at line 674 of file eviction.cpp.

◆ get_stats()

auto gfx::eviction::get_stats ( ) -> stats

Snapshot the current statistics.

Definition at line 953 of file eviction.cpp.

◆ init()

auto gfx::eviction::init ( const config & cfg = {} ) -> init_status

Initialize the system and set the default config used by the argument-less evict. Must be called after the graphics backend has presented at least one frame so the GPU memory budget is available. When the backend does not report a budget the system stays disabled and every entry point becomes a no-op (resources are neither tracked nor CPU-backed).

Definition at line 645 of file eviction.cpp.

◆ is_supported()

auto gfx::eviction::is_supported ( ) -> bool

Whether eviction is supported and active on the current backend. Cheap; safe to call from the resource creation path to decide whether to retain a CPU backing.

Definition at line 650 of file eviction.cpp.

◆ make_backing()

auto gfx::eviction::make_backing	(	const void *	data,
		std::uint32_t	size ) -> backing_buffer

inline

Definition at line 20 of file eviction.h.

◆ make_backing_ref()

auto gfx::eviction::make_backing_ref ( const backing_buffer & backing ) -> const memory_view*

inline

Definition at line 31 of file eviction.h.

◆ note_pending_allocation()

void gfx::eviction::note_pending_allocation ( std::uint64_t bytes )

Record a newly queued GPU allocation. Used for allocations that are not registered as evictable resources (e.g. render targets / compute write textures). Complements the bytes argument passed to reclaim_for for the same create: reclaim counts the imminent allocation once; this keeps it visible in peek_queued_bytes for later same-frame creates until clear_queued_allocations.

Definition at line 806 of file eviction.cpp.

◆ peek_external_queued_bytes()

auto gfx::eviction::peek_external_queued_bytes ( ) -> std::uint64_t

In-flight bytes from non-evictable creates (render targets, etc.) recorded via note_pending_allocation. Used by the manual-budget driver path.

Definition at line 801 of file eviction.cpp.

◆ peek_pending_release_bytes()

auto gfx::eviction::peek_pending_release_bytes ( ) -> std::uint64_t

GPU bytes from destroys/evictions queued in bgfx but not yet reflected in gpuMemoryUsed. Credited against occupancy projections until clear_queued_allocations runs after a pump.

Definition at line 796 of file eviction.cpp.

◆ peek_queued_bytes()

auto gfx::eviction::peek_queued_bytes ( ) -> std::uint64_t

Peek the GPU bytes queued since the last bgfx::frame/flush without consuming them. The driver adds this to the backend's gpuMemoryUsed (which lags a frame or more) to react in the same frame, and reclaim_for uses it to project occupancy. Lock-free; cleared by clear_queued_allocations.

Definition at line 791 of file eviction.cpp.

◆ reclaim_for()

auto gfx::eviction::reclaim_for	(	std::uint64_t	bytes,
		reclaim_kind	kind = reclaim_kind::immediate ) -> reclaim_result

Synchronously guarantee headroom for an imminent GPU allocation of bytes (reclaim_kind::immediate). Reads the active budget_state and live backend stats:

If projected occupancy stays under the soft budget, returns reclaim_result::headroom.
Otherwise evicts resident victims (using config::strat and config::min_age_frames from init) down toward budget_state::target_bytes, then flushes so VRAM is free before create. reclaim_kind::evictable is projection-only; prefer would_allocation_fit at load sites. Restore-on-bind must not call this; frame_begin eviction already shaped the pool. Must run on the graphics API thread. A no-op when eviction is unsupported or no budget is set.

Definition at line 737 of file eviction.cpp.

◆ register_evicted_resource()

void gfx::eviction::register_evicted_resource ( ievictable * resource )

Begin tracking a resource with no live GPU handle (deferred create / allocation skipped). Counts toward stats::evicted_bytes; restore_resource recreates it on access.

Definition at line 977 of file eviction.cpp.

◆ register_resource()

void gfx::eviction::register_resource ( ievictable * resource )

Begin tracking a resource (assumed resident). Called from handle_impl::make_evictable.

Definition at line 972 of file eviction.cpp.

◆ release_backing_ref()

void gfx::eviction::release_backing_ref	(	void *	,
		void *	user_data )

inline

Definition at line 26 of file eviction.h.

◆ restore_all()

auto gfx::eviction::restore_all ( ) -> stats

Restore every currently evicted resource immediately. Calls reclaim_for once up front for the full evicted byte count so a large pending pool cannot push the device past the hard limit. The actual restore loop runs under the registry mutex to keep the evicted set stable. Useful for tests and for turning paging off. Must run on the graphics API thread.

Definition at line 923 of file eviction.cpp.

◆ restore_resource()

void gfx::eviction::restore_resource ( ievictable * resource )

Restore a resource immediately if it is evicted. Called from handle_impl::native_handle on access. Must run on the graphics API thread. No-op if the resource is already resident.

Definition at line 987 of file eviction.cpp.

◆ set_budget()

void gfx::eviction::set_budget	(	const budget_state &	budget,
		std::uint64_t	used_bytes )

Publish the active memory budget for this frame so reclaim_for and tooling see the same numbers. Pure bookkeeping — it does not trigger eviction itself. used_bytes is the metric the driver compares against the budget (e.g. gpuMemoryUsed + queued for auto budget, or evictable resident bytes for a manual budget); it is recorded only for diagnostics.

Definition at line 943 of file eviction.cpp.

◆ set_frame()

void gfx::eviction::set_frame ( std::uint64_t frame )

Set the global frame counter (call once per presented frame).

Definition at line 958 of file eviction.cpp.

◆ shutdown()

void gfx::eviction::shutdown ( )

Stop tracking and release internal bookkeeping. Resources are not destroyed (they own themselves); any evicted resource restores itself on next use.

Definition at line 655 of file eviction.cpp.

◆ to_string()

auto gfx::eviction::to_string ( reclaim_result r ) -> const char*

constexpr

Human-readable name for reclaim_result (for diagnostics / logging).

Definition at line 70 of file eviction.h.

◆ unregister_resource()

void gfx::eviction::unregister_resource ( ievictable * resource )

Stop tracking a resource. Called from handle_impl's destructor.

Definition at line 982 of file eviction.cpp.

◆ would_allocation_fit()

auto gfx::eviction::would_allocation_fit ( std::uint64_t bytes ) -> bool

Project whether bytes fit under the hard limit without running an eviction sweep. Used by speculative CPU-backed texture loads; defers the create when false (CPU backing retained).

Definition at line 723 of file eviction.cpp.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ backing_buffer

Enumeration Type Documentation

◆ init_status

◆ reclaim_kind

◆ reclaim_result

◆ strategy

Function Documentation

◆ advance_frame()

◆ clear_queued_allocations()

◆ current_budget()

◆ debug_consume_memory()

◆ debug_consumed_bytes()

◆ debug_release_memory()

◆ debug_simulate_budget()

◆ evict() [1/2]

◆ evict() [2/2]

◆ evict_all()

◆ evict_bytes()

◆ get_stats()

◆ init()

◆ is_supported()

◆ make_backing()

◆ make_backing_ref()

◆ note_pending_allocation()

◆ peek_external_queued_bytes()

◆ peek_pending_release_bytes()

◆ peek_queued_bytes()

◆ reclaim_for()

◆ register_evicted_resource()

◆ register_resource()

◆ release_backing_ref()

◆ restore_all()

◆ restore_resource()

◆ set_budget()

◆ set_frame()

◆ shutdown()

◆ to_string()

◆ unregister_resource()

◆ would_allocation_fit()