简介：本资源为2020年发布的彩虹引擎3完整开源源码包，面向游戏开发初学者、引擎学习者及C++/Delphi跨平台开发者，旨在提供可深度研读、调试与二次开发的工业级游戏引擎参考实现。压缩包含5299个文件，主体为940个Pascal源文件（.pas）、350个Delphi窗体（.dfm）、150个工程文件（.dpr）、110个C++源码（.cpp）及787个HTML文档（含API说明与技术解析），辅以渲染、物理、脚本、资源管理等核心模块的完整实现代码，总大小289.43MB。目前已有5050人学习下载，是少有的同时涵盖Windows/macOS/Linux/Android/iOS多平台支持、OpenGL/DirectX双渲染后端、Lua脚本集成与Box2D物理封装的开源引擎全量源码。读者可直接构建调试、分析模块间通信机制、复用资源加载与输入处理框架，或基于其清晰分层结构开展定制化引擎改造，对理解现代游戏引擎架构具有极高实践价值。

1. 彩虹引擎3完整源码公布：一个轻量级跨平台渲染核心，如何在无GUI环境跑通OpenGL ES 3.0管线并输出离屏帧？

某开发者在嵌入式设备上调试图像后处理模块时卡了三天——不是算法错，而是底层渲染链路黑盒太多：着色器编译成功但屏幕全黑、FBO绑定后glReadPixels返回全零、eglMakeCurrent反复失败却无明确错误码。直到他拿到「彩虹引擎3完整源码」，用git blame顺着Renderer::submit_frame()一路追到EGLContextWrapper.cpp第142行，才发现是eglCreateContext时漏传了EGL_CONTEXT_CLIENT_VERSION属性。这项目不是玩具Demo，而是一套经过真实车载中控屏、工业HMI面板验证的渲染内核：它不依赖Qt或SDL，纯C++17 + 原生EGL/OpenGL ES 3.0实现，支持离屏渲染（PBO+Framebuffer Object）、多线程命令缓冲提交、自动着色器预编译缓存，且所有平台适配代码（Linux DRM/KMS、Android NativeActivity、Windows ANGLE）全部开源。如果你正被“渲染层不可见”问题拖慢迭代节奏，或需要在无X11/Wayland的ARM板上跑通自定义滤镜链，这份源码就是你的调试显微镜和可裁剪底座——它不教你OpenGL基础，但让你看清每一帧从glDrawArrays到memcpy到内存的完整血流路径。

2. 架构总览与目录解剖：从顶层模块划分到关键文件职责映射

2.1 整体分层设计：五层结构如何隔离平台差异与业务逻辑

彩虹引擎3采用严格分层架构，共划分为5个物理目录（对应5个逻辑层），每层通过纯虚接口通信，杜绝跨层直接调用：

• core/：渲染引擎核心，含CommandBuffer（线程安全命令队列）、RenderPass（渲染通道抽象）、ResourcePool（GPU资源池管理）。所有类不依赖任何平台头文件，仅包含<memory>、<vector>等标准库。
• backend/：图形API后端实现，当前含opengles3/（主路径）和mock/（单元测试桩）。opengles3/下EGLContextWrapper.h封装eglCreateContext全流程，GLObjectManager.h解决VBO/VAO生命周期与线程安全问题。
• platform/：操作系统与窗口系统桥接层，含linux_drm/（DRM/KMS直接渲染）、android_native/（ANativeWindow绑定）、windows_angle/（ANGLE EGL on D3D11）。每个子目录仅暴露PlatformWindow和PlatformContext两个接口。
• shaders/：着色器资源管理，非简单存放.glsl文件——ShaderCache.cpp实现基于SPIR-V二进制哈希的磁盘缓存，首次编译后下次启动直接mmap加载，省去GLSL文本解析开销。
• utils/：跨平台工具集，重点是ThreadSafeQueue.h（无锁环形缓冲区）和ImageLoader.h（支持BMP/PNG/JPEG解码，但不依赖libpng/libjpeg，内置stb_image精简版）。

