Synopsis

qul_set_maximum_resource_cache_size(<target>
                                    CACHE_SIZE <cache_size_in_bytes>
                                    [RUNTIME_ALLOCATION_TYPE <runtime_allocation_type>])

Description

This command sets the maximum resource cache size for a given runtime allocation type.

The resource cache is used to cache resources with the "OnDemand" cache policy. This includes all compressed resources, as well as resources that have the QUL_RESOURCE_CACHE_POLICY property explicitly set to "OnDemand". When such resources are visible, they will be copied to the resource cache corresponding to the resource's runtime allocation type. If the resource cache is full at that point, resources that have been in the cache for the longest time without being used will be evicted in order to make space for the new resource.

Ensure that the maximum resource cache size is larger than the size of the biggest resource with the "OnDemand" cache policy. An ideal maximum resource cache size should be able to fit all "OnDemand" images that might be visible at the same time, to prevent having to decompress or copy image resources to RAM on each frame update.

For example, a 400x300 image with 32 bpp color depth occupies up to 480,000 bytes of RAM. If there could be two such images visible at the same time, and their cache policy is "OnDemand", then a reasonable maximum resource cache size would be 960,000 bytes:

# Assuming that no custom runtime allocation type has been set for the images
qul_set_maximum_resource_cache_size(<target> CACHE_SIZE 960000)

Options

The CACHE_SIZE option is mandatory, and specifies the maximum cache size in bytes.

The RUNTIME_ALLOCATION_TYPE option is of integer type and its value has to be greater than or equal to 0 and less than 256. It corresponds to the QUL_RESOURCE_RUNTIME_ALLOCATION_TYPE set for each individual resource. The value has to match the memory allocator types known by the platform, where the range [128,255] is dedicated to user-defined custom allocators.

If the RUNTIME_ALLOCATION_TYPE option is not given, then by default the Image enum value will be used.

Internally, the resource cache sizes are collected and passed to the qulrcc tool resource compiler in a JSON file. qulrcc tool generates C++ files with necessary symbols needed by the Qul::Core library to know the cache sizes for each runtime allocation type.