refactor: 宣言/実装の物理分離 (src/ → impl/)

.github/workflows/test.yml

@@ -12,12 +12,18 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Check clang-format
+      - name: Check clang-format (src)
         uses: jidicula/clang-format-action@v4.14.0
         with:
           clang-format-version: '21'
           check-path: 'src'
 
+      - name: Check clang-format (impl)
+        uses: jidicula/clang-format-action@v4.14.0
+        with:
+          clang-format-version: '21'
+          check-path: 'impl'
+
   test:
     runs-on: ubuntu-latest
     steps:

CHANGELOG.md

@@ -12,6 +12,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Changed
 
+- **宣言/実装の物理分離**
+  - `src/fleximg/` を宣言のみ（公開ヘッダ）、`impl/fleximg/` に実装（`.inl`）を配置
+  - `#ifdef FLEXIMG_IMPLEMENTATION` パターンを廃止し、`fleximg.cpp` が両方をインクルードする構成に変更
+  - Arduino ライブラリとして安全にインクルード可能に（実装の重複コンパイルを防止）
+  - `dda.h`, `format_converter.h` を削除（実装は `.inl` に移行）
+  - examples の `#define FLEXIMG_IMPLEMENTATION` を削除、`platformio.ini` で `fleximg.cpp` をビルド対象に追加
+
+- **common.h: デバッグディレイのプラットフォーム対応改善**
+  - `__has_include` による FreeRTOS 自動検出（ESP-IDF 直接利用にも対応）
+  - FreeRTOS なし Arduino 環境では `delay()` にフォールバック
+
 - **WebUI: C++同期型定義を `cpp-sync-types.js` に分離**
   - `NODE_TYPES`, `PIXEL_FORMATS`, `DEFAULT_PIXEL_FORMAT` 等のC++側と手動同期が必要な定義を `app.js` から `demo/web/cpp-sync-types.js` に分離
   - `buildFormatOptions()`, `NodeTypeHelper` も同ファイルに移動

CLAUDE.md

@@ -10,11 +10,16 @@
 ### 主要ディレクトリ
 
 ```
-src/fleximg/           # コアライブラリ
-├── nodes/             # ノード実装（Source, Composite, Filter等）
+src/fleximg/           # 公開ヘッダ（宣言のみ）
+├── nodes/             # ノード宣言
 ├── image/             # ImageBuffer, PixelFormat, ViewPort
-├── operations/        # blend, filters, transform
+├── operations/        # filters, transform
 └── core/memory/       # アロケータ、プール管理
+impl/fleximg/          # 実装ファイル（.inl、非公開）
+├── nodes/             # ノード実装
+├── image/             # PixelFormat, ViewPort 実装
+├── operations/        # filters 実装
+└── core/memory/       # メモリ管理実装
 examples/              # サンプルコード
 ├── bench/             # ベンチマーク（native/M5Stack両対応）
 ├── m5stack_basic/     # M5Stack基本サンプル

docs/ARCHITECTURE.md

@@ -393,66 +393,47 @@ namespace canvas_utils {
 
 ## ビルド方式
 
-### stb-style（Implementation Macro パターン）
+### 宣言/実装分離パターン
 
-fleximg は [stb ライブラリ](https://github.com/nothings/stb) と同様の実装マクロパターンを採用しています。
-これにより、コンパイル単位を最小化し、Arduino IDE などでのビルド時間を短縮します。
+fleximg は宣言（`.h`）と実装（`.inl`）を物理的に分離しています。
+`src/fleximg/` に公開ヘッダ（宣言のみ）、`impl/fleximg/` に実装ファイルを配置し、
+単一コンパイル単位 `fleximg.cpp` から両方をインクルードします。
 
-**使用方法:**
+この構造により：
+- Arduino IDE 等で `src/` 配下のヘッダを安全にインクルード可能
+- 実装の重複コンパイルを防止
+- コンパイル単位を最小化し、ビルド時間を短縮
+
+**使用方法（ユーザー側）:**
 
 ```cpp