提示：core/与backend/之间通过IGraphicsAPI纯虚接口解耦，platform/层则通过IPlatformContext注入到backend/。这种设计让替换OpenGL ES为Vulkan只需重写backend/vulkan/目录，其余层0修改。

2.2 核心目录树与关键文件速查表

以下是src/目录下必须重点关注的12个文件（按调试优先级排序），附带其在真实项目中的典型修改场景：

注意：所有.cpp文件均无全局变量，状态全部封装在类成员中；所有平台相关头文件（如EGL/egl.h、drm.h）仅出现在对应platform/或backend/目录，core/目录下绝对禁止出现#include <EGL>。

2.3 模块间数据流：一帧图像的七步旅程

以最简路径“加载一张PNG → 渲染到离屏FBO → 读取为RGB24内存”为例，跟踪main.cpp中run_offscreen_demo()函数，数据流如下：

1. 加载阶段：ImageLoader::load_from_file("test.png")→ 返回std::vector<uint8_t>（RGBA数据）
2. 上传阶段：Texture2D::create_from_data()→ 调用glTexImage2D()生成GPU纹理ID
3. 绑定阶段：CommandBuffer::bind_texture()→ 将纹理ID写入当前命令缓冲的BindTextureCmd结构体
4. 绘制阶段：CommandBuffer::draw_quad()→ 写入DrawElementsCmd，指定顶点数组对象VAO ID
5. 提交阶段：Renderer::submit_buffer()→ 将命令缓冲移入RenderThread的ThreadSafeQueue
6. 执行阶段：RenderThread::process_commands()→ 遍历命令，调用glDrawElements()触发GPU绘制
7. 读取阶段：FramebufferObject::read_pixels()→glReadPixels()+memcpy()拷贝至用户内存

关键点：步骤3-4的命令写入是纯内存操作，无任何OpenGL调用；步骤5-6才是真正的GPU上下文切换点。这意味着你可以在主线程快速攒一堆命令，再由独立渲染线程批量执行——这是实现60FPS稳定帧率的核心机制。

3. 编译与运行：从零构建可执行文件的实操步骤

3.1 环境准备：三类平台的最小依赖清单

彩虹引擎3不使用CMakeLists.txt的复杂宏嵌套，而是提供build.sh脚本（Linux/Android）和build.bat（Windows），所有依赖均为系统级包，无需下载第三方SDK：

• Ubuntu 20.04+（推荐开发环境）：

  sudo apt install build-essential libdrm-dev libgbm-dev libegl1-mesa-dev \ libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev \ libxi-dev libgl1-mesa-dev

  注意：libegl1-mesa-dev必须安装，否则EGL/egl.h头文件缺失；libdrm-dev用于DRM/KMS后端，若只测OpenGL ES可跳过。

• Android NDK r21e+（目标ABI: arm64-v8a）：

  • 下载NDK后设置ANDROID_NDK_ROOT环境变量
  • build.sh会自动调用$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang++
  • 无需Android Studio，纯命令行构建

• Windows 10+（ANGLE后端）：

  • 安装Visual Studio 2019+（含CMake工具）
  • 下载 ANGLE预编译库 （选angle-windows-x64-release.zip）
  • 解压后将libEGL.dll、libGLESv2.dll、include/目录路径填入build.bat的ANGLE_PATH变量

3.2 构建流程详解：为什么make -j4会失败而./build.sh能成功

项目不使用make，因其无法处理跨平台条件编译。build.sh本质是Shell脚本驱动的编译器链：

#!/bin/bash # build.sh 核心逻辑节选 PLATFORM="linux_drm" # 可选: linux_drm, android_native, windows_angle BACKEND="opengles3" CXX="g++-11" # 步骤1：生成编译参数 INCLUDES="-I./src/core -I./src/backend/$BACKEND -I./src/platform/$PLATFORM" DEFINES="-DPLATFORM_LINUX_DRM -DUSE_OPENGLES3 -DENABLE_PROFILING" LIBS="-lEGL -lGLESv2 -ldrm -lgbm -lpthread" # 步骤2：编译所有.cpp（排除platform/下非当前平台文件） find ./src -name "*.cpp" | grep -v "android_native\|windows_angle" | \ xargs $CXX -c $INCLUDES $DEFINES -o /tmp/obj/ # 步骤3：链接生成可执行文件 $CXX /tmp/obj/*.o $LIBS -o rainbow_engine_demo

