General Resource Management

Automatic resource manager for D3D resources.

Glossary:

level - feature of texture size, computed as log2(max(tex.dimensions)) = log2(max(tex.w, tex.h, tex.d)):
1. level=1 means smallest possing size (2x2x2) and is commonly used to denote smallest quality;
2. level=15 means maximum possible size (up to 32767x32768, but current GPUs don’t handle such res);
3. level=2..15 means some non-stub quality. Variables for holding level usually have suffix Lev or _lev
QL - quality level (or TQL - texture quality level), do not confuse it with ‘level’. Some predefined quality preset of texture (stub, thumbnail, base, high, ultrahigh, etc.) Enumerated later with TexQL enum (TQL_*). Variables for holding quality level usually have suffix QL or _ql.
LFU - last frame used, ordinary rendered frame counter (generally from game start) where texture was referenced last time
levDesc - levels descriptor that maps QL to real levels (e.g. TQL_thumb -> level=6, TQL_base -> level=9)

Helper wrappers

See iterate_all_managed_d3dres(). Use as follows:

for (D3DRESID id = first_managed_d3dres(); id != BAD_D3DRESID; id = next_managed_d3dres(id)) 

Get the first managed resource ID for iteration

param min_rc:: Minimum reference count filter

return:: First managed resource ID with refCount >= min_rc

inline D3DRESID first_managed_d3dres(int min_rc = 0)

inline D3DRESID next_managed_d3dres(D3DRESID prev_id, int min_rc = 0)

Get the next managed resource ID for iteration.

Parameters:

prev_id – ID of the previous resource
min_rc – Minimum reference count filter

Returns:

Next managed resource ID after prev_id with refCount >= min_rc

Enums

enum TexQL

Quality levels for textures (QL)

Values:

enumerator TQL_stub: stub (shared 1x1 placeholder)

enumerator TQL_thumb: thumbnail quality (upto 64x64, total mem size <= 4K)

enumerator TQL_base: base quality (low split)

enumerator TQL_high: full quality (HQ)

enumerator TQL_uhq: ultra high quality

enumerator TQL__COUNT: enum item count

enumerator TQL__FIRST

enumerator TQL__LAST

Functions

D3DRESID register_managed_res(const char *name, D3dResource *res)

Registers external D3D resource with the specified name as managed and returns the D3DRESID for it.

Specified resource becomes owned by the manager, no factory is assigned to it. RefCount is set to 1 and when it eventually reaches 0, the resource is automatically destroyed and the name is evicted. Use release_managed_res() or release_managed_res_verified() to del ref and finally destroy.

Warning

Resource name is case-insensitive and must be unique.

Parameters:

name – the name to register the resource under
res – the resource to register

Returns:

the D3DRESID for the registered resource

bool is_managed_res_factory_set(D3DRESID id)

Checks whether creation/release factory is set for D3DRESID.

E.g. for an ID that was acquired from register_managed_res(), it will return false.

Parameters:: id – the D3DRESID to check
Returns:: true if a factory was specified for the D3DRESID

D3dResource *acquire_managed_res(D3DRESID id)

Acquires resource object and increments resource reference count.

If resource was not referenced yet, it is created. If it is unavailable (bad ID), nullptr is returned. Logically paired with release_managed_res().

Note

When factory fails to create texture, missing texture handling may be applied.

Parameters:: id – the managed ID to acquire
Returns:: the acquired resource object or nullptr if the ID is invalid

void release_managed_res(D3DRESID id)

Releases resource object and decrements resource reference count.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res()

Parameters:: id – the managed ID to release

void release_managed_res_verified(D3DRESID &id, D3dResource *check_res)

Releases resource object and decrements resource reference count, but additionally checks that the managed resource is the same as check_res.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res() On resource destruction (when name is unregistered) id is set to BAD_D3DRESID

Parameters:

id – the managed ID to release
check_res – the resource to check against

BaseTexture *acquire_managed_tex(D3DRESID id)

Acquires resource object and increments resource reference count.

If resource was not referenced yet, it is created. If it is unavailable (bad ID), nullptr is returned. Logically paired with release_managed_res().

Note

When factory fails to create texture, missing texture handling may be applied.

Parameters:: id – the managed ID to acquire
Returns:: the acquired resource object or nullptr if the ID is invalid

static inline void release_managed_tex(D3DRESID id)

Releases resource object and decrements resource reference count.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res()

Parameters:: id – the managed ID to release

template<class T> static inline void release_managed_tex_verified(D3DRESID &id, T &tex)

