# GenerateGL 与 StgSharp.Graphics OpenGL 绑定架构评估 评估日期：2026-08-24 ## 1. 评估目的 本文评估 `StgSharp.GenerateGL` 与 `src/StgSharp.Graphics` 当前 OpenGL 绑定代码之间的关系，重点回答以下问题： - GenerateGL 为什么会生成大量保留 C 命名风格的方法； - Uniform 系列应如何生成符合 C# 使用习惯的方法重载； - 现有手写封装散落在哪些文件中； - 修改生成器时还需要同步调整哪些类型、加载器和调用方； - 如何在保留现有功能的前提下逐步完成迁移。 本次评估基于静态代码检查，不包含代码重构或 API 变更。 ## 2. 总体结论 当前 GenerateGL 完成的是“将 Khronos OpenGL C API 转换为可调用的 C# 代码”，尚未建立从 C API 函数族到惯用 C# API 的语义映射。 `glUniform1f`、`glUniform2f`、`glUniform4fv` 等名称中的数字和后缀分别编码了分量数、元素类型和指针形式。当前生成器只删除 `gl` 前缀，因此得到的仍然是 C 风格方法，而不是 C# 重载。 解决该问题不能只修改方法命名。当前 OpenGL 代码同时存在以下结构性问题： 1. 原始函数指针、自动生成的薄封装和手写高级封装没有清晰分层； 2. `Uniform.cs` 同时定义 Uniform 类型和 `partial OpenGLFunction` 方法； 3. `ShaderStruct.cs` 绕过 `OpenGLFunction`，直接调用原始函数指针； 4. uniform location 被建模为通用 `GlHandle`，语义不正确； 5. Context、ContextShadow、Loader 和 Wrapper 分别维护，已经出现函数清单漂移； 6. OpenGL 版本能力判断存在错误，可能加载当前上下文不支持的函数； 7. GenerateGL 文档描述的是增量源生成器，但当前实现是独立控制台代码生成程序。 建议将架构拆分为四个明确层次： 1. Registry 模型层：解析 `gl.xml` 并建立函数、版本和类型模型； 2. ABI 层：生成原始函数指针和加载代码； 3. Raw API 层：提供与 OpenGL 一一对应的薄封装； 4. Idiomatic API 层：按函数族生成 C# 重载，并使用 StgSharp 的向量、矩阵和资源类型。 ## 3. 当前 GenerateGL 行为 ### 3.1 输入 GenerateGL 从 `xml/gl.xml` 读取 Khronos OpenGL Registry。 当前解析内容包括： - `` 中的函数名、返回值和参数； - `` 中各 OpenGL 版本新增的命令； - Core Profile 中删除的命令。 当前未完整实现： - 枚举和常量生成； - 扩展 API 生成； - Roslyn Incremental Generator； - 自动写入或接入 `StgSharp.Graphics` 项目。 ### 3.2 输出 当前生成器针对 OpenGL 3.3 至 4.6 生成： - 分版本 `OpenglContext` 函数指针字段； - 分版本 `OpenGLFunction` 薄封装方法； - 合并后的 `glContext.cs`； - OpenGL 命令新增和删除历史。 输出目录为 GenerateGL 可执行文件所在目录下的 `Generated`，而不是 `src/StgSharp.Graphics`。 ### 3.3 当前生成策略的限制 生成器对公开方法的处理主要包括： - 删除 `gl` 前缀； - 将部分 `GLuint` 参数启发式转换为 `GlHandle`； - 将部分 `const T*` 转换为 `ReadOnlySpan`； - 对 C# 保留字进行转义。 它没有分析 OpenGL 函数族，因此下列函数会被当作互不相关的方法： ```text glUniform1f glUniform2f glUniform3f glUniform4f glUniform1fv glUniform2fv glUniform3fv glUniform4fv ``` ## 4. StgSharp.Graphics 当前代码分布 ### 4.1 原始函数指针 `src/StgSharp.Graphics/OpenGL/glContext.cs` 定义 `OpenglContext`，当前包含 657 个函数指针字段。 这些字段是 OpenGL ABI 的核心，应完全由生成器维护，不应与手写高级 API 混合。 ### 4.2 ContextShadow `src/StgSharp.Graphics/OpenGL/glContextShadow.cs` 使用 657 个 `IntPtr` 字段镜像 `OpenglContext`。 加载器将 `OpenglContext*` 强制转换为 `glContextShadow*` 后写入函数地址。因此两个结构体必须始终满足： - 字段数量一致； - 字段顺序一致； - 每个字段占用相同大小。 当前两者字段数量和顺序一致，但这种设计非常脆弱。生成器目前不生成 ContextShadow，任何一侧发生变化都可能破坏内存布局。 ### 4.3 函数加载器 `src/StgSharp.Graphics/OpenGL/glApiManager.Load.cs` 按 OpenGL 版本加载函数。 静态检查结果： - `OpenglContext` 字段数：657； - `glContextShadow` 字段数：657； - 实际 Loader 赋值数：655。 当前未被实际加载的字段： - `glGetPointerv`； - `glVertexAttribLFormat`。 这说明 Context、Shadow 和 Loader 已经发生漂移。 ### 4.4 自动生成的公开薄封装 以下文件定义 `partial OpenGLFunction`： - `glFunction.v3_3.cs`； - `glFunction.v4_0.cs`； - `glFunction.v4_1.cs`； - `glFunction.v4_2.cs`； - `glFunction.v4_3.cs`； - `glFunction.v4_4.cs`； - `glFunction.v4_5.cs`； - `glFunction.v4_6.cs`。 这些文件合计约 656 个公开方法。它们已经进行了一部分 C# 类型转换，但函数名和参数模型仍基本对应 C API。 这使它们处于不稳定的中间层： - 不再是完全精确的 Raw ABI； - 又没有形成惯用的 C# API； - `count` 与 `ReadOnlySpan` 长度可能不一致； - `byte`、裸 `uint` 和裸指针仍大量暴露； - 资源句柄识别依赖参数名启发式规则。 ### 4.5 手写 OpenGLFunction 方法 `src/StgSharp.Graphics/OpenGL/glFunction.cs` 约 795 行，包含约 55 个手写公开方法，职责包括： - Context 与 `OpenGLFunction` 实例管理； - Buffer 创建、删除和数据上传； - Texture 创建和上传； - Framebuffer 和 Renderbuffer 操作； - Shader 创建、源码上传和状态检查； - Draw 调用； - 错误检查； - Vertex Attribute 配置。 这些方法与版本文件中的公开方法并存。例如同时存在： - `ActiveTextureUnit` 与 `ActiveTexture`； - `BindFrameBuffer` 与 `BindFramebuffer`； - `FrameBufferTexture2d` 与 `FramebufferTexture2D`； - `TextureImage2d` 与 `TexImage2D`； - `SetBufferData` 与 `BufferData`。 这种重复不是编译错误，但会让调用者无法判断哪一层是推荐 API，也会妨碍生成器安全地产生新重载。 ### 4.6 Uniform 类型与方法 `src/StgSharp.Graphics/OpenGL/ShaderEdit/Uniform.cs` 同时包含： - `Uniform` 基类； - `Uniform`； - `Uniform`； - `Uniform`； - `Uniform`； - `partial OpenGLFunction` 的 `SetUniformValue` 重载。 代码位置本身不影响编译，但该文件跨越了两个职责边界： - Uniform 数据模型； - OpenGL 命令封装。 这会导致生成器无法拥有 Uniform 方法的明确输出区域。 ### 4.7 Shader 相关代码 `src/StgSharp.Graphics/OpenGL/ShaderEdit/Shader.cs` 同时定义： - `partial glRender` 的 Shader 工厂方法； - `Shader`； - `ShaderStatus`； - `ShaderProgram`； - `ShaderProgram.GetUniform`。 此外还存在 `src/StgSharp.Graphics/ShaderEdit`，其中包含另一套 Shader 抽象。`OpenGL/ShaderEdit/IglConvertable.cs` 的文件路径位于 OpenGL 子目录，但命名空间是 `StgSharp.Graphics.ShaderEdit`。 当前文件位置和命名空间没有形成一致边界。 ### 4.8 绕过公开封装的调用 除 Loader 和绑定实现外，发现 `src/StgSharp.Graphics/ShaderEdit/ShaderStruct.cs` 直接获取： ```csharp OpenglContext* gl = (OpenglContext*)OpenGLFunction.CurrentGL.ContextHandle; ``` 随后直接调用 `glUniform*`。 这是高级代码对 ABI 层的越层依赖。新的 Uniform API 建立后，这里应只调用 `OpenGLFunction.SetUniformValue` 或对应的 Uniform 对象方法。 ## 5. 已确认的正确性问题 ### 5.1 Vec4 使用了错误的 OpenGL 函数 当前 `Uniform.cs` 中，`Vec4` 被传给： ```csharp glUniform1fv(location, 4, pointer); ``` 该调用表示上传 4 个标量 uniform，而不是上传 1 个四分量向量。 正确调用应为： ```csharp glUniform4fv(location, 1, pointer); ``` ### 5.2 整数 Uniform 调用了浮点函数 `ShaderStruct.SetAllUniforms` 的整数分支调用 `glUniform1f`，应调用 `glUniform1i`。 ### 5.3 Uniform location 被错误建模为 GlHandle OpenGL uniform location 的原始类型是有符号 `GLint`，并允许 `-1` 表示未找到。 当前实现使用 `GlHandle` 保存 uniform location。`GlHandle` 同时被用于 Buffer、Texture、Program 和 Shader 等 `GLuint` 对象名称，因此无法表达 uniform location 的不同语义和有效性规则。 建议引入： ```csharp public readonly record struct UniformLocation(int Value) { public bool IsValid => Value >= 0; } ``` ### 5.4 版本判断错误 `glManager.CheckCoreVersion` 当前使用类似以下判断： ```csharp majorVersion >= 4 || (majorVersion == 4 && minorVersion == requiredMinor) ``` 当上下文版本为 OpenGL 4.0 时，`majorVersion >= 4` 对 4.1 至 4.6 的检查也全部为真。 正确判断应为： ```csharp majorVersion > requiredMajor || (majorVersion == requiredMajor && minorVersion >= requiredMinor) ``` 版本和扩展能力还应保存在每个 OpenGL context 中，而不是静态全局字段中。 ### 5.5 上下文内存没有完整清零 `glRender.InitializeContext` 通过 `Marshal.AllocHGlobal` 分配 `OpenglContext`，但只将 `glGetString` 设置为零。 如果当前版本不加载某些较新函数，其字段可能保留未初始化值。公开版本方法仍然存在，错误调用时可能跳转到无效地址。 上下文分配后应完整清零，并通过 capability 检查限制不受支持的方法调用。 ### 5.6 函数指针调用约定需要统一审计 GLFW 返回的是非托管函数地址。当前 `OpenglContext` 多数使用 `delegate*<...>`，没有显式标记 `unmanaged` 调用约定。 生成器应根据目标平台统一生成并验证函数指针调用约定，例如： ```csharp delegate* unmanaged<...> ``` 或在确有需要时生成平台对应的显式调用约定。 ## 6. Uniform 函数族的推荐建模 ### 6.1 函数名解析 生成器应将以下函数族解析为结构化模型： ```text glUniform{1|2|3|4}{f|d|i|ui}{v?} glProgramUniform{1|2|3|4}{f|d|i|ui}{v?} glUniformMatrix{2|3|4|2x3|2x4|3x2|3x4|4x2|4x3}{f|d}v glProgramUniformMatrix{...}{f|d}v ``` 建议模型至少包含： ```text Operation = Uniform | ProgramUniform Shape = Scalar | Vector | Matrix Columns = 1..4 Rows = 1..4 ElementType = Float | Double | Int | UInt InputForm = Components | Array NativeCommand = glUniform4fv 等原始名称 IntroducedIn = OpenGL 版本 ``` 不要直接在字符串 emitter 中通过多组 `StartsWith` 和 `EndsWith` 拼接逻辑。应先完成函数族识别，再根据统一模型生成代码。 ### 6.2 推荐的 Uniform 类型 建议保留单泛型参数： ```csharp public readonly struct Uniform where T : unmanaged { public UniformLocation Location { get; } } ``` 向量和矩阵形状由 `T` 表达： ```text Uniform Uniform Uniform Uniform Uniform ``` 不建议继续使用 `Uniform` 表达四分量值。 要完整支持 `double`、`int` 和 `uint` 向量，数学库还需要提供对应的向量类型，或者 OpenGL 层需要定义布局稳定的专用值类型，例如： ```text DVec2 / DVec3 / DVec4 IVec2 / IVec3 / IVec4 UVec2 / UVec3 / UVec4 ``` ### 6.3 推荐重载 标量与向量： ```csharp void SetUniformValue(Uniform uniform, float value); void SetUniformValue(Uniform uniform, Vec2 value); void SetUniformValue(Uniform uniform, Vec3 value); void SetUniformValue(Uniform uniform, Vec4 value); ``` 数组： ```csharp void SetUniformValue( Uniform uniform, ReadOnlySpan values); void SetUniformValue( Uniform uniform, ReadOnlySpan values); ``` 矩阵： ```csharp void SetUniformValue( Uniform uniform, in GraphicsMatrix value, bool transpose = false); ``` 调用者不应手工传入 `count`。生成方法应根据 Span 长度和元素形状计算 OpenGL 的 `count` 参数。 ### 6.4 Raw API 的处理 建议保留与 OpenGL 一一对应的 Raw 方法，至少在迁移期内不要立即删除。 可选策略： 1. 将 Raw 方法改为 `internal`； 2. 放入单独的 `OpenGLRaw` 类型； 3. 暂时保持 `public`，但使用 `EditorBrowsable(Never)` 降低 IntelliSense 噪音； 4. 为旧 API 提供一个兼容周期，再逐步弃用。 Idiomatic API 不应与 Raw API 写入同一生成文件。 ## 7. 推荐目录结构 ```text src/StgSharp.Graphics/OpenGL/ Generated/ OpenglContext.g.cs OpenglLoader.v33.g.cs OpenGLFunction.Raw.v33.g.cs OpenGLFunction.Raw.v40.g.cs OpenGLFunction.Uniform.g.cs OpenGLFunction.ProgramUniform.g.cs Api/ OpenGLFunction.Context.cs OpenGLFunction.Diagnostics.cs OpenGLFunction.Buffer.cs OpenGLFunction.Texture.cs OpenGLFunction.Drawing.cs OpenGLFunction.Shader.cs Objects/ Uniform.cs UniformLocation.cs Shader.cs ShaderProgram.cs ShaderStatus.cs Buffer/ Texture/ Rendering/ GlRender.cs GlRender.Resources.cs GlRender.Threading.cs ``` 具体目录名称可以调整，但必须保持以下边界： - `Generated` 中的文件可以被完整覆盖； - 手写文件永远不写入 `Generated`； - Uniform 类型定义和 Uniform 调用方法分离； - Shader 资源对象不直接访问 `OpenglContext*`； - Loader 与 Context 来自同一个生成模型。 ## 8. 建议的文件迁移 ### 8.1 `Uniform.cs` 保留： - `Uniform`； - uniform location； - 与 uniform 数据模型直接相关的成员。 移出： - 所有 `partial OpenGLFunction` 方法。 ### 8.2 `Shader.cs` 拆分为： - `Shader.cs`； - `ShaderProgram.cs`； - `ShaderStatus.cs`； - `ShaderProgram.Uniform.cs`； - `GlRender.ShaderFactory.cs`。 ### 8.3 `ShaderStruct.cs` 移除： - `ContextHandle` 访问； - `OpenglContext*` 转换； - 直接 `glUniform*` 调用。 改为通过类型安全的 Uniform API 分发。 ### 8.4 `glFunction.cs` 保留 Context 生命周期和实例管理，然后按功能拆分手写便利方法： ```text OpenGLFunction.Context.cs OpenGLFunction.Diagnostics.cs OpenGLFunction.Buffer.cs OpenGLFunction.Texture.cs OpenGLFunction.Framebuffer.cs OpenGLFunction.Drawing.cs OpenGLFunction.Shader.cs ``` ### 8.5 `glFunction.SourceManager.cs` 该文件实际管理 Texture Unit，而不是 Source。建议重命名为： ```text OpenGLFunction.TextureUnits.cs ``` 进一步可以将 Texture Unit 分配状态移出函数绑定类，放入每个 Render Context 的资源管理对象。 ### 8.6 `IglConvertable.cs` 该文件位于 `OpenGL/ShaderEdit`，命名空间却是 `StgSharp.Graphics.ShaderEdit`。应移动到与命名空间一致的 `ShaderEdit` 目录。 ## 9. GenerateGL 推荐内部结构 建议将当前单一 `Generator` 拆分为以下阶段。 ### 9.1 Registry 解析 ```text GlXmlParser -> RegistryModel ``` 负责准确保留： - C 类型； - 指针层级； - const； - 参数组信息； - feature/profile/version； - alias； - enum group。 ### 9.2 ABI 类型映射 ```text RegistryModel -> AbiCommandModel ``` 这里只做精确映射，不做 `GlHandle`、Span 或 ShaderType 等高级推断。 ### 9.3 函数族分析 ```text AbiCommandModel -> CommandFamilyModel ``` 由专门规则识别： - Uniform； - ProgramUniform； - UniformMatrix； - VertexAttrib； - TexParameter； - Get 系列； - Gen/Delete/Create 系列。 无法识别的命令仍可生成 Raw API，但不得用不确定的启发式规则擅自改变资源类型。 ### 9.4 Emitters 建议拆分： ```text ContextEmitter LoaderEmitter RawFunctionEmitter UniformEmitter ProgramUniformEmitter ConstantEmitter HistoryEmitter ``` 每个 emitter 只负责一种输出，便于单独进行 golden-file 测试。 ## 10. 迁移计划 ### 阶段一：建立安全的生成边界 1. 新增 `OpenGL/Generated`； 2. 所有生成文件使用 `.g.cs` 后缀； 3. 生成器直接生成 `OpenglContext` 和 Loader； 4. 移除或自动生成 `glContextShadow`； 5. 增加函数数量、名称和版本一致性测试。 此阶段不改变现有公开 API。 ### 阶段二：修复 Uniform 模型 1. 新增 `UniformLocation`； 2. 将 `GetUniformLocation` 返回类型改为 `UniformLocation`； 3. 将 Uniform 简化为 `Uniform`； 4. 修复 Vec4 和整数 uniform 的错误调用； 5. 迁移 Camera、ShaderProgram 和 ShaderStruct。 ### 阶段三：生成 Uniform 重载 1. 实现 Uniform 函数族解析； 2. 生成 scalar/vector/matrix overload； 3. 自动计算 Span 对应的 count； 4. 生成 ProgramUniform 对应重载； 5. 使用 golden-file 测试验证每个原始命令映射到正确 overload。 ### 阶段四：整理其他手写便利 API 1. 拆分 `glFunction.cs`； 2. 统一 Buffer、Texture、Framebuffer 方法命名； 3. 明确 Raw API 的可见性和兼容策略； 4. 逐步为 VertexAttrib、TexParameter 等函数族生成重载。 ### 阶段五：清理旧 API 1. 标记旧 C 风格 public wrapper 为 obsolete 或隐藏； 2. 提供迁移说明； 3. 在约定的兼容版本后删除旧入口。 ## 11. 测试与验收标准 ### 11.1 Registry 一致性 - 每个 Context 字段必须有对应 Loader 赋值； - 每个 Raw wrapper 必须对应一个 Context 字段； - 不允许 Loader 引用不存在的字段； - Context、Loader 和 Wrapper 的版本归属必须一致。 ### 11.2 Uniform golden tests 至少验证： ```text float -> glUniform1f Vec2 -> glUniform2fv(count = 1) Vec3 -> glUniform3fv(count = 1) Vec4 -> glUniform4fv(count = 1) ReadOnlySpan -> glUniform4fv(count = span.Length) GraphicsMatrix -> glUniformMatrix4fv(count = 1) ``` 同时覆盖 `double`、`int`、`uint`、非方阵矩阵和 ProgramUniform。 ### 11.3 API 约束 - 高级代码不得访问 `OpenglContext*`； - 高级代码不得手工传入可由 Span 推导的 count； - uniform location 不得使用 `GlHandle`； - 生成文件不得包含手写区域； - 手写文件不得依赖生成字段的布局顺序； - 不支持的 OpenGL 版本方法不得调用未初始化函数指针。 ### 11.4 构建验证 GenerateGL 当前可以成功构建，但存在代码分析警告。 本次检查中，单独构建 `StgSharp.Graphics` 时，MSBuild 在项目引用 `StgSharp.Mathematics` 的 `GetTargetFrameworks` 阶段失败，最终显示 0 个 C# 错误和 0 个警告。该失败发生在 C# 编译前，因此本次评估不将其视为 Graphics 源码编译结果。 ## 12. 推荐的第一批实际改动 为了控制改动规模，第一批建议只完成以下内容： 1. 新增 `UniformLocation`； 2. 将 `Uniform` 收敛到 `Uniform`； 3. 把 `SetUniformValue` 从 `Uniform.cs` 移到独立 partial 文件； 4. 修复 `Vec4` 与整数 uniform 调用； 5. 让 `ShaderStruct` 不再访问 `OpenglContext*`； 6. 给 GenerateGL 增加 `UniformFamilyModel` 和 `UniformEmitter`； 7. 同时生成 Context 与 Loader，并消除 ContextShadow 的手工同步； 8. 增加 Context/Loader/Wrapper 集合一致性测试。 完成这一批后，再决定是否立即重构全部 `glFunction.cs`。这样可以先解决 Uniform API 和生成同步问题，同时避免一次性扩大到整个 Graphics 框架。