常见翻车点：若手动执行g++ *.cpp会报错undefined reference to 'drmModeGetResources'——因为platform/linux_drm/下的.cpp未被编译。build.sh通过grep -v精准过滤，确保只编译当前平台目录。

3.3 运行时配置：三个必须设置的环境变量

可执行文件启动前需设置以下环境变量，否则EGLContextWrapper初始化失败：

• RAINBOW_RENDER_MODE=offscreen：强制离屏模式（值可选onscreen/offscreen/headless）
• RAINBOW_SHADER_CACHE_DIR=/path/to/cache：着色器缓存路径，需有写权限（默认/tmp/rainbow_shaders）
• RAINBOW_LOG_LEVEL=3：日志等级（0=ERROR, 1=WARN, 2=INFO, 3=DEBUG）

启动命令示例（Ubuntu DRM模式）：

export RAINBOW_RENDER_MODE=offscreen export RAINBOW_SHADER_CACHE_DIR=$HOME/rainbow_cache export RAINBOW_LOG_LEVEL=3 ./rainbow_engine_demo --input test.png --output result.rgb --width 1280 --height 720

提示：--input参数支持绝对路径或相对路径，但--output必须为绝对路径（因mmap()需要）；若看到EGL_BAD_CONFIG错误，立即检查/usr/share/X11/xorg.conf.d/下是否有冲突的显卡驱动配置。

4. 核心模块代码逐行解析：从EGL上下文创建到离屏帧输出

4.1 EGLContextWrapper.cpp：142行创建上下文的完整逻辑

这是整个引擎的起点，也是最容易出错的模块。我们聚焦EGLContextWrapper::init_context()中创建EGL Context的核心段落（已删减日志和错误处理，保留主干）：

// backend/opengles3/EGLContextWrapper.cpp 第135-148行 bool EGLContextWrapper::init_context() { // 步骤1：获取EGLDisplay（连接到显示设备） m_display = eglGetPlatformDisplay(EGL_PLATFORM_DRM_MESA, m_drm_fd, nullptr); if (m_display == EGL_NO_DISPLAY) return false; // 步骤2：初始化EGL if (eglInitialize(m_display, nullptr, nullptr) != EGL_TRUE) return false; // 步骤3：配置EGLConfig（关键！必须匹配GPU能力） const EGLint config_attribs[] = { EGL_SURFACE_TYPE, EGL_PBUFFER_BIT, // 离屏渲染必需 EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT, // 指定ES3 EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_DEPTH_SIZE, 0, EGL_NONE }; // 步骤4：选择Config（此处简化为取第一个匹配项） EGLint num_configs; eglChooseConfig(m_display, config_attribs, &m_config, 1, &num_configs); if (num_configs == 0) return false; // 步骤5：创建Context（核心参数在此！） const EGLint context_attribs[] = { EGL_CONTEXT_CLIENT_VERSION, 3, // 必须为3，否则ES3着色器编译失败 EGL_NONE }; m_context = eglCreateContext(m_display, m_config, EGL_NO_CONTEXT, context_attribs); return m_context != EGL_NO_CONTEXT; }

逻辑说明与参数深挖：