Releases resource object and decrements resource reference count, but additionally checks that the managed resource is the same as check_res.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res() On resource destruction (when name is unregistered) id is set to BAD_D3DRESID

Parameters:

id – the managed ID to release
check_res – the resource to check against

Sbuffer *acquire_managed_buf(D3DRESID id)

Acquires resource object and increments resource reference count.

If resource was not referenced yet, it is created. If it is unavailable (bad ID), nullptr is returned. Logically paired with release_managed_res().

Note

When factory fails to create texture, missing texture handling may be applied.

Parameters:: id – the managed ID to acquire
Returns:: the acquired resource object or nullptr if the ID is invalid

static inline void release_managed_buf(D3DRESID id)

Releases resource object and decrements resource reference count.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res()

Parameters:: id – the managed ID to release

template<class T> static inline void release_managed_buf_verified(D3DRESID &id, T &buf)

Releases resource object and decrements resource reference count, but additionally checks that the managed resource is the same as check_res.

When reference count reaches 0, resource may be released. Logically paired with acquire_managed_res() On resource destruction (when name is unregistered) id is set to BAD_D3DRESID

Parameters:

id – the managed ID to release
check_res – the resource to check against

const char *get_managed_res_name(D3DRESID id)

Gets the name for a managed resource by ID, or nullptr if ID is invalid.

Parameters:: id – the D3DRESID to get the name for
Returns:: the name of the managed resource with ID id or nullptr

D3DRESID get_managed_res_id(const char *res_name)

Gets managed resource ID by its name, or BAD_D3DRESID if name is invalid.

Parameters:: res_name – the name of the resource to get the ID for
Returns:: the managed resource ID that corresponds to res_name or BAD_D3DRESID if the name is invalid

inline int get_managed_res_refcount(D3DRESID id)

Gets the reference count for a managed resource by ID.

Parameters:: id – the ID to get the reference count for
Returns:: the reference count for the D3DRESID resource or a negative value if the resource is missing

inline unsigned get_managed_res_lfu(D3DRESID id)

Gets the last-frame-used (LFU) counter for a managed ID.

Parameters:: id – the ID to get the LFU counter for
Returns:: the last-frame-used counter for the D3DRESID resource or 0 if the resource is missing/unregistered

inline TexQL get_managed_res_cur_tql(D3DRESID id)

Gets the current quality level (TQL_*) for a managed ID.

Parameters:: id – the ID to get the quality level for
Returns:: the current quality level for the D3DRESID resource or TQL_stub if the resource is missing/unregistered

inline TexQL get_managed_res_max_tql(D3DRESID id)

Gets the maximum available quality level (TQL_*) for a managed ID.

Parameters:: id – the D3DRESID to get the quality level for
Returns:: the current quality level for the D3DRESID resource or TQL_stub if the resource is missing/unregistered

inline unsigned get_managed_res_maxreq_lev(D3DRESID id)

Gets the maximum requested level for a managed ID, i.e. log2(tex.dimension). Do not confuse it with QL!

Parameters:: id – the D3DRESID to get the loaded level for
Returns:: the current loaded level for id or 0 if the resource is missing/unregistered

inline unsigned get_managed_res_loaded_lev(D3DRESID id)

Gets the current loaded level for a managed ID, i.e. log2(tex.dimension). Do not confuse it with QL!

Parameters:: id – the D3DRESID to get the loaded level for
Returns:: the current loaded level for id or 0 if the resource is missing/unregistered

void enable_res_mgr_mt(bool enable, int max_res_entry_count)

Enables or disables multithreading support for resource manager and preallocates internal structures to handle upto max_res_entry_count resource entries without reallocations.

enable_res_mgr_mt(false, -1) will disable multithreading support and shrink entries array to used size

Parameters:

enable – whether to enable multithreading support
max_res_entry_count – the maximum number of resource entries to preallocate or -1 to shrink to fit

D3DRESID iterate_all_managed_d3dres(D3DRESID after_rid, int min_ref_count)

Utility for iterating all managed resources.

Managed resources form a linked list, so for an arbitrary ID, this function returns the “next” ID in the list. Hence one is supposed to call this function in a loop until it returns BAD_D3DRESID.

Parameters:

after_rid – ID of the texture to get the next texture for. Use BAD_D3DRESID to start iteration.
min_ref_count – Minimum reference count filter

Returns:

Some ID that follows after_rid and has refCount >= min_ref_count OR BAD_RESID if the iteration is done.