重构平台条件编译,剥离 LightGame 调试内容到 Debug 配置

- 把 USE_FRAMEBUFFER 替换为 TARGET_IMX / TARGET_PC 双正向互斥宏,由 CMake 选项 TARGET_IMX 推导,代码层只用 #ifdef 正向判断
- 新增 IMX6U_DEBUG 宏,通过 $<$<CONFIG:Debug>:...> 只在 Debug 构建中注入
- LightGame 关卡编辑器(LevelEditor + ImGui)改为仅 PC + Debug 编入,Release 不参与编译
- LightGame draw_debug、debug_mode_、--debug 命令行、[INFO] 启动日志全部用 IMX6U_DEBUG 门控,Release 二进制中完全消失
- [WARN] 硬件初始化失败提示保留在 Release,作为现场诊断信息
- README、APP_AND_CORE_ARCHITECTURE、Game README 同步新宏命名,并新增「构建类型与调试开关」小节
This commit is contained in:
SepComet 2026-06-16 13:46:12 +08:00
parent 334c9ee96f
commit 10872fde82
14 changed files with 139 additions and 55 deletions

View File

@ -9,7 +9,12 @@ if(NOT CMAKE_CONFIGURATION_TYPES AND NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
endif()
option(USE_FRAMEBUFFER "Use Linux framebuffer instead of SDL2" OFF)
option(TARGET_IMX "Build for IMX6U target board (framebuffer + Alsa + Evdev). OFF builds for PC (SDL2)." OFF)
if(TARGET_IMX)
set(TARGET_PC OFF)
else()
set(TARGET_PC ON)
endif()
set(CORE_SOURCES
src/Core/Asset/ObjLoader.cpp
@ -29,7 +34,7 @@ set(CORE_SOURCES
src/Core/Shading/BlinnPhongShader.cpp
)
if(USE_FRAMEBUFFER)
if(TARGET_IMX)
list(APPEND CORE_SOURCES
src/Core/Platform/FBDisplay.cpp
src/Core/Platform/Ap3216cPhotoSensor.cpp
@ -60,7 +65,7 @@ set(CORE_INCLUDE_DIRS
assets/sprite
)
if(NOT USE_FRAMEBUFFER)
if(NOT TARGET_IMX)
list(APPEND CORE_SOURCES
third_party/imgui/imgui.cpp
third_party/imgui/imgui_demo.cpp
@ -76,11 +81,15 @@ endif()
add_library(imx6u_core STATIC ${CORE_SOURCES})
target_include_directories(imx6u_core PUBLIC ${CORE_INCLUDE_DIRS})
if(USE_FRAMEBUFFER)
target_compile_definitions(imx6u_core PUBLIC USE_FRAMEBUFFER)
if(TARGET_IMX)
target_compile_definitions(imx6u_core PUBLIC TARGET_IMX)
else()
target_compile_definitions(imx6u_core PUBLIC TARGET_PC)
endif()
if(USE_FRAMEBUFFER)
target_compile_definitions(imx6u_core PUBLIC $<$<CONFIG:Debug>:IMX6U_DEBUG>)
if(TARGET_IMX)
else()
if(WIN32)
if(CMAKE_SIZEOF_VOID_P EQUAL 8)
@ -136,7 +145,7 @@ function(imx6u_configure_app_target target_name)
)
endif()
if(WIN32 AND NOT USE_FRAMEBUFFER)
if(WIN32 AND NOT TARGET_IMX)
add_custom_command(TARGET ${target_name} POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_if_different
"${SDL2_DLL}"
@ -154,7 +163,7 @@ add_subdirectory(src/Apps/Game)
add_subdirectory(src/Apps/Demo)
add_subdirectory(src/Apps/LightGame)
if(BUILD_TESTING AND NOT USE_FRAMEBUFFER)
if(BUILD_TESTING AND NOT TARGET_IMX)
add_executable(render_pipeline_tests
tests/render_pipeline_tests.cpp
)

View File

@ -51,6 +51,26 @@ IMX6U 运行时性能预算较紧,后续开发必须遵守 `docs/DEVELOPMENT_G
cd IMX6U-Game
```
### 构建类型与调试开关
项目有两根独立的条件编译轴,组合出常用的构建形态:
| 轴 | CMake 参数 | 编译宏 | 默认 |
|---|---|---|---|
| 平台软件栈 | `-DTARGET_IMX=ON/OFF` | `TARGET_IMX``TARGET_PC`(互斥、双正向) | `OFF``TARGET_PC` |
| 构建类型 | `-DCMAKE_BUILD_TYPE=Debug/Release` | `IMX6U_DEBUG`(仅 Debug 配置注入) | `Release` |
`IMX6U_DEBUG` 控制开发期辅助内容是否参与构建。当前 LightGame 中下列内容只在 Debug 构建中存在Release 构建会被完全剔除(不参与编译,不进入二进制):
- 关卡编辑器(`LevelEditor` + ImGui`F1` 切换)
- 碰撞框可视化(`LevelRenderer::draw_debug` 与 `LightGameApp::debug_mode_`
- `--debug` 命令行开关
- `[INFO] LightGame started …` 启动日志
硬件初始化失败的 `[WARN]` 提示无论 Debug/Release 都保留,作为现场诊断信息。
> 多配置生成器Visual Studio`CMAKE_BUILD_TYPE` 在 configure 阶段被忽略,应在构建阶段用 `--config Debug|Release` 选择单配置生成器Makefile/Ninja使用 `-DCMAKE_BUILD_TYPE=...` 在 configure 阶段决定。
### WindowsVisual Studio / MSVC
仓库已自带 SDL2 开发库(`libs/Win/SDL2`),无需额外安装。
@ -67,6 +87,13 @@ cmake --build build-win --config Release --target IMX6U-Game
cmake --build build-win --config Release --target IMX6U-Demo
```
启用 LightGame 关卡编辑器和调试显示,使用 Debug 构建:
```bash
cmake --build build-win --config Debug --target IMX6U-LightGame
./build-win/Debug/IMX6U-LightGame.exe
```
构建 `IMX6U-Game` 时会自动重新生成 Tom 的 atlas 头文件;也可以单独执行:
```bash
@ -136,12 +163,18 @@ sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
- **SDL2 后端**目标是后续游戏主路径SDL2 负责显示、输入和最终 framebuffer 提交,时间源使用独立的 `Platform::ITimeSource`
- **Framebuffer 后端**:作为极简依赖和显示通路对照测试。
> CMake 选项 `TARGET_IMX` 控制的不是"是否交叉编译",而是"使用哪一套软件栈"
> - `TARGET_IMX=ON` —— framebuffer (`/dev/fb0`) + Alsa 音频 + evdev 输入 + AP3216C 光敏,对应 IMX6U 板载硬件。
> - `TARGET_IMX=OFF` —— SDL2 显示/音频/输入/光敏PC 调试和 ARM-SDL 对照路径共用这一栈。
>
> 因此 ARM 交叉编译 + SDL2 后端使用 `-DTARGET_IMX=OFF`,与"运行在 PC"无关。
构建Framebuffer 对照后端):
```bash
cmake -B build-arm-fb \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
-DUSE_FRAMEBUFFER=ON .
-DTARGET_IMX=ON .
cmake --build build-arm-fb
```
@ -154,7 +187,7 @@ cmake --build build-arm-fb
```bash
cmake -B build-arm-sdl \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
-DUSE_FRAMEBUFFER=OFF .
-DTARGET_IMX=OFF .
cmake --build build-arm-sdl
```
@ -281,7 +314,7 @@ assets/font/font_atlas.h
└──────────────────────────────────────────────┘
```
切换显示后端不应影响应用层和核心绘制逻辑;当前 CMake 通过 `USE_FRAMEBUFFER` 在 SDL2 与 framebuffer 后端间切换
切换显示后端不应影响应用层和核心绘制逻辑;当前 CMake 通过 `TARGET_IMX` 在 framebuffer (IMX6U) 与 SDL2 (PC) 后端间切换,对应代码层的 `TARGET_IMX` / `TARGET_PC` 双正向宏
## 目录结构

View File

@ -219,8 +219,8 @@ ALSA、evdev、SDL2、`/dev/fb0` 等平台细节只能出现在 `src/Core/Platfo
### 5.7 CMake 后端切换
```cmake
-DUSE_FRAMEBUFFER=OFF # 默认,使用 SDLDisplay
-DUSE_FRAMEBUFFER=ON # 使用 FBDisplay
-DTARGET_IMX=OFF # 默认 (PC),使用 SDLDisplay
-DTARGET_IMX=ON # IMX6U 板,使用 FBDisplay
```
## 6. DrawContext

View File

@ -15,9 +15,10 @@
#include "font_atlas.h"
#include "test_sprite.h"
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
#include "FBDisplay.h"
#else
#endif
#ifdef TARGET_PC
#include "SDLDisplay.h"
#endif
@ -47,9 +48,10 @@ namespace
static Platform::IDisplay* CreateDisplay()
{
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
return new Platform::FBDisplay();
#else
#endif
#ifdef TARGET_PC
return new Platform::SDLDisplay();
#endif
}

View File

@ -3,7 +3,7 @@ set(TOM_ATLAS_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/generated/tom_atlas.h")
set_source_files_properties(${TOM_ATLAS_HEADER} PROPERTIES GENERATED TRUE)
set(TOM_GAME_ENABLE_TFLITE_C_API_DEFAULT OFF)
if(CMAKE_CROSSCOMPILING AND USE_FRAMEBUFFER)
if(CMAKE_CROSSCOMPILING AND TARGET_IMX)
set(TOM_GAME_ENABLE_TFLITE_C_API_DEFAULT ON)
endif()
@ -109,7 +109,7 @@ if(CMAKE_CROSSCOMPILING AND NOT EXISTS "${TOM_ATLAS_HEADER}")
)
endif()
if(NOT USE_FRAMEBUFFER)
if(NOT TARGET_IMX)
set(TOM_ATLAS_TOOL_SOURCES
tools/asset_pipeline/SpriteAssetTool.cpp
)

View File

@ -20,9 +20,10 @@
#include "recognition/TinyKwsRecognizer.h"
#endif
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
#include "FBDisplay.h"
#else
#endif
#ifdef TARGET_PC
#include "SDLDisplay.h"
#endif
@ -49,9 +50,10 @@ namespace
static Platform::IDisplay* CreateDisplay()
{
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
return new Platform::FBDisplay();
#else
#endif
#ifdef TARGET_PC
return new Platform::SDLDisplay();
#endif
}

View File

@ -10,7 +10,7 @@
- Windows C++ 构建默认不启用 TFLite C API避免在 Windows 上编译/链接
TensorFlow C++。
- ARM framebuffer 交叉编译时默认启用 TFLite C API
`CMAKE_CROSSCOMPILING && USE_FRAMEBUFFER` 时
`CMAKE_CROSSCOMPILING && TARGET_IMX` 时
`TOM_GAME_ENABLE_TFLITE_C_API=ON`
- 仓库里的 `runtime/lib/tensorflow/lite/c/libtensorflowlite_c.so` 是 ELF32 ARM
hard-float 动态库,方向上匹配 IMX6ULL 常见的 `arm-linux-gnueabihf`
@ -98,7 +98,7 @@ python src\Apps\Game\tools\kws_python_test.py --wav tmp\kws_test.wav
```bash
cmake -B build-arm-fb \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
-DUSE_FRAMEBUFFER=ON \
-DTARGET_IMX=ON \
-DTOM_GAME_ENABLE_TFLITE_C_API=ON \
-DTOM_GAME_TFLITE_INCLUDE_DIR=/path/to/tensorflow-source-root \
-DTOM_GAME_TFLITE_LIBRARY=$PWD/src/Apps/Game/runtime/lib/tensorflow/lite/c/libtensorflowlite_c.so \
@ -112,7 +112,7 @@ cmake --build build-arm-fb --target IMX6U-Game
```bash
cmake -B build-arm-fb-no-kws \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
-DUSE_FRAMEBUFFER=ON \
-DTARGET_IMX=ON \
-DTOM_GAME_ENABLE_TFLITE_C_API=OFF \
.

View File

@ -12,13 +12,18 @@ set(LIGHTGAME_SOURCES
src/main.cpp
)
if(NOT USE_FRAMEBUFFER)
list(APPEND LIGHTGAME_SOURCES src/editor/LevelEditor.cpp)
endif()
add_executable(IMX6U-LightGame ${LIGHTGAME_SOURCES})
target_include_directories(IMX6U-LightGame PRIVATE src/engine src/systems src/levels generated)
if(NOT USE_FRAMEBUFFER)
target_include_directories(IMX6U-LightGame PRIVATE src/editor)
endif()
# PC + Debug
# - TARGET_IMX=OFF ( TARGET_PC) SDL/ImGui
# - $<CONFIG:Debug> /
set(LIGHTGAME_EDITOR_GUARD "$<AND:$<NOT:$<BOOL:${TARGET_IMX}>>,$<CONFIG:Debug>>")
target_sources(IMX6U-LightGame PRIVATE
"$<${LIGHTGAME_EDITOR_GUARD}:${CMAKE_CURRENT_SOURCE_DIR}/src/editor/LevelEditor.cpp>"
)
target_include_directories(IMX6U-LightGame PRIVATE
"$<${LIGHTGAME_EDITOR_GUARD}:${CMAKE_CURRENT_SOURCE_DIR}/src/editor>"
)
imx6u_configure_app_target(IMX6U-LightGame)

View File

@ -90,6 +90,7 @@ namespace LightGame
}
}
#ifdef IMX6U_DEBUG
void LevelRenderer::draw_debug(Core::DrawContext& ctx, const Level& level,
const Camera2D& camera, const RenderData::BitmapFont& font)
{
@ -119,4 +120,5 @@ namespace LightGame
ctx.draw_line(Math::Vector2Int(sx, sy + h), Math::Vector2Int(sx, sy), color);
}
}
#endif
}