-// 1つのソースファイルでのみ FLEXIMG_IMPLEMENTATION を定義
+// ヘッダのインクルードのみ（実装は fleximg.cpp に含まれる）
 #define FLEXIMG_NAMESPACE fleximg
-#define FLEXIMG_IMPLEMENTATION
-#include "fleximg/core/memory/platform.h"
-#include "fleximg/core/memory/pool_allocator.h"
 #include "fleximg/image/pixel_format.h"
-#include "fleximg/image/viewport.h"
-#include "fleximg/operations/filters.h"
-// ... 使用するヘッダをインクルード
-
-// 他のソースファイルでは FLEXIMG_IMPLEMENTATION を定義しない
-#define FLEXIMG_NAMESPACE fleximg
-#include "fleximg/image/pixel_format.h"  // 宣言のみ使用
+#include "fleximg/nodes/source_node.h"
+// ...
 ```
 
-**WASM/テストビルド:**
-`src/fleximg/fleximg.cpp` が唯一のコンパイル単位として全実装を含みます。
-
-**実装分離の方針:**
-
-各ヘッダファイルは以下の構造を持ちます：
+**コンパイル単位:**
+`src/fleximg/fleximg.cpp` が唯一のコンパイル単位として、宣言ヘッダと `.inl` 実装ファイルの両方をインクルードします。
 
 ```cpp
-#ifndef FLEXIMG_XXX_H
-#define FLEXIMG_XXX_H
-
-// クラス宣言（ヘッダ部）
-// - コンストラクタ、デストラクタ
-// - 短いアクセサ（1-2行）
-// - 短いpublicメソッド
-
-#ifdef FLEXIMG_IMPLEMENTATION
-// 実装部
-// - 仮想オーバーライドメソッド（vtable linkage問題の回避）
-// - privateヘルパーメソッド
-// - 複雑なロジック
-#endif
-
-#endif
+// 宣言ヘッダ（src/fleximg/ 内）
+#include "core/node.h"
+#include "image/pixel_format.h"
+// ...
+
+// 実装ファイル（impl/fleximg/ 内）
+#include "../../impl/fleximg/core/node.inl"
+#include "../../impl/fleximg/image/pixel_format.inl"
+// ...
 ```
 
-**実装を含むファイル一覧:**
-- `core/node.h`, `core/memory/platform.h`, `core/memory/pool_allocator.h`
-- `image/pixel_format.h`, `image/viewport.h`
-- `operations/filters.h`
-- 全ノードファイル（`nodes/*.h`）
-
 ## ファイル構成
 
 ```
-src/fleximg/
-├── fleximg.cpp               # メインコンパイル単位（stb-style）
+src/fleximg/                  # 公開ヘッダ（宣言のみ）
+├── fleximg.cpp               # メインコンパイル単位
 │
 ├── core/                     # コア機能（fleximg::core 名前空間）
 │   ├── common.h              # NAMESPACE定義、バージョン
@@ -471,19 +452,19 @@ src/fleximg/
 │
 ├── image/                    # 画像処理
 │   ├── pixel_format.h        # ピクセルフォーマット共通定義・ユーティリティ
-│   ├── pixel_format/         # 各フォーマットの個別実装
+│   ├── pixel_format/         # 各フォーマットの個別宣言
 │   │   ├── rgba8_straight.h  # RGBA8_Straight
 │   │   ├── alpha8.h          # Alpha8
 │   │   ├── rgb565.h          # RGB565_LE/BE + ルックアップテーブル + swap16
 │   │   ├── rgb332.h          # RGB332 + ルックアップテーブル
 │   │   ├── rgb888.h          # RGB888/BGR888 + swap24
-│   │   ├── grayscale8.h      # Grayscale8（BT.601輝度）
-│   │   └── index8.h          # Index8（パレットインデックス）
+│   │   ├── grayscale.h       # Grayscale（BT.601輝度）
+│   │   └── index.h           # Index（パレットインデックス）
 │   ├── viewport.h            # ViewPort
 │   ├── image_buffer.h        # ImageBuffer
 │   └── render_types.h        # RenderRequest, RenderResponse
 │
-├── nodes/
+├── nodes/                    # ノード宣言
 │   ├── source_node.h         # SourceNode
 │   ├── ninepatch_source_node.h # NinePatchSourceNode（9パッチ画像）
 │   ├── sink_node.h           # SinkNode
@@ -503,23 +484,51 @@ src/fleximg/
     ├── transform.h           # アフィン変換（DDA処理）
     ├── filters.h             # フィルタ処理
     └── canvas_utils.h        # キャンバス操作（合成ユーティリティ）
+
+impl/fleximg/                 # 実装ファイル（.inl、非公開）
+├── core/
+│   ├── node.inl
+│   └── memory/
+│       ├── platform.inl
+│       └── pool_allocator.inl
+├── image/
+│   ├── pixel_format.inl      # 集約ファイル（サブフォーマット .inl をインクルード）
+│   ├── pixel_format/
+│   │   ├── alpha8.inl
+│   │   ├── grayscale.inl
+│   │   ├── index.inl
+│   │   ├── rgb332.inl
+│   │   ├── rgb565.inl
+│   │   ├── rgb888.inl
+│   │   ├── rgba8_straight.inl
+│   │   ├── dda.inl
+│   │   └── format_converter.inl
+│   └── viewport.inl
+├── operations/
+│   └── filters.inl
+└── nodes/
+    ├── affine_node.inl
+    ├── composite_node.inl
+    ├── distributor_node.inl
+    ├── filter_node_base.inl
+    ├── horizontal_blur_node.inl
+    ├── matte_node.inl
+    ├── ninepatch_source_node.inl
+    ├── renderer_node.inl
+    ├── sink_node.inl
+    ├── source_node.inl
+    └── vertical_blur_node.inl
 ```
 
 ## 使用例
 
 ### 基本的なパイプライン
 
 ```cpp
-// stb-style: 実装を有効化
 #define FLEXIMG_NAMESPACE fleximg
-#define FLEXIMG_IMPLEMENTATION
-#include "fleximg/core/common.h"
-#include "fleximg/core/memory/platform.h"
-#include "fleximg/core/memory/pool_allocator.h"
 #include "fleximg/image/pixel_format.h"
 #include "fleximg/image/viewport.h"
 #include "fleximg/image/image_buffer.h"
-#include "fleximg/operations/filters.h"
 #include "fleximg/nodes/source_node.h"
 #include "fleximg/nodes/sink_node.h"
 #include "fleximg/nodes/affine_node.h"

examples/bench/src/main.cpp

@@ -46,10 +46,9 @@
 #include <string>
 #endif
 
-// fleximg (stb-style: define FLEXIMG_IMPLEMENTATION before including headers)
+// fleximg
 #define FLEXIMG_NAMESPACE fleximg
 #define FLEXIMG_DEBUG_MOVE_COUNT // ムーブ回数カウンタ有効化
-#define FLEXIMG_IMPLEMENTATION
 #include "fleximg/core/common.h"
 #include "fleximg/core/memory/allocator.h"
 #include "fleximg/core/memory/pool_allocator.h"

examples/m5stack_basic/src/main.cpp

@@ -4,22 +4,19 @@
 
 #include <M5Unified.h>
 
-// fleximg (stb-style: define FLEXIMG_IMPLEMENTATION before including headers)
+// fleximg
 #define FLEXIMG_NAMESPACE fleximg
-#define FLEXIMG_IMPLEMENTATION
 #include "fleximg/core/common.h"
 #include "fleximg/core/memory/platform.h"
+#include "fleximg/core/memory/pool_allocator.h"
 #include "fleximg/core/types.h"
 #include "fleximg/image/image_buffer.h"
+#include "fleximg/image/pixel_format.h"
 #include "fleximg/image/viewport.h"
 #include "fleximg/nodes/affine_node.h"
 #include "fleximg/nodes/composite_node.h"
 #include "fleximg/nodes/renderer_node.h"
 #include "fleximg/nodes/source_node.h"
-
-// stb 方式: FLEXIMG_IMPLEMENTATION 定義済みなのでヘッダから実装が有効化される
-#include "fleximg/core/memory/pool_allocator.h"
-#include "fleximg/image/pixel_format.h"
 #include "fleximg/operations/filters.h"
 
 // カスタムSinkNode

examples/m5stack_hos/src/main.cpp

@@ -5,22 +5,20 @@
 
 #include <M5Unified.h>
 
-// fleximg (stb-style: define FLEXIMG_IMPLEMENTATION before including headers)
+// fleximg
 #define FLEXIMG_NAMESPACE fleximg
-#define FLEXIMG_IMPLEMENTATION
 #include "fleximg/core/common.h"
 #include "fleximg/core/memory/platform.h"
+#include "fleximg/core/memory/pool_allocator.h"
 #include "fleximg/core/types.h"
 #include "fleximg/image/image_buffer.h"
+#include "fleximg/image/pixel_format.h"
 #include "fleximg/image/viewport.h"
 #include "fleximg/nodes/affine_node.h"
 #include "fleximg/nodes/composite_node.h"
 #include "fleximg/nodes/renderer_node.h"
 #include "fleximg/nodes/source_node.h"
 
-#include "fleximg/core/memory/pool_allocator.h"
-#include "fleximg/image/pixel_format.h"
-
 #include "lcd_sink_node.h"
 
 #include <algorithm>

examples/m5stack_matte/src/main.cpp

@@ -3,22 +3,19 @@
 
 #include <M5Unified.h>
 
-// fleximg (stb-style: define FLEXIMG_IMPLEMENTATION before including headers)
+// fleximg
 #define FLEXIMG_NAMESPACE fleximg
-#define FLEXIMG_IMPLEMENTATION
 #include "fleximg/core/common.h"
 #include "fleximg/core/memory/platform.h"
+#include "fleximg/core/memory/pool_allocator.h"
 #include "fleximg/core/types.h"
 #include "fleximg/image/image_buffer.h"
+#include "fleximg/image/pixel_format.h"
 #include "fleximg/image/viewport.h"
 #include "fleximg/nodes/affine_node.h"
 #include "fleximg/nodes/matte_node.h"
 #include "fleximg/nodes/renderer_node.h"
 #include "fleximg/nodes/source_node.h"
-
-// stb 方式: FLEXIMG_IMPLEMENTATION 定義済みなのでヘッダから実装が有効化される
-#include "fleximg/core/memory/pool_allocator.h"
-#include "fleximg/image/pixel_format.h"
 #include "fleximg/operations/filters.h"
 
 // カスタムSinkNode

impl/fleximg/core/memory/platform.inl

@@ -0,0 +1,42 @@
+/**
+ * @file platform.inl
+ * @brief プラットフォーム固有のメモリ確保 実装
+ * @see src/fleximg/core/memory/platform.h
+ */
+
+#include "../../../../src/fleximg/core/memory/allocator.h"
+
+namespace FLEXIMG_NAMESPACE {
+namespace core {
+namespace memory {
+
+// グローバルプラットフォームメモリインスタンス
+static IPlatformMemory *s_platformMemory = nullptr;
+
+IPlatformMemory &getPlatformMemory()
+{
+    if (!s_platformMemory) {
+        s_platformMemory = &DefaultPlatformMemory::instance();
+    }
+    return *s_platformMemory;
+}
+
+void setPlatformMemory(IPlatformMemory *platformMemory)
+{
+    s_platformMemory = platformMemory;
+}
+
+// DefaultPlatformMemory の実装
+void *DefaultPlatformMemory::allocate(size_t size, const AllocateOptions &options)
+{
+    return DefaultAllocator::instance().allocate(size, options.alignment);
+}
+
+void DefaultPlatformMemory::deallocate(void *ptr)
+{
+    DefaultAllocator::instance().deallocate(ptr);
+}
+
+}  // namespace memory
+}  // namespace core
+}  // namespace FLEXIMG_NAMESPACE