AnimationCatalog.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Valentin Eloy
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
#include <filesystem>
#include <optional>
#include <string>
#include <string_view>
 
#include "Core/Ecs/AnimationClip.h"
#include "Core/Ecs/Components/Animation.h"
#include "Core/Ecs/Components/Sprite.h"  // core::AtlasRegion
#include "HMI/Graphics/AssetContract.h"  // hmi::AssetValidation

 
#include "Core/Data/JsonDocument.h"
 
namespace hmi {

enum class AnimationCatalogError {
    None,                 
    FileNotFound,         
    ParseError,           
    UnsupportedVersion,   
    MalformedStructure,   
    IncoherentFrameSize,  
};

struct AnimationDescription {
    int frameWidth = 0;
    int frameHeight = 0;
    core::ClipSet clips;
};

struct AnimationDescriptionResult {
    std::optional<AnimationDescription> description;
    std::string error;
    AnimationCatalogError errorCode = AnimationCatalogError::None;

    [[nodiscard]] bool ok() const noexcept {
        return description.has_value();
    }
};

class AnimationCatalog {
public:
    static constexpr int FORMAT_VERSION = 1;

    static constexpr float DEFAULT_FRAME_DURATION_SECONDS = 0.1f;

    [[nodiscard]] static AnimationDescriptionResult loadFromString(std::string_view json);

    [[nodiscard]] static AnimationDescriptionResult loadFromFile(const std::filesystem::path& path);
 
private:
    [[nodiscard]] static AnimationDescriptionResult fromDocument(
        const core::JsonDocument& document);
 
public:
    [[nodiscard]] static std::string descriptorFileName(std::string_view assetFileName);

    [[nodiscard]] static AssetValidation validateAgainstTexture(
        const AnimationDescription& description, const std::string& fileName, int textureWidth,
        int textureHeight);

    [[nodiscard]] static core::AtlasRegion frameRegion(const AnimationDescription& description,
                                                       int frameSheetIndex);

    [[nodiscard]] static core::AtlasRegion currentFrameRegion(
        const AnimationDescription& description, const core::Animation& animation);
};
 
}  // namespace hmi