Corrade::Utility::Resource class
#include <Corrade/Utility/Resource.h>

Data resource management.

Contents

This class provides support for compiled-in data resources - both compiling and reading. Resources can be differentiated into more groups, every resource in given group has unique filename.

See Resource management for brief introduction and example usage. Standalone resource compiler executable is implemented in corrade-rc.

Resource configuration file

Function compileFrom() takes a configuration file as parameter. The file allows you to specify filenames and filename aliases of resource files instead of passing the data manually to compile(). The file is used when compiling resources using corrade_add_resource() via CMake. The file can be also used when overriding compiled-in resources with live data using overrideGroup(). All filenames are expected to be in UTF-8. Example file:

group=myGroup

[file]
filename=../resources/intro-new-final.ogg
alias=intro.ogg

[file]
filename=license.txt

[file]
filename=levels-insane.conf
alias=levels-easy.conf

Thread safety

The resources register themselves into a global storage. If done implicitly, the registration is executed before entering main() and thus serially. If done explicitly via CORRADE_RESOURCE_INITIALIZE() / CORRADE_RESOURCE_FINALIZE(), these macros have to be called from a single thread or externally guarded to avoid data races. Same goes for the overrideGroup() function.

On the other hand, all other functionality only reads from the global storage and thus is thread-safe.

Public static functions

static auto compile(const std::string& name, const std::string& group, const std::vector<std::pair<std::string, std::string>>& files) -> std::string
Compile data resource file.
static auto compileFrom(const std::string& name, const std::string& configurationFile) -> std::string
Compile data resource file using configuration file.
static void overrideGroup(const std::string& group, const std::string& configurationFile)
Override group.
static auto hasGroup(const std::string& group) -> bool
Whether given group exists.
template<std::size_t size>
static auto hasGroup(const char(&group)[size]) -> bool

Constructors, destructors, conversion operators

Resource(const std::string& group) explicit
Constructor.
template<std::size_t size>
Resource(const char(&group)[size]) explicit

Public functions

auto list() const -> std::vector<std::string>
List of all resources in the group.
auto getRaw(const std::string& filename) const -> Containers::ArrayView<const char>
Get resource data.
template<std::size_t size>
auto getRaw(const char(&filename)[size]) const -> Containers::ArrayView<const char>
auto get(const std::string& filename) const -> std::string
Get resource data as a std::string.

Function documentation

static std::string Corrade::Utility::Resource::compile(const std::string& name, const std::string& group, const std::vector<std::pair<std::string, std::string>>& files)

Compile data resource file.

Parameters
name Resource name (see CORRADE_RESOURCE_INITIALIZE())
group Group name
files Files (pairs of filename, file data)

Produces a C++ file with hexadecimal data representation.

static std::string Corrade::Utility::Resource::compileFrom(const std::string& name, const std::string& configurationFile)

Compile data resource file using configuration file.

Parameters
name Resource name (see CORRADE_RESOURCE_INITIALIZE())
configurationFile Filename of configuration file

Produces a C++ file with hexadecimal data representation. See class documentation for configuration file syntax overview. The filenames are taken relative to configuration file path.

static void Corrade::Utility::Resource::overrideGroup(const std::string& group, const std::string& configurationFile)

Override group.

Parameters
group Group name
configurationFile Filename of configuration file. Empty string will discard the override.

Overrides compiled-in resources of given group with live data specified in given configuration file, useful during development and debugging. Subsequently created Resource instances with the same group will take data from live filesystem instead and fallback to compiled-in resources only for files that are not found.

template<std::size_t size>
static bool Corrade::Utility::Resource::hasGroup(const char(&group)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Corrade::Utility::Resource::Resource(const std::string& group) explicit

Constructor.

Expects that the group exists.

template<std::size_t size>
Corrade::Utility::Resource::Resource(const char(&group)[size]) explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::vector<std::string> Corrade::Utility::Resource::list() const

List of all resources in the group.

Note that the list contains only list of compiled-in files, no additional filenames from overridden group are included.

Containers::ArrayView<const char> Corrade::Utility::Resource::getRaw(const std::string& filename) const

Get resource data.

Parameters
filename Filename in UTF-8

Returns a view on data of given file in the group. Expects that the file exists. If the file is empty, returns nullptr.

template<std::size_t size>
Containers::ArrayView<const char> Corrade::Utility::Resource::getRaw(const char(&filename)[size]) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::Resource::get(const std::string& filename) const

Get resource data as a std::string.

Parameters
filename Filename in UTF-8

Returns data of given file in the group. Expects that the file exists.