feat(graphics): add stable mesh resource caching

Author: OmarAglan

AGENTS.md

@@ -5,7 +5,7 @@
 - `Engine/` builds the C++17 `PyramidEngine` library.
 - Active modules are Core, Graphics, Math, Platform, and Utils.
 - `Examples/BasicGame` and `Examples/BasicRendering` are the graphical references.
-- `Tests/PublicApiLinkage.cpp` protects selected public symbols; `Tests/WindowResizeEventTests.cpp` protects resize callback semantics; `Tests/CameraViewportTests.cpp` protects projection resizing; `Tests/FramebufferResizeTests.cpp` protects framebuffer specification and zero-area resize behavior; `Tests/TextureLoadingTests.cpp` protects transactional file loading and OpenGL upload state; `Tests/SceneTransformTests.cpp` protects hierarchy composition, invalidation, reparenting, cycle rejection, and parent-destruction behavior; `Tests/CameraFrustumTests.cpp` protects camera orientation, frustum extraction, transformed bounds, and linear/octree scene visibility; `Tests/OctreeUpdateTests.cpp` protects incremental movement, insertion, removal, and stable-scene synchronization; `Tests/OctreeQueryTests.cpp` protects bounds-accurate point, sphere, box, and nearest-first ray queries plus linear/octree parity; `Tests/NearestQueryTests.cpp` protects bounds-distance nearest/K-nearest ordering, limits, root-overflow behavior, and octree/linear parity. `Tests/OctreeConfigurationTests.cpp` protects atomic bounds/depth/capacity changes, tracked-object preservation, invalid configuration rejection, and constructor normalization. `Tests/OctreeCompactionTests.cpp` protects automatic branch collapse after removals and movement, explicit no-op compaction, synchronization compaction statistics, object preservation, and health-metric consistency. `Tests/RenderObjectBoundsTests.cpp` protects mesh-derived/manual transformed bounds. `Tests/MeshResourceTests.cpp` protects mesh validation, immutable metadata, topology-aware indexed/non-indexed submission, and `RenderObject` integration.
+- `Tests/PublicApiLinkage.cpp` protects selected public symbols; `Tests/WindowResizeEventTests.cpp` protects resize callback semantics; `Tests/CameraViewportTests.cpp` protects projection resizing; `Tests/FramebufferResizeTests.cpp` protects framebuffer specification and zero-area resize behavior; `Tests/TextureLoadingTests.cpp` protects transactional file loading and OpenGL upload state; `Tests/SceneTransformTests.cpp` protects hierarchy composition, invalidation, reparenting, cycle rejection, and parent-destruction behavior; `Tests/CameraFrustumTests.cpp` protects camera orientation, frustum extraction, transformed bounds, and linear/octree scene visibility; `Tests/OctreeUpdateTests.cpp` protects incremental movement, insertion, removal, and stable-scene synchronization; `Tests/OctreeQueryTests.cpp` protects bounds-accurate point, sphere, box, and nearest-first ray queries plus linear/octree parity; `Tests/NearestQueryTests.cpp` protects bounds-distance nearest/K-nearest ordering, limits, root-overflow behavior, and octree/linear parity. `Tests/OctreeConfigurationTests.cpp` protects atomic bounds/depth/capacity changes, tracked-object preservation, invalid configuration rejection, and constructor normalization. `Tests/OctreeCompactionTests.cpp` protects automatic branch collapse after removals and movement, explicit no-op compaction, synchronization compaction statistics, object preservation, and health-metric consistency. `Tests/RenderObjectBoundsTests.cpp` protects mesh-derived/manual transformed bounds. `Tests/MeshResourceTests.cpp` protects mesh validation, immutable metadata, topology-aware indexed/non-indexed submission, and `RenderObject` integration. `Tests/MeshCacheTests.cpp` protects deterministic identifiers, exact-content deduplication, alias conflicts, upload counts, strong residency, unused collection, explicit eviction, and external-owner lifetime.
 - `Tests/Consumer` validates the installed CMake package.
 - `vendor/glad` is a bundled public dependency. libjpeg-turbo is an external open-source dependency resolved through CMake `FindJPEG`.
 - The supported Windows toolchain is MSYS2 UCRT64 with MinGW-w64 GCC; Clang is also validated. Visual Studio is not required.
