class EE::Graphics::ResourceCatalog¶

Overview¶

Thread-safe, strongly owning collection of named graphics resources. More…

#include <resourcecatalog.hpp>

class ResourceCatalog {
public:
    // methods

    static ResourceCatalogPtr New();
    void publish(ResourceKey key, TexturePtr texture);
    void publish(std::string key, TexturePtr texture);
    void publishDrawable(ResourceKey key, DrawablePtr drawable);
    void publishDrawable(std::string key, DrawablePtr drawable);
    void publishAtlas(ResourceKey key, TextureAtlasPtr atlas);
    void publishAtlas(std::string key, TextureAtlasPtr atlas);
    void publishFont(ResourceKey key, FontPtr font);
    void publishFont(std::string key, FontPtr font);
    void publishShaderProgram(ResourceKey key, ShaderProgramPtr program);
    void publishShaderProgram(std::string key, ShaderProgramPtr program);
    TexturePtr findTexture(const ResourceKey& key) const;
    TexturePtr findTexture(const std::string& key) const;
    DrawablePtr findDrawable(const ResourceKey& key) const;
    DrawablePtr findDrawable(const std::string& key) const;
    DrawablePtr findDrawable(ResourceNameHash hash) const;
    DrawablePtr findDrawable(String::HashType legacyHash) const;
    TextureAtlasPtr findAtlas(const ResourceKey& key) const;
    TextureAtlasPtr findAtlas(const std::string& key) const;
    std::vector<TextureAtlasPtr> getAtlases() const;
    FontPtr findFont(const ResourceKey& key) const;
    FontPtr findFont(const std::string& key) const;
    FontPtr findFont(ResourceNameHash hash) const;
    std::vector<FontPtr> getFonts() const;
    ShaderProgramPtr findShaderProgram(const ResourceKey& key) const;
    ShaderProgramPtr findShaderProgram(const std::string& key) const;
    std::vector<ShaderProgramPtr> getShaderPrograms() const;
    bool erase(const ResourceKey& key);
    bool erase(const std::string& key);
    bool eraseDrawable(const ResourceKey& key);
    bool eraseDrawable(const std::string& key);
    bool eraseAtlas(const ResourceKey& key);
    bool eraseAtlas(const std::string& key);
    bool eraseFont(const ResourceKey& key);
    bool eraseFont(const std::string& key);
    bool eraseFont(Font* font);
    bool eraseShaderProgram(const ResourceKey& key);
    bool eraseShaderProgram(const std::string& key);
    void clear();
    std::size_t size() const;
};

Detailed Documentation¶

Thread-safe, strongly owning collection of named graphics resources.

A catalog maps semantic string keys to textures, drawable sources, texture atlases, and fonts. Publishing a resource gives the catalog shared ownership of it. Publishing another resource of the same kind under the same key replaces that binding; the key and resource name are never changed automatically. Publishing a null handle is equivalent to erasing the corresponding key, while an empty key is ignored.

Lookups return owning handles. A resource obtained from a catalog therefore remains alive even if its binding is subsequently replaced, erased, or the catalog is cleared. Final handles are released after dropping the catalog mutex so resource destruction and callbacks never execute while the catalog is locked.

Drawable and font hash lookups use resourceNameHash() as a direct secondary index. The dedicated 64-bit hash provides a cheap expected-O(1) convenience lookup for trusted names without changing the repository-wide 32-bit String::HashType. A hash is not mathematically collision-free, so complete ResourceKey lookup remains authoritative and must be used for attacker-controlled names or persistent identity. ResourceNameHash values are process-local conveniences and must not be serialized.

ResourceCatalog performs no parent, scene, live-registry, filesystem, or fallback search. A ResourceScope defines lookup precedence by searching its local catalog and then explicitly imported catalogs. Importing a catalog shares this object and its live contents; it does not copy any resource.

All public operations are safe to call concurrently. Enumeration methods return snapshots and allocate vectors containing owning handles.

Methods¶

static ResourceCatalogPtr New()

Returns:

A new empty catalog using eepp resource allocation and deletion.

void publish(ResourceKey key, TexturePtr texture)

Publishes or replaces a texture binding. A null texture erases key.

void publish(std::string key, TexturePtr texture)

Publishes or replaces a texture binding. A null texture erases key.

void publishDrawable(ResourceKey key, DrawablePtr drawable)

Publishes or replaces a drawable-source binding. A null drawable erases key.

void publishDrawable(std::string key, DrawablePtr drawable)

Publishes or replaces a drawable-source binding. A null drawable erases key.

void publishAtlas(ResourceKey key, TextureAtlasPtr atlas)

Publishes or replaces a texture-atlas binding. A null atlas erases key.

void publishAtlas(std::string key, TextureAtlasPtr atlas)

Publishes or replaces a texture-atlas binding. A null atlas erases key.

void publishFont(ResourceKey key, FontPtr font)

Publishes or replaces a font binding. A null font erases key.

void publishFont(std::string key, FontPtr font)

Publishes or replaces a font binding. A null font erases key.

void publishShaderProgram(ResourceKey key, ShaderProgramPtr program)

Publishes or replaces a shader-program binding. A null program erases key.

void publishShaderProgram(std::string key, ShaderProgramPtr program)

Publishes or replaces a shader-program binding. A null program erases key.

TexturePtr findTexture(const ResourceKey& key) const

Returns:

The texture bound to key, or an empty handle when it is not present.

TexturePtr findTexture(const std::string& key) const

Returns:

The texture bound to key, or an empty handle when it is not present.

DrawablePtr findDrawable(const ResourceKey& key) const

Returns:

The drawable source bound to key, or an empty handle when it is not present.

DrawablePtr findDrawable(const std::string& key) const

Returns:

The drawable source bound to key, or an empty handle when it is not present.

DrawablePtr findDrawable(ResourceNameHash hash) const

Looks up a drawable through the resourceNameHash(key) convenience index.

DrawablePtr findDrawable(String::HashType legacyHash) const

Legacy lookup for persisted 32-bit drawable hashes.

This compatibility path scans full bindings and should not be used by new code. Persistent formats should migrate to complete ResourceKey values rather than serializing another hash. If several names share legacyHash, which matching drawable is returned is unspecified.

TextureAtlasPtr findAtlas(const ResourceKey& key) const

Returns:

The texture atlas bound to key, or an empty handle when it is not present.

TextureAtlasPtr findAtlas(const std::string& key) const

Returns:

The texture atlas bound to key, or an empty handle when it is not present.

std::vector<TextureAtlasPtr> getAtlases() const

Returns:

An owning snapshot of all texture atlases currently published in this catalog.

FontPtr findFont(const ResourceKey& key) const

Returns:

The font bound to key, or an empty handle when it is not present.

FontPtr findFont(const std::string& key) const

Returns:

The font bound to key, or an empty handle when it is not present.

FontPtr findFont(ResourceNameHash hash) const

Looks up a font through the resourceNameHash(key) convenience index.

std::vector<FontPtr> getFonts() const

Returns:

An owning snapshot of all fonts currently published in this catalog.

ShaderProgramPtr findShaderProgram(const ResourceKey& key) const

Returns:

The shader program bound to key, or an empty handle when absent.

ShaderProgramPtr findShaderProgram(const std::string& key) const

Returns:

The shader program bound to key, or an empty handle when absent.

std::vector<ShaderProgramPtr> getShaderPrograms() const

Returns:

An owning snapshot of all shader programs published in this catalog.

bool erase(const ResourceKey& key)

Removes the texture binding for key.

Returns: