Resource Management

xygine currently provides two means of resource management. The preferred method is conducted with xy::ResourceHandler. This class provides templated load() and get() functions which can be used on the following types:

• sf::Font
• sf::Texture
• sf::SoundBuffer
• sf::Image

It can also be used with any custom resource type which provides a loadFromFile(const std::string&) function. sf::Shader is a special case, however, see xy::ShaderResource below for more information.

The ResourceHandler is used to precache resources at load-time and returns a handle which can be used to gain a reference to a resource quickly at runtime. For example one might do the following:

namespace FontID
{
    enum
    {
        MenuFont, TextFont, ScoreFont, Count
    };
    static std::array<std::size_t, FontID::Count> handles = {};
}

//when loading
FontID::handles[FontID::MenuFont] = m_resourceHandler.load<sf::Font>("myFancyFont.ttf");

//at runtime
entity.addComponent<xy::Text>(m_resourceHandler.get<sf::Font>(FontID::handles[FontID::MenuFont]));

ResourceHandler will provide fall-back resources should loading a resource fail, although in the case of sf::Font the default action is to try and find a common system font. On linux this means making sure FONT_PATH is defined with a string containing the current font directory when building xygine, as the default font directory varies between distributions.

Legacy resource management is provided via a templated interface xy::BaseResource. For example xygine implements the interface in classes such as xy::TextureResource and xy::FontResource. Not only does the resource management class ensure that a single instance of a resource exists at any one time, it also provides a way to deal with fallbacks, should a requested resource not be found. xy::TextureResource will return a texture with a solid colour as defined by xy::TextureResource::setFallbackColour() and xy:::FontResource will supply a default font (see caveat above). xygine offers the following resource management classes:

• xy::FontResource - manages instances of sf::Font
• xy::ImageResource - resource management for sf::Image
• xy::ShaderResource - precaches compiled sf::Shaders
• xy::SoundResource - resource management for sf::SoundBuffer objects
• xy::TextureResource - manages sf::Texture instances

These all implement the xy::BaseResource interface with the exception of xy::ShaderResource (see below). To implement your own resource manager create a class which inherits xy::BaseResource and implement the pure virtual function errorHandle() which should return a unique_ptr of the type to be managed by the class. This unique_ptr should point to the object used as a default resource should loading a resource from disk fail. Legacy resource management is only preferred when the caching of resource handles is inconvenient.

xy::ShaderResource

The shader resource manager differs slightly from the other resource management classes. Shaders are created from strings in memory (how you aquire these is up to you) and mapped to an integer ID, stored (for example) as an enum value. As no reasonable default values can be returned for a shader xygine will throw an assertion error in debug mode when creating a shader fails. Shaders should all be loaded via the precache() function during load time, as some shaders may take a small amount of time to compile and cause interruptions should they be loaded during gameplay. Shaders can then be quickly accessed from the resource manager by using the get() function along with the specific shader ID. Remember that, as each shader exists only once, when a drawable using a shader modifies the shader's property via sf::Shader::setUniform (or setParameter() in older versions of SFML) any drawable using that shader will have the same uniform parameters applied and will need to update these values itself should it need to.