@@ -32,7 +32,7 @@ ctest --preset test-gcc-release
 
 - C++17, four spaces, braces on new lines.
 - Types/public methods use `PascalCase`; locals/parameters use `camelCase`; fields use `m_`.
-- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`.
+- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`. Shared reusable geometry should be acquired through a graphics-device-bound `MeshCache`; do not create parallel uploads for byte-identical mesh specifications.
 - Do not add required interface methods with silent no-op defaults.
 - Do not expose source-tree absolute paths through installed target interfaces.
 

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to Pyramid Engine are documented here. The project is pre-al
 
 ## [Unreleased]
 
+### Stable mesh identifiers and resource caching
+
+- Added deterministic 128-bit `MeshAssetId` values from caller-owned stable names or exact mesh content. Content fingerprints include vertex/index bytes, layout semantics, counts, normalization flags, and primitive topology while excluding debug names.
+- Added `MeshCache`, which owns one resident GPU mesh per unique content fingerprint and resolves any number of stable asset-ID aliases to that upload.
+- Added hard conflict detection when one explicit asset identifier is reused for different resident geometry.
+- Added explicit `Evict()`, `CollectUnused()`, and `Clear()` lifetime controls; cache eviction releases cache ownership without invalidating external `shared_ptr<Mesh>` instances.
+- Added mesh/cache residency statistics for hits, misses, creations, failures, conflicts, evictions, identifier aliases, externally referenced resources, and resident geometry bytes.
+- Migrated both examples to the cache and added `Graphics.MeshCache` coverage for deterministic IDs, alias deduplication, upload counts, conflicts, residency, collection, eviction, and external-owner lifetime.
+
 ### Engine-owned mesh resources
 
 - Added `Mesh` and `MeshSpecification` as the authoritative geometry resource for vertex/index ownership, layout, draw count, primitive topology, and immutable local bounds.

Engine/Graphics/CMakeLists.txt