View File

@ -25,7 +25,9 @@ namespace LightGame
const LightEffectSystem& light_system, uint16_t light_level,
bool draw_background = true);
#ifdef IMX6U_DEBUG
void draw_debug(Core::DrawContext& ctx, const Level& level, const Camera2D& camera,
const RenderData::BitmapFont& font);
#endif
};
}

View File

@ -43,7 +43,9 @@ namespace LightGame
light_step_(256),
smoothed_light_q8_(2048 << 8),
has_manual_override_(false),
#ifdef IMX6U_DEBUG
debug_mode_(false),
#endif
death_processed_(false)
{
camera_.configure(screen_width, screen_height - LevelRenderer::kTopBlackBorder);
@ -136,14 +138,17 @@ namespace LightGame
const uint16_t light = manual_light_level_;
renderer_.draw(ctx, level_, camera_, light_system_, light);
#ifdef IMX6U_DEBUG
if (debug_mode_)
{
renderer_.draw_debug(ctx, level_, camera_, font);
}
#endif
}
state_manager_.draw(ctx, font, screen_width_, screen_height_);
#ifdef IMX6U_DEBUG
if (debug_mode_ && state_manager_.get_state() == GameState::Playing)
{
const uint16_t light = manual_light_level_;
@ -152,6 +157,7 @@ namespace LightGame
ctx.draw_text(font, screen_width_ - 64, screen_height_ - 16,
RenderData::Color(128, 128, 128, 255), buf);
}
#endif
}
bool LightGameApp::is_action_pressed()

