Embedded Resources Management

There are some APIs (e.g., VTK) which can load resources (models, textures) only from files specified by a name, not by a file handle or memory location. This APIs prevent embedding the resources into the binary. Embedding the resources into binary makes it portable and install-location independent.

ResourceManager and ResourceFile help to create a temporary file from a resource embedded in the binary, and therefore, provide a file name for such resource.

Usage

To use an embedded resource you have to:

  • embed the resource into the binary as a blob,

  • load it in the program,

  • get filename.

Embedding of the resources is handled by a CMake macro:

# resources can be an arbitrary, but unique name
# multiple resource files are allowed
add_resources(resources "resouceFile1.bmp" resourceFile2.obj")
# Then you specify resources as one of the sources for you executable/library
add_executable(myProject ${resources} main.cpp)

Then you can use the resource in your code:

// Slashes and dots in file names are replaced by an underscore
// Note that the resource name is not string (it is a symbol actually)
ResourceFile myResource = LOAD_RESOURCE_FILE( resouceFile1_bmp );
// Call the api with file name:
loadTexture( myResource.name() );

Classes reference

class ResourceManager

Manager of embedded resources.

ResourceManager allows the user to register a resource and obtain a file name for it. The class is a singleton, obtain instance by calling ResourceManager::inst().

This class is usually not needed when working with resources specified via CMake macro. Look at ResourceFile and LOAD_RESOURCE_FILE instead.

Public Functions

inline ~ResourceManager()
inline std::filesystem::path add(const char *data, std::ptrdiff_t count)

Add a resource and obtain a valid file path for it.

If the resource on given address was already added, existing file is returned. The resource is specified by address and its size in bytes.

Public Static Functions

static inline ResourceManager &inst()

Get an instance of the manager.

class ResourceFile

Represents a single resource with na associated filename.

If you are using resources specified by the CMake macro, do not create instances of the class directly, but use macro LOAD_RESOURCE_FILE.

Public Functions

inline ResourceFile(const char *start, const char *end)
inline ResourceFile(const char *data, std::ptrdiff_t count)
inline std::filesystem::path name() const

Get filename associated with given resource.

Macro reference

LOAD_RESOURCE_FILE(x)

Obtain an instance of ResourceFile for given resource specified by the CMake macro.

Specify the resource name directly, without string quotes, and replace special symbols by and underscore. E.g., for resource test/file.bmp use test_file_bmp.