♻️ refactor asset image_parser -> image_codec; add gfx copy/blit commands and geometry math

- Rename image_parser to image_codec with expanded codec interface

- Add copy texture region and blit commands across gfx backends (DX12, Vulkan, mock)

- Add geometry.cppm with ray, plane, frustum, AABB, and intersection tests

- Consolidate gfx tests (desc_hash_test -> gfx_test) and asset tests (parser_test -> codec_test)

- Rename CLAUDE.md to AGENT.md

Made-with: Cursor

Author: L-Sun

.cursor/.gitignore

@@ -0,0 +1 @@
+plans/

.cursor/skills/commit/skill.md

@@ -0,0 +1,61 @@
+---
+description: Using git to commit current changes
+match:
+  - commit
+  - git commit
+---
+
+Using git to commit current changes with the Commit Rule following these steps, and as fast as possible without any explanations.
+
+# Steps
+
+1. According to the staged changes existing or not,
+   - If there are staged changes, read the staged changes using `git --no-pager diff --cached`
+   - If there are not staged changes, read the changes in the current branch using `git --no-pager diff`
+2. According to the changes content, the changes may be committed with one or more commits.
+3. For each commit, generate a commit message using the Commit Rule.
+4. Commit the changes with the generated commit message.
+
+# Commit Rule
+
+Follow the commit message format: `<gitmoji> <scope?> <message>`
+
+## Format Structure
+
+- **gitmoji**: A required gitmoji indicating the type of change
+- **scope**: Optional module/area name (e.g., `gfx:`, `asset:`, `render_graph:`)
+- **message**: Descriptive commit message in present tense
+
+## Gitmoji Reference
+
+| Gitmoji | Code            | Description                        |
+| ------- | --------------- | ---------------------------------- |
+| ✨      | `:sparkles:`    | New feature                        |
+| 🐛      | `:bug:`         | Bug fix                            |
+| ♻️      | `:recycle:`     | Refactor / restructure code        |
+| ⚡      | `:zap:`         | Performance improvement            |
+| ⬆️      | `:arrow_up:`    | Upgrade dependencies               |
+| 💚      | `:green_heart:` | Fix CI/build                       |
+| ✏️      | `:pencil2:`     | Fix typo                           |
+| 🔧      | `:wrench:`      | Configuration changes              |
+| 📝      | `:memo:`        | Documentation                      |
+| 🎨      | `:art:`         | Improve structure / format of code |
+| 🔥      | `:fire:`        | Remove code or files               |
+| 🏗️      | `:building_construction:` | Architectural changes    |
+
+## Examples
+
+- `✨ simple material viewer`
+- `🐛 fix uninitialized RT/DS on D3D12MA heaps with CREATE_NOT_ZEROED`
+- `♻️ modernize gfx: Vulkan submit2, std::ranges, scoped_lock; fix DX12 barriers`
+- `⬆️ update sdl2 to sdl3`
+- `♻️ refactor ecs interface`
+- `⚡ use GPU Upload Heap (DX12) and VK_EXT_host_image_copy (Vulkan) for resource init`
+
+## Rules
+
+1. Always start with an appropriate gitmoji
+2. Optionally include a scope prefix (e.g., `gfx:`, `asset:`) when the change affects a specific module
+3. Keep the message concise but descriptive
+4. Use present tense ("Add feature" not "Added feature")
+5. Lowercase the message (except proper nouns like API names, DX12, Vulkan, etc.)

CLAUDE.md AGENT.mdCLAUDE.md renamed to AGENT.md

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENT.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding agents when working with code in this repository.
 
 ## Build System
 
