统一 2D 渲染链路以消除格式分叉和热路径中转

将图片主路径收口为 RGBA5551 输入、RGB565 backbuffer 输出，并删除 USE_RGB565_BACKBUFFER 双路径。sprite/tilemap 主绘制改为直接 RGBA5551 -> RGB565，透明语义固定为 1-bit alpha test。同步收口 SDL/FB present 路径、sprite 资源加载/导出规范，以及相关测试与文档。 Constraint: 运行时图片主路径需统一到 RGBA5551，不能继续保留主要 RGBA8888 分支 Constraint: 透明仅支持 1-bit 语义，不引入 alpha blending Rejected: 保留 USE_RGB565_BACKBUFFER 宏双路径 | 持续增加维护成本并掩盖真实主链路 Rejected: 主绘制继续走 RGBA5551 -> RGBA8888 -> RGB565 | 热路径存在不必要中转 Confidence: high Scope-risk: moderate Directive: 后续图片资源默认按 RGBA5551 接入；不要重新引入通用 RGBA8888 主运行时路径 Directive: 字体 atlas 目前仍属兼容输入；若继续收口，优先改成 1-bit mask 而不是新的图片分支 Tested: render_pipeline_tests；SDL Demo Release 构建；搜索确认无 USE_RGB565_BACKBUFFER 残留 Not-tested: Linux framebuffer 目标实机构建与显示验证
2026-06-08 18:32:04 +08:00
parent 8785368913
commit 5ac61dca0e
19 changed files with 167075 additions and 166993 deletions
@@ -0,0 +1,118 @@
+#include "Display.h"
+#include "DrawContext.h"
+#include "FrameBuffer.h"
+#include "Image.h"
+#include "SpriteAssetLoader.h"
+
+#include <cassert>
+#include <cstdio>
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace
+{
+	class CaptureDisplay : public Platform::IDisplay
+	{
+	public:
+		const Core::FrameBuffer* framebuffer;
+
+		CaptureDisplay()
+			: framebuffer(nullptr)
+		{
+		}
+
+		bool init(int, int) override { return true; }
+		void present(const Core::FrameBuffer* fb) override { framebuffer = fb; }
+		void poll_events(bool&) override {}
+		void shutdown() override {}
+	};
+
+	void TestFramePixelIsRgb565()
+	{
+		static_assert(sizeof(Core::FramePixel) == sizeof(uint16_t), "FramePixel must stay RGB565");
+		assert(RenderData::rgba5551_to_rgb565(0xF801u) == 0xF800u);
+		assert(RenderData::rgba5551_to_rgb565(0x07C1u) == 0x07E0u);
+		assert(RenderData::rgba5551_to_rgb565(0x003Fu) == 0x001Fu);
+	}
+
+	void TestFrameBufferStoresRgb565()
+	{
+		Core::FrameBuffer framebuffer(2, 1);
+		framebuffer.clear(RenderData::Color(255, 0, 0, 255));
+
+		const Core::FramePixel* pixels = static_cast<const Core::FramePixel*>(framebuffer.get_buffer());
+		assert(pixels[0] == 0xF800u);
+		assert(pixels[1] == 0xF800u);
+	}
+
+	void TestDrawSpriteUsesOneBitAlpha()
+	{
+		const uint16_t sprite_pixels[] = {
+			0xF800u,
+			0x07C1u
+		};
+
+		Core::DrawContext ctx(2, 1);
+		ctx.clear_color(RenderData::Color(0, 0, 255, 255));
+
+		RenderData::Image sprite(
+			sprite_pixels,
+			2,
+			1,
+			RenderData::PixelFormat::RGBA5551);
+		ctx.draw_sprite(0, 0, sprite);
+
+		CaptureDisplay display;
+		ctx.present(&display);
+		assert(display.framebuffer != nullptr);
+
+		const Core::FramePixel* pixels =
+			static_cast<const Core::FramePixel*>(display.framebuffer->get_buffer());
+		assert(pixels[0] == 0x001Fu);
+		assert(pixels[1] == 0x07E0u);
+	}
+
+	void TestSpriteAssetLoaderRoundTripsRgba5551()
+	{
+		const std::string path = "render_pipeline_test.sprite";
+		const uint16_t original_pixels[] = {
+			0x0000u,
+			0xF801u,
+			0x07C1u,
+			0x003Fu
+		};
+
+		RenderData::Image original(
+			original_pixels,
+			2,
+			2,
+			RenderData::PixelFormat::RGBA5551);
+		assert(Asset::SpriteAssetLoader::Save(path, original));
+
+		std::vector<uint16_t> loaded_pixels;
+		RenderData::Image loaded;
+		const bool loaded_ok = Asset::SpriteAssetLoader::Load(path, loaded_pixels, loaded);
+		std::remove(path.c_str());
+
+		assert(loaded_ok);
+		assert(loaded.format == RenderData::PixelFormat::RGBA5551);
+		assert(loaded.width == 2);
+		assert(loaded.height == 2);
+		assert(loaded_pixels.size() == 4u);
+		for (size_t i = 0; i < loaded_pixels.size(); ++i)
+		{
+			assert(loaded_pixels[i] == original_pixels[i]);
+		}
+	}
+}
+
+int main()
+{
+	TestFramePixelIsRgb565();
+	TestFrameBufferStoresRgb565();
+	TestDrawSpriteUsesOneBitAlpha();
+	TestSpriteAssetLoaderRoundTripsRgba5551();
+	std::cout << "render_pipeline_tests: PASS\n";
+	return 0;
+}