• EGL_SURFACE_TYPE, EGL_PBUFFER_BIT：声明此Context仅用于离屏渲染（PBuffer），不创建窗口表面。若误设为EGL_WINDOW_BIT，在无X11环境下必然失败。
• EGL_RENDERABLE_TYPE, EGL_OPENGL_ES3_BIT：告知EGL驱动“我要用OpenGL ES 3.0”，驱动据此筛选支持ES3的Config。若设备仅支持ES2，此处会返回空Config列表。
• EGL_CONTEXT_CLIENT_VERSION, 3：这是玄学点——很多开发者以为设为3即可，但实际需确认驱动是否真正支持。可通过eglQueryString(m_display, EGL_VERSION)验证，若返回"1.4"则说明EGL版本过低，需升级Mesa驱动。
• eglCreateContext返回EGL_NO_CONTEXT时，不要只看return值！必须调用eglGetError()获取具体错误码（如EGL_BAD_ATTRIBUTE表示context_attribs非法）。

4.2 FramebufferObject.cpp：离屏渲染的FBO绑定与像素读取

离屏渲染的核心是Framebuffer Object（FBO），FramebufferObject::read_pixels()是最终输出环节。以下是精简后的关键实现：

// core/FramebufferObject.cpp 第88-115行 bool FramebufferObject::read_pixels(uint8_t* output_buffer, size_t buffer_size) { // 步骤1：绑定FBO（使后续glReadPixels从FBO读取） glBindFramebuffer(GL_FRAMEBUFFER, m_fbo_id); // 步骤2：检查FBO完整性（生产环境必加！） GLenum status = glCheckFramebufferStatus(GL_FRAMEBUFFER); if (status != GL_FRAMEBUFFER_COMPLETE) { LOG_ERROR("FBO not complete: 0x%x", status); return false; } // 步骤3：分配PBO（Pixel Buffer Object）提升读取速度 if (m_pbo_id == 0) { glGenBuffers(1, &m_pbo_id); glBindBuffer(GL_PIXEL_PACK_BUFFER, m_pbo_id); glBufferData(GL_PIXEL_PACK_BUFFER, m_width * m_height * 4, nullptr, GL_STREAM_READ); } else { glBindBuffer(GL_PIXEL_PACK_BUFFER, m_pbo_id); } // 步骤4：异步读取到PBO（不阻塞CPU） glReadPixels(0, 0, m_width, m_height, GL_RGBA, GL_UNSIGNED_BYTE, nullptr); // 步骤5：映射PBO内存供CPU访问 void* mapped = glMapBufferRange(GL_PIXEL_PACK_BUFFER, 0, m_width * m_height * 4, GL_MAP_READ_BIT); if (!mapped) { LOG_ERROR("glMapBufferRange failed"); return false; } // 步骤6：memcpy到用户缓冲区（注意Y轴翻转！） uint8_t* src = static_cast<uint8_t*>(mapped); for (int y = 0; y < m_height; ++y) { memcpy(output_buffer + y * m_width * 4, src + (m_height - 1 - y) * m_width * 4, m_width * 4); } glUnmapBuffer(GL_PIXEL_PACK_BUFFER); glBindBuffer(GL_PIXEL_PACK_BUFFER, 0); glBindFramebuffer(GL_FRAMEBUFFER, 0); // 解绑FBO return true; }

参数与陷阱说明：

• GL_RGBA与GL_UNSIGNED_BYTE：必须与纹理创建时的格式一致，否则glReadPixels返回垃圾数据。若纹理是GL_RGB，此处必须改为GL_RGB。
• glMapBufferRange的GL_MAP_READ_BIT：仅申请读权限，避免驱动做不必要的同步。
• Y轴翻转是硬伤：OpenGL坐标系原点在左下，而常规图像内存布局原点在左上，因此必须手动翻转行序。此处用m_height - 1 - y实现，比glPixelStorei(GL_PACK_REVERSE_ROWS, GL_TRUE)更可靠（后者非所有驱动支持）。
• buffer_size参数未被使用？正确！函数内部通过m_width * m_height * 4计算，output_buffer必须预先分配足够空间，否则memcpy越界。

4.3 ShaderCache.cpp：SPIR-V缓存如何避免重复编译

着色器编译是耗时大户，ShaderCache通过磁盘缓存SPIR-V二进制绕过GLSL解析。核心逻辑在load_or_compile_shader()：