View File

@ -40,7 +40,6 @@ namespace LightGame
Platform::IKeyboardState* keyboard_input_;
Platform::IPointerInput* pointer_input_;
Platform::IPhotoSensor* photo_sensor_;
// TODO: consolidate input interfaces into IInputState when a 4th modality arrives
Level level_;
Camera2D camera_;
@ -65,7 +64,9 @@ namespace LightGame
int32_t smoothed_light_q8_;
bool has_manual_override_;
#ifdef IMX6U_DEBUG
bool debug_mode_;
#endif
bool death_processed_;
public:
@ -81,7 +82,9 @@ namespace LightGame
void draw(Core::DrawContext& ctx, const RenderData::BitmapFont& font);
GameState get_state() const { return state_manager_.get_state(); }
#ifdef IMX6U_DEBUG
void set_debug_mode(bool enabled) { debug_mode_ = enabled; }
#endif
private:
void load_room(int32_t room_index);

View File

@ -1,9 +1,11 @@
#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <iostream>
#include <thread>
#ifdef IMX6U_DEBUG
#include <cstring>
#endif
#include "DefaultHardware.h"
#include "Display.h"
@ -15,10 +17,13 @@
#include "font_atlas.h"
#include "LevelTotalData.h"
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
#include "FBDisplay.h"
#else
#endif
#ifdef TARGET_PC
#include "SDLDisplay.h"
#endif
#ifdef IMX6U_DEBUG
#include "LevelEditor.h"
#include "imgui.h"
#include "backends/imgui_impl_sdl2.h"
@ -32,9 +37,10 @@ namespace
static Platform::IDisplay* CreateDisplay()
{
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
return new Platform::FBDisplay();
#else
#endif
#ifdef TARGET_PC
return new Platform::SDLDisplay();
#endif
}
@ -97,10 +103,12 @@ int main(int argc, char* argv[])
&pointerInput,
&photoSensor);
#ifndef USE_FRAMEBUFFER
#ifdef TARGET_PC
Platform::SDLDisplay* sdl_display = static_cast<Platform::SDLDisplay*>(display);
#endif
#ifdef IMX6U_DEBUG
LightGame::LevelEditor editor(ScreenWidth, ScreenHeight);
Platform::SDLDisplay* sdl_display = static_cast<Platform::SDLDisplay*>(display);
IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGui::StyleColorsDark();
@ -108,6 +116,7 @@ int main(int argc, char* argv[])
ImGui_ImplSDLRenderer2_Init(sdl_display->get_renderer());
#endif
#ifdef IMX6U_DEBUG
bool debug_mode = false;
for (int i = 1; i < argc; ++i)
{
@ -119,6 +128,10 @@ int main(int argc, char* argv[])
app.set_debug_mode(debug_mode);
std::cout << "[INFO] LightGame started. Target FPS: " << timer.target_fps() << std::endl;
#else
(void)argc;
(void)argv;
#endif
bool is_running = true;
while (is_running)
@ -127,13 +140,16 @@ int main(int argc, char* argv[])
bool should_quit = false;
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
display->poll_events(should_quit);
#else
#endif
#ifdef TARGET_PC
SDL_Event event;
while (SDL_PollEvent(&event))
{
#ifdef IMX6U_DEBUG
ImGui_ImplSDL2_ProcessEvent(&event);
#endif
if (event.type == SDL_QUIT)
{
should_quit = true;
@ -142,10 +158,12 @@ int main(int argc, char* argv[])
{
should_quit = true;
}
#ifdef IMX6U_DEBUG
if (event.type == SDL_KEYDOWN && event.key.keysym.sym == SDLK_F1)
{
editor.set_active(!editor.is_active());
}
#endif
}
#endif
if (should_quit)
@ -156,7 +174,7 @@ int main(int argc, char* argv[])
buttonInput.update();
pointerInput.update();
#ifndef USE_FRAMEBUFFER
#ifdef IMX6U_DEBUG
if (editor.is_active())
{
if (editor.get_pending_load() >= 0)
@ -169,23 +187,22 @@ int main(int argc, char* argv[])
editor.draw(ctx, font);
}
else
#endif
{
app.update(timer.fixed_delta_ms());
app.draw(ctx, font);
}
#else
app.update(timer.fixed_delta_ms());
app.draw(ctx, font);
#endif
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
ctx.present(display);
#else
#endif
#ifdef TARGET_PC
const Core::FrameBuffer* fb = ctx.get_frame_buffer();
SDL_UpdateTexture(sdl_display->get_texture(), nullptr, fb->get_buffer(), ScreenWidth * 2);
SDL_RenderClear(sdl_display->get_renderer());
SDL_RenderCopy(sdl_display->get_renderer(), sdl_display->get_texture(), nullptr, nullptr);
#ifdef IMX6U_DEBUG
ImGui_ImplSDLRenderer2_NewFrame();
ImGui_ImplSDL2_NewFrame();
ImGui::NewFrame();
@ -195,6 +212,7 @@ int main(int argc, char* argv[])
}
ImGui::Render();
ImGui_ImplSDLRenderer2_RenderDrawData(ImGui::GetDrawData(), sdl_display->get_renderer());
#endif
SDL_RenderPresent(sdl_display->get_renderer());
#endif
SleepRemainingFrameTime(timer, time_source);
@ -204,7 +222,7 @@ int main(int argc, char* argv[])
pointerInput.shutdown();
buttonInput.shutdown();
#ifndef USE_FRAMEBUFFER
#ifdef IMX6U_DEBUG
ImGui_ImplSDLRenderer2_Shutdown();
ImGui_ImplSDL2_Shutdown();
ImGui::DestroyContext();

View File

@ -1,13 +1,14 @@
#pragma once
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
#include "AlsaAudioInput.h"
#include "AlsaAudioOutput.h"
#include "EvdevButtonInput.h"
#include "EvdevKeyboardState.h"
#include "EvdevTouchInput.h"
#include "Ap3216cPhotoSensor.h"
#else
#endif
#ifdef TARGET_PC
#include "SdlAudioInput.h"
#include "SdlAudioOutput.h"
#include "SdlKeyboardButtonInput.h"
@ -18,14 +19,15 @@
namespace Platform
{
#ifdef USE_FRAMEBUFFER
#ifdef TARGET_IMX
typedef AlsaAudioInput DefaultAudioInput;
typedef AlsaAudioOutput DefaultAudioOutput;
typedef EvdevButtonInput DefaultButtonInput;
typedef EvdevKeyboardState DefaultKeyboardState;
typedef EvdevTouchInput DefaultPointerInput;
typedef Ap3216cPhotoSensor DefaultPhotoSensor;
#else
#endif
#ifdef TARGET_PC
typedef SdlAudioInput DefaultAudioInput;
typedef SdlAudioOutput DefaultAudioOutput;
typedef SdlKeyboardButtonInput DefaultButtonInput;