@@ -116,7 +116,7 @@ Following the layered architecture from *Game Engine Architecture* (Jason Gregor
 
 **`hitagi/asset`** — `AssetManager` for loading scenes, meshes, materials, textures. Assimp for model import; custom parsers for PNG, JPEG, BMP, TGA. Materials are defined with named instances (e.g., `"Phong"`).
 
-**`hitagi/render`** — `IRenderer` interface; `ForwardRenderer` is the concrete implementation. The renderer owns the swapchain and render graph instance.
+**`hitagi/render`** — `IRenderer` interface with two concrete implementations: `ForwardRenderer` (single-pass Phong shading) and `DeferredRenderer` (G-Buffer MRT pass + fullscreen lighting pass). Both renderers own the swapchain and render graph instance. The engine defaults to `ForwardRenderer`; switch via `Engine::SetRenderer()`.
 
 **`hitagi/engine`** — Top-level `Engine` class that composes everything. Initialized from `hitagi.json` at the project root. Usage pattern: construct `Engine`, call `engine.Tick()` in the game loop.
 

hitagi/asset/asset.cppm

@@ -12,7 +12,7 @@ export import :meta_info;
 export import :transform;
 export import :scene;
 export import :mesh_factory;
-export import :image_parser;
+export import :image_codec;
 export import :scene_parser;
 export import :material_parser;
 export import :asset_manager;

hitagi/asset/asset_manager.cpp

@@ -19,13 +19,15 @@ AssetManager::AssetManager(std::filesystem::path asset_base_path)
 
     m_MaterialParser = std::make_shared<MaterialJSONParser>();
 
-    m_ImageParsers[ImageFormat::PNG]  = std::make_shared<PngParser>(m_Logger);
-    m_ImageParsers[ImageFormat::JPEG] = std::make_shared<JpegParser>(m_Logger);
-    m_ImageParsers[ImageFormat::TGA]  = std::make_shared<TgaParser>(m_Logger);
-    m_ImageParsers[ImageFormat::BMP]  = std::make_shared<BmpParser>(m_Logger);
+    m_ImageDecoders[ImageFormat::PNG]  = std::make_shared<PngDecoder>(m_Logger);
+    m_ImageDecoders[ImageFormat::JPEG] = std::make_shared<JpegDecoder>(m_Logger);
+    m_ImageDecoders[ImageFormat::TGA]  = std::make_shared<TgaDecoder>(m_Logger);
+    m_ImageDecoders[ImageFormat::BMP]  = std::make_shared<BmpDecoder>(m_Logger);
+
+    m_ImageEncoders[ImageFormat::PNG] = std::make_shared<PngEncoder>(m_Logger);
 
     m_SceneParsers[SceneFormat::UNKOWN] = std::make_shared<AssimpParser>(
-        m_ImageParsers,
+        m_ImageDecoders,
         [this](auto name) { return GetMaterial(name); },
         m_Logger);
     m_SceneParsers[SceneFormat::GLTF]  = m_SceneParsers[SceneFormat::UNKOWN];
@@ -49,7 +51,7 @@ std::shared_ptr<Scene> AssetManager::ImportScene(const std::filesystem::path& pa
 
 std::shared_ptr<Texture> AssetManager::ImportTexture(const std::filesystem::path& path) {
     auto format = get_image_format(path.extension().string());
-    auto image  = m_ImageParsers[format]->Parse(path);
+    auto image  = m_ImageDecoders[format]->Decode(path);
     AddTexture(image);
     return image;
 }

hitagi/asset/asset_manager.cppm

@@ -12,7 +12,7 @@ import :camera;
 import :light;
 import :skeleton;
 import :scene;
-import :image_parser;
+import :image_codec;
 import :scene_parser;
 import :material_parser;
 import core;
@@ -50,7 +50,8 @@ private:
 
     // Parser
     std::shared_ptr<MaterialParser>                             m_MaterialParser;
-    utils::EnumArray<std::shared_ptr<ImageParser>, ImageFormat> m_ImageParsers;
+    utils::EnumArray<std::shared_ptr<ImageDecoder>, ImageFormat> m_ImageDecoders;
+    utils::EnumArray<std::shared_ptr<ImageEncoder>, ImageFormat> m_ImageEncoders;
     utils::EnumArray<std::shared_ptr<SceneParser>, SceneFormat> m_SceneParsers;
 
     struct Assets {

hitagi/asset/assimp.cpp

@@ -227,14 +227,14 @@ auto AssimpParser::Parse(const std::filesystem::path& path, const std::filesyste
             logger->trace("texture path: {}", _texture->mFilename.C_Str());
             const auto compressed_buffer = core::Buffer(_texture->mWidth, reinterpret_cast<const std::byte*>(_texture->pcData));
 
-            if (_texture->CheckFormat("jpg") && m_ImageParsers[ImageFormat::JPEG]) {
-                texture = m_ImageParsers[ImageFormat::JPEG]->Parse(compressed_buffer);
-            } else if (_texture->CheckFormat("png") && m_ImageParsers[ImageFormat::PNG]) {
-                texture = m_ImageParsers[ImageFormat::PNG]->Parse(compressed_buffer);
-            } else if (_texture->CheckFormat("bmp") && m_ImageParsers[ImageFormat::BMP]) {
-                texture = m_ImageParsers[ImageFormat::BMP]->Parse(compressed_buffer);
-            } else if (_texture->CheckFormat("tga") && m_ImageParsers[ImageFormat::TGA]) {
-                texture = m_ImageParsers[ImageFormat::TGA]->Parse(compressed_buffer);
+            if (_texture->CheckFormat("jpg") && m_ImageDecoders[ImageFormat::JPEG]) {
+                texture = m_ImageDecoders[ImageFormat::JPEG]->Decode(compressed_buffer);
+            } else if (_texture->CheckFormat("png") && m_ImageDecoders[ImageFormat::PNG]) {
+                texture = m_ImageDecoders[ImageFormat::PNG]->Decode(compressed_buffer);
+            } else if (_texture->CheckFormat("bmp") && m_ImageDecoders[ImageFormat::BMP]) {
+                texture = m_ImageDecoders[ImageFormat::BMP]->Decode(compressed_buffer);
+            } else if (_texture->CheckFormat("tga") && m_ImageDecoders[ImageFormat::TGA]) {
+                texture = m_ImageDecoders[ImageFormat::TGA]->Decode(compressed_buffer);
             } else {
                 logger->warn("Unsupported texture format: {}", _texture->achFormatHint);
             }

hitagi/asset/bmp.cpp

@@ -33,7 +33,7 @@ using BITMAP_HEADER = struct BitmapHeader {
 };
 #pragma pack(pop)
 
-std::shared_ptr<Texture> BmpParser::Parse(const core::Buffer& buffer) {
+std::shared_ptr<Texture> BmpDecoder::Decode(const core::Buffer& buffer) {
     auto logger = m_Logger ? m_Logger : spdlog::default_logger();
     if (buffer.Empty()) {
         logger->warn("[BMP] Parsing a empty buffer will return nullptr");

hitagi/asset/image_codec.cpp

@@ -0,0 +1,24 @@
+module;
+
+module asset;
+import :image_codec;
+import std;
+
+namespace hitagi::asset {
+auto ImageDecoder::Decode(const std::filesystem::path& path) -> std::shared_ptr<Texture> {
+    if (core::FileIOManager::Get())
+        return Decode(core::FileIOManager::Get()->SyncOpenAndReadBinary(path));
+    else
+        return nullptr;
+}
+
+auto ImageEncoder::Encode(const Texture& texture, const std::filesystem::path& path) -> bool {
+    auto buffer = Encode(texture);
+    if (buffer.Empty()) return false;
+    if (core::FileIOManager::Get()) {
+        core::FileIOManager::Get()->SaveBuffer(buffer, path);
+        return true;
+    }
+    return false;
+}
+}  // namespace hitagi::asset

hitagi/asset/image_codec.cppm

@@ -0,0 +1,91 @@
+module;
+
+#include <spdlog/logger.h>
+
+export module asset:image_codec;
+import std;
+import :texture;
+import core;
+
+export namespace hitagi::asset {
+
+enum struct ImageFormat : std::uint8_t {
+    UNKOWN,
+    PNG,
+    JPEG,
+    TGA,
+    BMP,
+};
+
+inline constexpr ImageFormat get_image_format(std::string_view ext) noexcept {
+    if (ext == ".jpeg" || ext == ".jpg")
+        return ImageFormat::JPEG;
+    else if (ext == ".bmp")
+        return ImageFormat::BMP;
+    else if (ext == ".tga")
+        return ImageFormat::TGA;
+    else if (ext == ".png")
+        return ImageFormat::PNG;
+    return ImageFormat::UNKOWN;
+}
+
+class ImageDecoder {
+public:
+    ImageDecoder(std::shared_ptr<spdlog::logger> logger = nullptr) : m_Logger(std::move(logger)) {}
+
+    virtual auto Decode(const std::filesystem::path& path) -> std::shared_ptr<Texture>;
+    virtual auto Decode(const core::Buffer& buffer) -> std::shared_ptr<Texture> = 0;
+    virtual ~ImageDecoder()                                                     = default;
+
+protected:
+    std::shared_ptr<spdlog::logger> m_Logger;
+};
+
+class ImageEncoder {
+public:
+    ImageEncoder(std::shared_ptr<spdlog::logger> logger = nullptr) : m_Logger(std::move(logger)) {}
+
+    virtual auto Encode(const Texture& texture, const std::filesystem::path& path) -> bool;
+    virtual auto Encode(const Texture& texture) -> core::Buffer = 0;
+    virtual ~ImageEncoder()                                     = default;
+
+protected:
+    std::shared_ptr<spdlog::logger> m_Logger;
+};
+
+class PngDecoder : public ImageDecoder {
+public:
+    using ImageDecoder::ImageDecoder;
+    using ImageDecoder::Decode;
+    auto Decode(const core::Buffer& buffer) -> std::shared_ptr<Texture> final;
+};
+
+class PngEncoder : public ImageEncoder {
+public:
+    using ImageEncoder::ImageEncoder;
+    using ImageEncoder::Encode;
+    auto Encode(const Texture& texture) -> core::Buffer final;
+};
+
+class JpegDecoder : public ImageDecoder {
+public:
+    using ImageDecoder::ImageDecoder;
+    using ImageDecoder::Decode;
+    auto Decode(const core::Buffer& buffer) -> std::shared_ptr<Texture> final;
+};
+
+class BmpDecoder : public ImageDecoder {
+public:
+    using ImageDecoder::ImageDecoder;
+    using ImageDecoder::Decode;
+    auto Decode(const core::Buffer& buffer) -> std::shared_ptr<Texture> final;
+};
+
+class TgaDecoder : public ImageDecoder {
+public:
+    using ImageDecoder::ImageDecoder;
+    using ImageDecoder::Decode;
+    auto Decode(const core::Buffer& buffer) -> std::shared_ptr<Texture> final;
+};
+
+}  // namespace hitagi::asset