@@ -14,6 +14,7 @@ target_sources(PyramidEngine
         source/Buffer/UniformBuffer.cpp
         source/Geometry/MeshBounds.cpp
         source/Geometry/Mesh.cpp
+        source/Geometry/MeshCache.cpp
         source/OpenGL/Shader/OpenGLShader.cpp
         source/Texture.cpp
         source/OpenGL/OpenGLTexture.cpp
@@ -43,6 +44,7 @@ target_sources(PyramidEngine
         include/Pyramid/Graphics/Geometry/Vertex.hpp
         include/Pyramid/Graphics/Geometry/MeshBounds.hpp
         include/Pyramid/Graphics/Geometry/Mesh.hpp
+        include/Pyramid/Graphics/Geometry/MeshCache.hpp
         include/Pyramid/Graphics/PrimitiveTopology.hpp
         include/Pyramid/Graphics/Renderer/RenderSystem.hpp
         include/Pyramid/Graphics/Renderer/ShaderPathResolver.hpp

Engine/Graphics/include/Pyramid/Graphics/Geometry/Mesh.hpp

@@ -5,8 +5,10 @@
 #include <Pyramid/Graphics/PrimitiveTopology.hpp>
 #include <Pyramid/Math/Math.hpp>
 
+#include <cstddef>
 #include <memory>
 #include <string>
+#include <string_view>
 
 namespace Pyramid
 {
@@ -20,12 +22,46 @@ namespace Pyramid
         class CommandBuffer;
     }
 
+    /**
+     * @brief Stable 128-bit identifier for a mesh asset.
+     *
+     * Caller-defined identifiers can be created from stable names such as asset
+     * paths. When a specification does not provide an identifier, Pyramid derives
+     * one deterministically from the exact vertex/index bytes, layout, counts, and
+     * primitive topology. Debug names are deliberately excluded.
+     */
+    struct MeshAssetId
+    {
+        u64 high = 0;
+        u64 low = 0;
+
+        bool IsValid() const { return high != 0 || low != 0; }
+        std::string ToString() const;
+
+        static MeshAssetId FromString(std::string_view stableName);
+
+        bool operator==(const MeshAssetId& other) const
+        {
+            return high == other.high && low == other.low;
+        }
+
+        bool operator!=(const MeshAssetId& other) const
+        {
+            return !(*this == other);
+        }
+    };
+
+    struct MeshAssetIdHash
+    {
+        std::size_t operator()(const MeshAssetId& identifier) const noexcept;
+    };
+
     /**
      * @brief Immutable source description used to create a GPU-backed mesh.
      *
      * Pyramid copies the supplied vertex/index data into engine-owned GPU buffers.
      * The caller only needs to keep the pointed-to memory alive for the duration of
-     * Mesh::Create().
+     * Mesh::Create() or MeshCache::GetOrCreate().
      */
     struct MeshSpecification
     {
@@ -39,14 +75,21 @@ namespace Pyramid
 
         PrimitiveTopology topology = PrimitiveTopology::Triangles;
         std::string name;
+
+        /**
+         * Optional stable caller-owned identifier. If invalid, the content
+         * fingerprint becomes the asset identifier automatically.
+         */
+        MeshAssetId assetId;
     };
 
     /**
      * @brief Engine-owned immutable geometry resource.
      *
      * A mesh owns the vertex array plus its vertex/index buffers and keeps the
-     * validated layout, draw count, topology, and local bounds together. This
-     * prevents RenderObject from depending on mutable raw vertex-array state.
+     * validated layout, draw count, topology, identifiers, and local bounds
+     * together. This prevents RenderObject from depending on mutable raw
+     * vertex-array state.
      */
     class Mesh final
     {
@@ -55,6 +98,12 @@ namespace Pyramid
             IGraphicsDevice& device,
             const MeshSpecification& specification);
 
+        /**
+         * @brief Calculate the deterministic fingerprint for a valid specification.
+         * @return Invalid identifier when the specification is malformed.
+         */
+        static MeshAssetId CalculateContentId(const MeshSpecification& specification);
+
         Mesh(const Mesh&) = delete;
         Mesh& operator=(const Mesh&) = delete;
         Mesh(Mesh&&) = delete;
@@ -69,9 +118,20 @@ namespace Pyramid
         u32 GetVertexCount() const { return m_vertexCount; }
         u32 GetIndexCount() const { return m_indexCount; }
         u32 GetDrawCount() const { return IsIndexed() ? m_indexCount : m_vertexCount; }
+        u64 GetVertexDataSize() const { return m_vertexDataSize; }
+        u64 GetIndexDataSize() const
+        {
+            return static_cast<u64>(m_indexCount) * sizeof(u32);
+        }
+        u64 GetGeometryDataSize() const
+        {
+            return GetVertexDataSize() + GetIndexDataSize();
+        }
         PrimitiveTopology GetTopology() const { return m_topology; }
         const BufferLayout& GetLayout() const { return m_layout; }
         const std::string& GetName() const { return m_name; }
+        MeshAssetId GetAssetId() const { return m_assetId; }
+        MeshAssetId GetContentId() const { return m_contentId; }
 
         void GetLocalBounds(Math::Vec3& minPoint, Math::Vec3& maxPoint) const;
 
@@ -85,9 +145,12 @@ namespace Pyramid
             std::shared_ptr<IVertexBuffer> vertexBuffer,
             std::shared_ptr<IIndexBuffer> indexBuffer,
             BufferLayout layout,
+            u32 vertexDataSize,
             u32 vertexCount,
             u32 indexCount,
             PrimitiveTopology topology,
+            MeshAssetId assetId,
+            MeshAssetId contentId,
             const Math::Vec3& localBoundsMin,
             const Math::Vec3& localBoundsMax,
             std::string name);
@@ -96,9 +159,12 @@ namespace Pyramid
         std::shared_ptr<IVertexBuffer> m_vertexBuffer;
         std::shared_ptr<IIndexBuffer> m_indexBuffer;
         BufferLayout m_layout;
+        u32 m_vertexDataSize = 0;
         u32 m_vertexCount = 0;
         u32 m_indexCount = 0;
         PrimitiveTopology m_topology = PrimitiveTopology::Triangles;
+        MeshAssetId m_assetId;
+        MeshAssetId m_contentId;
         Math::Vec3 m_localBoundsMin = Math::Vec3(-0.5f);
         Math::Vec3 m_localBoundsMax = Math::Vec3(0.5f);
         std::string m_name;

Engine/Graphics/include/Pyramid/Graphics/Geometry/MeshCache.hpp

@@ -0,0 +1,112 @@
+#pragma once
+
+#include <Pyramid/Core/Prerequisites.hpp>
+#include <Pyramid/Graphics/Geometry/Mesh.hpp>
+
+#include <memory>
+#include <unordered_map>
+
+namespace Pyramid
+{
+    class IGraphicsDevice;
+
+    /**
+     * @brief Snapshot of mesh-cache residency and acquisition activity.
+     */
+    struct MeshCacheStats
+    {
+        u64 cacheHits = 0;
+        u64 cacheMisses = 0;
+        u64 meshesCreated = 0;
+        u64 creationFailures = 0;
+        u64 identifierConflicts = 0;
+        u64 evictions = 0;
+
+        u32 residentMeshes = 0;
+        u32 residentAssetIds = 0;
+        u32 externallyReferencedMeshes = 0;
+        u64 residentVertexBytes = 0;
+        u64 residentIndexBytes = 0;
+
+        u64 GetResidentGeometryBytes() const
+        {
+            return residentVertexBytes + residentIndexBytes;
+        }
+    };
+
+    /**
+     * @brief Graphics-device-bound cache for immutable Mesh resources.
+     *
+     * Exact content is uploaded once even when it is requested through several
+     * stable asset identifiers. The cache owns one strong reference per unique
+     * geometry resource, so a resident mesh remains alive until it is explicitly
+     * evicted, cleared, or removed by CollectUnused(). Existing external
+     * shared_ptr instances remain valid after cache eviction.
+     *
+     * The cache and its meshes must be destroyed before the graphics
+     * device/context. MeshCache is intended for use on the graphics thread and is
+     * not internally synchronized.
+     */
+    class MeshCache final
+    {
+    public:
+        explicit MeshCache(IGraphicsDevice& device);
+
+        MeshCache(const MeshCache&) = delete;
+        MeshCache& operator=(const MeshCache&) = delete;
+        MeshCache(MeshCache&&) = delete;
+        MeshCache& operator=(MeshCache&&) = delete;
+        ~MeshCache() = default;
+
+        /**
+         * @brief Return a resident mesh or upload it once when absent.
+         *
+         * An invalid specification returns nullptr. Reusing one explicit asset ID
+         * with different geometry is rejected while the original entry is resident.
+         */
+        std::shared_ptr<Mesh> GetOrCreate(const MeshSpecification& specification);
+
+        std::shared_ptr<Mesh> Find(MeshAssetId assetId) const;
+        bool Contains(MeshAssetId assetId) const;
+
+        /**
+         * @brief Evict the resolved mesh and all identifiers that alias it.
+         * @return true when a resident resource was removed.
+         */
+        bool Evict(MeshAssetId assetId);
+
+        /**
+         * @brief Evict resources only owned by the cache.
+         * @return number of unique meshes removed.
+         */
+        u32 CollectUnused();
+
+        /**
+         * @brief Evict every resident resource without invalidating external owners.
+         * @return number of unique meshes removed.
+         */
+        u32 Clear();
+
+        u32 GetResidentCount() const { return static_cast<u32>(m_residents.size()); }
+        MeshCacheStats GetStats() const;
+
+    private:
+        struct Resident
+        {
+            std::shared_ptr<Mesh> mesh;
+        };
+
+        void RemoveAliasesForContent(MeshAssetId contentId);
+
+        IGraphicsDevice* m_device = nullptr;
+        std::unordered_map<MeshAssetId, MeshAssetId, MeshAssetIdHash> m_assetToContent;
+        std::unordered_map<MeshAssetId, Resident, MeshAssetIdHash> m_residents;
+
+        u64 m_cacheHits = 0;
+        u64 m_cacheMisses = 0;
+        u64 m_meshesCreated = 0;
+        u64 m_creationFailures = 0;
+        u64 m_identifierConflicts = 0;
+        u64 m_evictions = 0;
+    };
+}