XCEngine/docs/api/XCEngine/RHI/OpenGL/OpenGLTexture/Initialize.md

OpenGLTexture::Initialize()

bool Initialize(OpenGLTextureType type, int width, int height, int depth, int mipLevels, OpenGLFormat format, const void* data = nullptr);

作用

按通用参数创建一个 OpenGL 纹理对象。

参数

• type: 纹理类型。
• width: 宽度。
• height: 高度。
• depth: 深度或层数。对 3D、2DArray、CubeArray 等类型有意义。
• mipLevels: 期望的 mip 数量元数据。
• format: OpenGL 后端使用的格式枚举。
• data: 初始数据指针；传入 nullptr 时只分配 level 0 存储。

返回值

当前实现始终返回 true。

当前实现行为

函数会:

1. 写入 m_type、m_width、m_height、m_depth、m_mipLevels。
2. 通过 ToOpenGL(type) 获取目标 target。
3. 通过 ToOpenGLFormat(format, internalFormat, glFormat, glType) 解析上传格式。
4. 生成并绑定纹理对象。
5. 按类型选择上传路径:
   • TextureCube: 对六个 face 分别调用一次 glTexImage2D(..., level = 0, ..., data)
   • Texture1D: glTexImage1D(..., level = 0, ..., data)
   • Texture3D / Texture2DArray / TextureCubeArray: glTexImage3D(..., level = 0, ..., depth, ..., data)
   • 其他类型: glTexImage2D(..., level = 0, ..., data)
6. 根据 mipLevels > 1 决定最小过滤器是 GL_LINEAR_MIPMAP_LINEAR 还是 GL_LINEAR。
7. 把放大过滤器设为 GL_LINEAR。
8. 对 cube / cube array 默认使用 GL_CLAMP_TO_EDGE，其他类型默认使用 GL_REPEAT。
9. 对 3D、2DArray、Cube、CubeArray 额外设置 GL_TEXTURE_WRAP_R。
10. 解绑纹理并返回 true。

关键限制

• 当前只真正创建了 level 0，mipLevels 更多是缓存字段和默认 min filter 决策依据。
• 不会自动设置 GetFormat 对应的 RHI Format 元数据。
• CompressedDXT1 / CompressedDXT5 当前不会走压缩纹理上传 API。
• 没有显式错误处理，也不会在失败时返回 false。

相关文档

• Initialize2D
• InitializeCubeMap
• GetOpenGLType
• GetMipLevels