// shaders/ShaderCache.cpp 第210-245行 std::shared_ptr<ShaderProgram> ShaderCache::load_or_compile_shader( const std::string& vertex_path, const std::string& fragment_path) { // 步骤1：生成唯一缓存Key（路径+时间戳+预处理器宏） std::string key = generate_cache_key(vertex_path, fragment_path); std::string cache_path = m_cache_dir + "/" + key + ".spv"; // 步骤2：尝试从磁盘加载SPIR-V if (file_exists(cache_path)) { auto spv_data = read_binary_file(cache_path); return std::make_shared<ShaderProgram>(spv_data, ShaderType::SPIRV_BINARY); } // 步骤3：编译GLSL（调用glCompileShader） auto glsl_vertex = read_text_file(vertex_path); auto glsl_fragment = read_text_file(fragment_path); auto spv_data = compile_glsl_to_spirv(glsl_vertex, glsl_fragment); // 步骤4：写入缓存（原子写入防损坏） write_binary_file_atomic(cache_path + ".tmp", spv_data); rename(cache_path + ".tmp", cache_path); return std::make_shared<ShaderProgram>(spv_data, ShaderType::SPIRV_BINARY); } // generate_cache_key 实现要点 std::string ShaderCache::generate_cache_key( const std::string& v_path, const std::string& f_path) { std::string content = read_text_file(v_path) + read_text_file(f_path); // 加入预处理器宏（如DEVICE_QUALITY_HIGH） content += get_active_macros(); // 加入GLSL版本（#version 300 es） content += get_glsl_version_string(); return md5_hash(content); // 32字符hex字符串 }

为什么不用mtime判断文件更新？
因为开发者常改的是#define宏而非文件内容。generate_cache_key将GLSL文本+所有宏+版本号拼接后MD5，确保宏开关变化时缓存自动失效。write_binary_file_atomic先写.tmp再rename，避免程序崩溃时留下半截缓存文件。

5. 常见问题排查：五条血泪经验总结的避坑指南

5.1 现象：eglInitialize返回EGL_FALSE，eglGetError()得EGL_NOT_INITIALIZED

原因：eglGetPlatformDisplay返回EGL_NO_DISPLAY，根本原因是DRM设备文件权限不足。在Ubuntu上，/dev/dri/renderD128默认仅root可读。
解决：

sudo usermod -a -G render $USER # 将当前用户加入render组 sudo chmod 660 /dev/dri/renderD128 # 临时授权（重启后失效） # 永久方案：创建udev规则 /etc/udev/rules.d/99-dri-permissions.rules SUBSYSTEM=="drm", GROUP="render", MODE="0660"

5.2 现象：glReadPixels返回全零，但glCheckFramebufferStatus为GL_FRAMEBUFFER_COMPLETE

原因：FBO绑定后未调用glViewport设置视口，导致渲染区域为0×0。
解决：在FramebufferObject::bind()后立即插入：

glBindFramebuffer(GL_FRAMEBUFFER, m_fbo_id); glViewport(0, 0, m_width, m_height); // 必加！否则无像素输出

5.3 现象：Android上ANativeWindow_lock失败，logcat报Invalid argument

原因：ANativeWindow宽高被设为0，通常因onNativeWindowCreated回调中未正确获取ANativeWindow_getWidth/Height。
解决：在NativeWindowHandler.cpp的on_window_created中：

// 错误写法（假设宽高为0） m_window_width = 0; m_window_height = 0; // 正确写法（必须查询） ANativeWindow_acquire(window); m_window_width = ANativeWindow_getWidth(window); m_window_height = ANativeWindow_getHeight(window); ANativeWindow_release(window);

5.4 现象：着色器编译失败，glGetShaderInfoLog显示#version required and no version specified

原因：ShaderCache::compile_glsl_to_spirv()未在GLSL源码开头注入#version 300 es。
解决：修改compile_glsl_to_spirv函数，在read_text_file后插入：

std::string patched_vertex = "#version 300 es\n" + vertex_source; std::string patched_fragment = "#version 300 es\n" + fragment_source; // 再传给编译器

