utility.hpp

Go to the documentation of this file.

// This file is part of the Rendering Engine project.
// Author: Alexander Obzherin <alexanderobzherin@gmail.com>
// Copyright (c) 2026 Alexander Obzherin
// Distributed under the terms of the zlib License. See LICENSE.md for details.
#pragma once
 
#include <iostream>
#include <cstdint>
#include <fstream>
#include <string>
#include <vector>
#include <filesystem>
#include <unordered_map>
 
#include "rendering_engine_export.hpp"
 
namespace rendering_engine
{
/**
 * @struct AppConfig
 * @brief Basic application settings loaded from a configuration file.
 *
 * This structure represents a minimal configuration schema for applications
 * built using the Rendering Engine. Values are typically read from
 * `Config/app_config.json` at startup and applied during window creation.
 */
struct AppConfig
{
    /** @brief Name of the application */
    std::string appName;
    /** @brief Whether the application should start in full-screen mode. */
    bool isFullScreen = false;
    /** @brief Desired window width in pixels (ignored in full-screen mode). */
    float screenWidth = 800.0f;
    /** @brief Desired window height in pixels (ignored in full-screen mode). */
    float screenHeight = 600.0f;
    /** @brief Unicode scripts to preload for text rendering. */
    std::vector<std::string> textScripts{"Latin"};
    /** @brief Font sizes to preload at startup. */
    std::vector<int> fontSizePreload{10};
    /** @brief Logging verbosity level ("Error", "Warning", "Info", "Debug"). */
    std::string logLevel{"Info"};
    /** @brief Enable FPS smoothing and frame pacing behavior. */
    bool useSmoothedFPS = true;
    /** @brief Target frame rate (0 = uncapped). */
    float targetFPS = 60.0f;
    /** @brief Enable on-screen statistics overlay. */
    bool showStatsOverlay = true;
};
 
/**
 * @struct PackEntry
 * @brief Metadata describing one file stored inside a packed asset archive.
 */
struct PackEntry
{
    size_t offset;
    size_t size;
};
 
using PackEntries = std::unordered_map<std::string, PackEntry>;
 
/**
 * @class Utility
 * @brief Provides static helper methods for file I/O and path management.
 *
 * The Utility class centralizes filesystem operations such as locating shader binaries,
 * listing files, and resolving build or application paths.
 *
 * All methods are static and thread-safe, designed for use throughout the engine.
 */
class RE_API Utility final
{
public:
    /**
     * @brief Initializes engine paths based on the executable location.
     *
     * Should be called once during startup to establish base directories for
     * application, build, and shader assets.
     *
     * @param argc Command-line argument count.
     * @param argv Command-line argument vector.
     */
    static void InitializePaths(int argc, char* argv[]);
    /**
     * @brief Reads application settings from the JSON config file.
     *
     * Missing or invalid fields fall back to default AppConfig values.
     *
     * @return Populated AppConfig structure.
     */
    static AppConfig ReadConfigFile();
    /**
     * @brief Reads a binary shader file from disk.
     * @param filename Path to the shader file.
     * @return Vector containing the binary data.
     */
    static std::vector<char> ReadShaderBinaryFile( std::string const & filename );
    /**
     * @brief Returns a list of full file paths in the given directory.
     * @param directory Directory path to search.
     * @return Vector of file paths.
     */
    static std::vector<std::string> GetListOfFilesInDirectory( std::string directory );
    /**
     * @brief Returns the absolute path of the running application.
     * @return Application path as std::filesystem::path.
     */
    static std::filesystem::path GetApplicationPath();
    /**
     * @brief Returns the build output directory path.
     * @return Build path as std::filesystem::path.
     */
    static std::filesystem::path GetBuildPath();
    /**
     * @brief Returns the directory path containing compiled shader binaries.
     * @return Shader binary path as std::filesystem::path.
     */
    static std::filesystem::path GetShadersBinaryPath();
    /**
     * @brief Returns a list of file names in a directory matching the specified extension.
     * @param directory Directory path.
     * @param extToSearch File extension to match (e.g., ".spv").
     * @return Vector of matching file names.
     */
    static std::vector<std::string> GetListOfFileNamesInDirectory(const char* directory, std::string extToSearch);
 
    /// @brief Resolves project root folder (handles Release/Debug/Binaries layouts).
    static std::filesystem::path ResolveProjectRoot();
 
    /// @brief Returns absolute path to Content.
    static std::filesystem::path GetContentFolderPath();
 
    /// @brief Returns absolute path to Content/Textures.
    static std::filesystem::path GetTextureFolderPath();
 
    /// @brief Returns absolute path to Content/Models.
    static std::filesystem::path GetModelsFolderPath();
 
    /// @brief Returns absolute path to Content/Fonts.
    static std::filesystem::path GetFontsFolderPath();
 
    /// @brief Returns absolute path to Content/Shaders.
    static std::filesystem::path GetShadersFolderPath();
 
    /// @brief Returns absolute path to Config/app_config.json.
    static std::filesystem::path GetConfigFilePath();
 
    /// @brief Returns absolute path to Logs folder.
    static std::filesystem::path GetLogsFolderPath();
 
    /**
     * @brief Checks whether packed assets (Pack.bin / Pack.json) exist.
     */
    static bool IsPackageProvided();
 
    /**
     * @brief Returns the manifest of packed files.
     */
    static const PackEntries& GetPackEntries();
 
    /**
     * @brief Reads raw bytes of a file stored inside Pack.bin.
     *
     * @param entryPath Virtual path inside the pack (e.g. "Textures/my.png").
     * @return Decoded file bytes, or empty vector on failure.
     */
    static std::vector<uint8_t> ReadPackedFile(const std::string& entryPath);
 
    private:
        Utility();
        Utility( const Utility& rhs );
        Utility& operator=( const Utility& rhs );
 
        static std::filesystem::path FindPath( std::string fileOrFolderName, std::string searchingFrom = "../../" );
 
    public:
        static std::filesystem::path sApplicationPath;
        static std::filesystem::path const sDefaultShadersBinaryRelativePath;
        static std::filesystem::path sBuildPath;
        static std::filesystem::path sShadersBinaryPath;
        static std::filesystem::path const sContentRelativePathFolder;
        static std::filesystem::path const sContentPackageFilePath;
        static std::filesystem::path const sContentPackEntriesFilePath;
        static std::filesystem::path const sTextureRelativePathFolder;
        static std::filesystem::path const sModelsRelativePathFolder;
        static std::filesystem::path const sFontsRelativePathFolder;
        static std::filesystem::path const sShadersRelativePathFolder;
        static std::filesystem::path const sAppConfigFilePath;
        static std::filesystem::path const sLogFolderPath;
        
};
 
}