Texture Management

Helper wrappers

See iterate_all_managed_textures(). Use as follows:

for (TEXTUREID id = first_managed_texture(); id != BAD_TEXTUREID; id = next_managed_texture(id)) 

Get the first managed texture ID for iteration

param min_rc:: Minimum reference count filter

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

inline TEXTUREID first_managed_texture(int min_rc = 0)

inline TEXTUREID next_managed_texture(TEXTUREID prev_id, int min_rc = 0)

Get the next managed texture ID for iteration.

Parameters:

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

Returns:

Next managed texture ID after prev_id with refCount >= min_rc

Functions

D3DRESID register_managed_tex(const char *name, BaseTexture *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

static inline bool is_managed_tex_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

static inline const char *get_managed_texture_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

static inline D3DRESID get_managed_texture_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

static inline int get_managed_texture_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

static inline void enable_tex_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

TEXTUREID add_managed_texture(const char *name, TextureFactory *factory = nullptr)

Adds entry for managed texture name and returns TEXTUREID for it.

When entry for ‘name’ already exists, it just returns TEXTUREID. For new entry ‘factory’ is set as creator, for existing entry ‘factory’ must be nullptr.

Warning

Texture name is case-insensitive and must be unique.

Parameters:

name – Name that uniquely identifies the texture
factory – Custom texture creation mechanism, must be nullptr for existing textures

Returns:

Managed ID of the texture

TEXTUREID add_managed_array_texture(const char *name, dag::ConstSpan<const char*> tex_slice_nm)

Adds or updates entry for managed array texture name, stores creation properties and returns TEXTUREID for it.

Array texture will be composed of slices with texture names tex_slice_nm.

Warning

Textures in slices must have the same format and size, and furthermore, some restrictions of DDSx flags apply.

Parameters:

name – Name that uniquely identifies the new array texture
tex_slice_nm – Array of texture names to use as slices

Returns:

Managed ID of the texture

TEXTUREID update_managed_array_texture(const char *name, dag::ConstSpan<const char*> tex_slice_nm)

Updates an existing array texture entry with new slices.

Note

Simply calls add_managed_texture() under the hood, this function exists purely for readability purposes.

Warning

The number of slices must match the original array texture.

Parameters:

name – Name of the array texture to update
tex_slice_nm – Array of new texture names to use as slices

Returns:

Managed ID of the array texture that was updated

unsigned reload_managed_array_textures_for_changed_slice(const char *slice_tex_name)

Checks all registered array textures and reloads those referencing specified slice.

Parameters:: slice_tex_name – Name of changed texture that can be used as slice in some array texture
Returns:: Number of reloaded array textures (or 0 if no array texture reference that slice)

bool evict_managed_tex_id(TEXTUREID &id)

Schedules removal of the managed entry for the specified id and sets id to BAD_TEXTUREID (unconditionally, even if the operation fails or is deferred).

When refCount = 0, removal is performed immediately, otherwise it is deferred. Can be used to remove entries created with register_managed_tex(), add_managed_texture(), add_managed_array_texture()

Parameters:: id – ID of the texture to remove
Returns:: true if the texture was removed immediately, false otherwise, including if the operation was invalid.

bool check_managed_texture_loaded(TEXTUREID id, bool fq_loaded = false)

Checks whether contents of managed texture was loaded.

Parameters:

id – ID of the texture to check
fq_loaded – true to check for full quality, false for any quality

Returns:

true if the texture is loaded, false otherwise

bool check_all_managed_textures_loaded(dag::ConstSpan<TEXTUREID> id, bool fq_loaded = false, bool ignore_unref_tex = true)

Checks whether contents of all managed textures in list was loaded, analogous to calling check_managed_texture_loaded() multiple times.

Note

Skips checks for textures with refcount=0 by default.

Parameters:

id – List of texture IDs to check.
fq_loaded – true to check for full quality, false for any quality
ignore_unref_tex – true to skip textures with refcount=0

Returns:

true if all textures (excluding those with refcount=0 if ignore_unref_tex is true) are loaded, false otherwise.

bool change_managed_texture(TEXTUREID id, BaseTexture *new_texture, TextureFactory *factory = NULL)

Replaces the texture for managed id id.

Parameters:

id – ID of the texture to replace
new_texture – New driver texture to use for this id
factory – Custom texture creation mechanism

Returns:

true if the texture was replaced successfully, false otherwise

void discard_unused_managed_texture(TEXTUREID id)

Discards unused texture: unloads texture when refCount=0, does nothing otherwise.

Parameters:: id – ID of the texture to discard

void discard_unused_managed_textures(): Iterate all managed textures and unload those with refCount=0.

inline void mark_managed_tex_lfu(TEXTUREID id, unsigned req_lev = 15)

Set current frame as ‘last frame used’ for texture.

Parameters:

id – ID of the texture to mark
req_lev – Quality level that was used on this frame

bool prefetch_managed_texture(TEXTUREID id)

Request texture content load.

Parameters:: id – ID of the texture to load
Returns:: true when texture already loaded, false otherwise

bool prefetch_managed_textures(dag::ConstSpan<TEXTUREID> id)

Requests texture content load for a list of textures, the same as calling prefetch_managed_texture() multiple times.

Parameters:: id – List of texture IDs to load
Returns:: true when all textures are already loaded

bool prefetch_managed_textures_by_textag(int textag)

Requests texture content load for list of textures by TEXTAG.

Parameters:: textag – The tag to load textures for
Returns:: true when all textures with the tag are already loaded

void mark_managed_textures_important(dag::ConstSpan<TEXTUREID> id, unsigned add_importance = 1, int min_lev_for_dyn_decrease = 16)

Marks list of textures as important (to force loading content upto requested quality level as soon as possible)

Parameters:

id – List of texture IDs to mark
add_importance – Additional importance to add to the textures
min_lev_for_dyn_decrease – important textures with more levels min can be downgraded 1 mip when dyn decrease used

void reset_managed_textures_streaming_state(): Resets streaming state of textures so that they can be reloaded respecting the global tex quality settings changes.

void set_default_tex_factory(TextureFactory *tf): Sets the default texture factory to use for managed textures.

TextureFactory *get_default_tex_factory(): Gets the default texture factory.

TextureFactory *get_symbolic_tex_factory(): Gets the symbolic texture factory which always produces nulls for texture creation.

TextureFactory *get_stub_tex_factory(): Gets the stub texture factory which always produces stub 1x1 textures.

void init_managed_textures_streaming_support(int reload_jobmgr_id = -2)

Init data and callbacks to support streaming.

Settings are taken from dgs_get_settings()->getBlockByName(“texStreaming”).

Note

reload_jobmgr_id=-2 means auto creation of jobmanager, reload_jobmgr_id=-1 means no jobmanager

Parameters:: rload_jobmgr_id – Either -1 or -2, controls whether to create a job manager for texture streaming

bool is_managed_textures_streaming_active()

Checks whether texture streaming is inited and active.

Returns:: true if texture streaming is active, false otherwise

bool is_managed_textures_streaming_load_on_demand()

Checks whether texture streaming loads textures only when used.

Returns:: true if texture streaming is load-on-demand, false otherwise

bool is_managed_texture_incomplete(TEXTUREID id)

Checks whether the specified texture is split BQ/HQ with missing HQ part.

Parameters:: id – ID of the texture to check
Returns:: true if the texture is missing HQ part, false otherwise

void load_anisotropy_from_settings(): Re-loads anisotropy config from settings.

void add_anisotropy_exception(TEXTUREID id)

Marks that a texture’s anisotropy should not be changed automatically.

Parameters:: id – ID of the texture to mark

void reset_anisotropy(const char *tex_name_filter = nullptr)

Resets anisotropy for all textures whose name contains tex_name_filter as a substring.

Parameters:: tex_name_filter – Substring filter to match texture names

inline bool prefetch_and_check_managed_texture_loaded(TEXTUREID id, bool fq_loaded = false)

Attempts to load the texture for usage on the current frame and simply checks for immediate success.

Parameters:

id – ID of the texture to load and check
fq_loaded – true to check for full quality, false for any quality

Returns:

true if the texture is loaded, false otherwise

bool prefetch_and_check_managed_textures_loaded(dag::ConstSpan<TEXTUREID> tex_list, bool fq_loaded = false)

Attempts to load multiple textures for usage on the current frame and check for immediate success.

Parameters:

tex_list – List of texture IDs to load and check
fq_loaded – true to check for full quality, false for any quality

Returns:

true if all textures are loaded, false otherwise

void prefetch_and_wait_managed_textures_loaded(dag::ConstSpan<TEXTUREID> tex_list, bool fq_loaded = false)

Synchronously loads a list of textures, blocking the current thread until all textures are loaded.

Parameters:

tex_list – List of texture IDs to load
fq_loaded – true to wait for full quality, false for any quality

TEXTUREID iterate_all_managed_textures(TEXTUREID after_tid, int min_ref_count)

Utility for iterating all managed textures.

Managed textures 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_TEXTUREID.

Parameters:

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

Returns:

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

TEXTUREID get_max_managed_texture_id()

Access to the highest valid texture ID for storing properties of managed textures in arrays.

Returns:: Highest valid texture ID

inline bool is_managed_texture_id_valid(TEXTUREID tid, bool validate_value): returns true when tid resembles texture ID and (optionally checked) contains valid value (non-BAD and has proper generation)

TextureMetaData get_texture_meta_data(TEXTUREID id)

Get texture meta data.

Parameters:: id – ID of the texture to get the meta data for

d3d::SamplerInfo get_sampler_info(const TextureMetaData &texture_meta_data, bool force_addr_from_tmd = true): Get a sampler info structure from texture meta data.

d3d::SamplerHandle get_texture_separate_sampler(TEXTUREID id)

Returns separate sampler for the texture ID.

Note

Returned sampler must not be destroyed

Note

The function is not thread-safe, and the caller must ensure that there are no concurrent setters for this texture ID

Parameters:: id – ID of the texture to get the sampler for
Returns:: Sampler handle for the texture. If no separate sampler is set, returns invalid handle

bool set_texture_separate_sampler(TEXTUREID id, const d3d::SamplerInfo &sampler_info)

Sets separate sampler for the texture ID.

Note

Calling a function for the same texture ID is not thread-safe

Note

Calling a function for different texture IDs is thread-safe

Parameters:

id – ID of the texture to set the sampler for
sampler_info – Sampler info for sampler to set

Returns:

true if the sampler was set successfully, false otherwise

void set_add_lod_bias_batch(dag::Span<const LODBiasRule> rules)

Sets the LOD bias for a batch of substring-bias pairs.

Parameters:: rules – A span of LODBiasRule objects containing substring and LOD bias pairs.

Variables

int dgs_tex_quality: Read-only access to the current texture quality level.

Warning

This is READ-ONLY, do not modify this value

int dgs_tex_anisotropy: Read-only access to the current texture anisotropy.

Warning

This is READ-ONLY, do not modify this value

class TextureFactory

Texture factory provides custom creation mechanism.

Public Functions

TextureFactory() = default

TextureFactory(TextureFactory&&) = default

TextureFactory &operator=(TextureFactory&&) = default

inline virtual ~TextureFactory()

virtual BaseTexture *createTexture(TEXTUREID id) = 0

Create texture a with the specified ID.

Warning

Make sure to store the result to release it in releaseTexture()

Parameters:: id – ID of the texture to create

virtual void releaseTexture(BaseTexture *texture, TEXTUREID id) = 0

Release a texture that was created using createTexture.

Parameters:

texture – Texture to release
id – ID of the texture to release

inline virtual void texFactoryActiveChanged(bool): A callback that is called on install/uninstall.

inline virtual bool scheduleTexLoading(TEXTUREID, TexQL)

Schedules loading of specified texture (if applicable)

Note

Thread-safe

Parameters:

id – ID of the texture to load
req_ql – Required quality level

Returns:

true when loading scheduled successfully

inline virtual bool getTextureDDSx(TEXTUREID, Tab<char>&)

Loads and returns contents of texture as DDSx data.

Warning

This function is synchronous and should be used with caution

Parameters:

id – ID of the texture to load
out_ddsx – Output buffer for DDSx data

Returns:

true when texture was loaded successfully

inline virtual void onUnregisterTexture(TEXTUREID)

Callback for notification of texture being unregistered from the manager.

Parameters:: id – ID of the texture that was unregistered

inline virtual bool isPersistentTexName(const char*)

Determines whether the string nm has static lifetime and can be referenced at any time without copying.

Parameters:: nm – String to check
Returns:: true if the string is persistent

Public Static Functions

static void onTexFactoryDeleted(TextureFactory *f): When a texture factory instance is destroyed at runtime, this function must be called to notify the manager about it.

Warning

This should not be called from factories which are static singletons or are destroyed after the manager was already de-initialized.

struct LODBiasRule

Public Members

const char *substring

float bias