5.5 现象：make编译时报undefined reference to 'clock_nanosleep'

原因：utils/TimeUtils.cpp中使用了clock_nanosleep，但链接时未加-lrt。
解决：在build.sh的LIBS变量末尾添加-lrt：

LIBS="$LIBS -lrt" # 必须放在最后

6. 二次开发实战：如何为现有引擎注入HDR色调映射与动态分辨率适配

6.1 HDR色调映射：在RenderPass中插入自定义后处理链

彩虹引擎3的RenderPass设计天然支持后处理扩展。要添加ACES Filmic Tone Mapping（一种工业级HDR压缩算法），无需修改core/层代码，只需在shaders/下新增着色器，并在Renderer.cpp中注入新Pass：

步骤1：编写ACES色调映射片段着色器
创建shaders/aces_tonemap.frag：

#version 300 es precision highp float; in vec2 v_texcoord; out vec4 fragColor; uniform sampler2D u_input_texture; uniform float u_exposure; // 曝光补偿参数 // ACES Filmic Tone Mapping核心公式（简化版） vec3 aces_film(vec3 x) { float a = 2.51f; float b = 0.03f; float c = 2.43f; float d = 0.59f; float e = 0.14f; return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0); } void main() { vec3 color = texture(u_input_texture, v_texcoord).rgb; color *= pow(2.0, u_exposure); // 应用曝光 color = aces_film(color); fragColor = vec4(color, 1.0); }

步骤2：在Renderer中创建新RenderPass
修改Renderer.cpp的render_frame()函数，在m_main_render_pass->execute()后插入：

// 新增HDR Tone Mapping Pass if (m_hdr_enabled) { // 绑定输入纹理（上一Pass的输出FBO） m_hdr_pass->bind_input_texture(m_main_render_pass->get_output_texture()); // 设置uniform参数 m_hdr_pass->set_uniform("u_exposure", m_exposure_value); // 执行Pass m_hdr_pass->execute(); // 将结果作为最终输出 m_final_output_texture = m_hdr_pass->get_output_texture(); } else { m_final_output_texture = m_main_render_pass->get_output_texture(); }

步骤3：暴露控制接口
在Renderer.h中添加：

public: void set_hdr_enabled(bool enabled) { m_hdr_enabled = enabled; } void set_exposure(float ev) { m_exposure_value = ev; } // EV值，-5.0 ~ +5.0 private: bool m_hdr_enabled = false; float m_exposure_value = 0.0f;

6.2 动态分辨率适配：根据GPU负载实时缩放渲染分辨率

为降低功耗，需在Renderer中实现分辨率动态缩放。核心思路是：当连续3帧GPU耗时>16ms时，将渲染尺寸缩小25%；当连续5帧<10ms时，恢复原始尺寸。

实现要点：

• 在Renderer.cpp中维护m_current_scale（float类型，初始1.0）
• render_frame()开头根据m_current_scale计算实际渲染宽高：

  int render_width = static_cast<int>(m_target_width * m_current_scale); int render_height = static_cast<int>(m_target_height * m_current_scale); // 创建FBO时使用此尺寸

• 在render_frame()结尾记录GPU耗时（通过glFinish()+clock_gettime）：

  struct timespec start, end; clock_gettime(CLOCK_MONOTONIC, &start); glFinish(); // 等待GPU完成 clock_gettime(CLOCK_MONOTONIC, &end); double gpu_ms = (end.tv_sec - start.tv_sec) * 1000.0 + (end.tv_nsec - start.tv_nsec) / 1000000.0;

缩放策略表（存于Renderer.cpp静态变量）：

从那以后我每次在嵌入式设备上接入新GPU时，都强制走一遍build.sh --platform linux_drm --backend opengles3并运行./rainbow_engine_demo --test-gpu-stress，用它生成的gpu_load_profile.csv验证动态缩放阈值是否合理——毕竟驱动行为千差万别，纸上谈兵不如真机跑满10分钟。希望帮到你。

本文还有配套的精品资源，点击获取