未完待续

前言

加载一张图片到 GPU texture 已经超出 Dear ImGui 的范围，更多的是与图形 API 有关，但是 Dear ImGui 的用户经常遇到这个问题，因此提供一个文档。

这个文档将展示如何从磁盘上加载一张图片，并将其显示到 Dear ImGui window 上。

我们将加载这张图片：（MyImage01.jpg）

MyImage01.jpg

通常需要以下两步：

  • 从磁盘加载一张图片到内存。在这个例子中，我们解压图片成为 RGBA 格式。可以使用 std_image.h 库来完成；

  • 从内存中加载 RGBA 图片到 GPU texture。你将使用图形 API（例如 OpenGL，DirectX11）来完成。

当 GPU texture memory 中存在一张图片，你可以使用 ImGui::Image() 去请求 Dear ImGui 创建一个 draw command，之后 Dear ImGui rendering back-end 将生成一个 draw call。

渲染游戏场景到 texture

这个文档介绍了从磁盘加载一张图片文件，并且导入 GPU texture。另一个频繁使用 textures 的情况是，渲染你的应用/游戏场景到 texture，并且将 texture 展示在 Dear ImGui 窗口内。

该文档目前不覆盖这部分内容。

关于文件

两件事情需要注意：

  • 在 C/C++ 和大多数编程语言中，如果你想要在字符串文字使用反斜杠 \ ，你需要写两个反斜杠 \\ 。碰巧，Windows 使用反斜杠作为路径分隔符，所以要注意。

filename = "C:\MyFiles\MyImage01.jpg"         // This is INCORRECT!!
filename = "C:\\MyFiles\\MyImage01.jpg"       // This is CORRECT

在一些情况，你在 Windows 下也可以使用 / 路径分隔符。

  • 确保你的 IDE/debugger 从正确的工作目录启动你的可执行文件。在 Visual Studio， 你可以在 Properties > General > Debugging > Working Directory 里改变你的工作目录。

filename = "MyImage01.jpg";    // Relative filename depends on your Working Directory when running your program!
filename = "../MyImage01.jpg"; // Load from parent folder

ImTextureId

  • 给诸如 ImGui::Image() ，ImGui::ImageButton() 或者低水平 ImDrawList::AddImage() 的函数传递自己的 textures，触发 draw calls。

  • 实际 textures 的识别方式取决于用户/引擎。这些标识符被存储作为 ImTextureID 值传递。

  • 从磁盘加载图像文件并将其转换为纹理不在 Dear ImGui 的范围内。你可以阅读有关图形 API 的文档或教程来了解如何上传纹理。在本文档中，你将找到一些示例。

完整解释：

  • Dear ImGui 的工作是创建 "meshes"，由 draw commands 和 vertices 组成，以渲染无关的格式定义。在帧的最后，这些 meshes (ImDrawList) 将由渲染函数显示。它们由纹理多边形组成，渲染它们的代码通常非常短（几十行）。我们将提供常见图形 API 的示例（OpenGL, DirectX, etc）。

  • 每个渲染函数决定一个数据类型表示 "textures"。"texture" 的概念与你的底层引擎/图形 API 有关。我们携带信息去识别 ImTextureID 类型中的 "texture"。ImTextureID 默认是 ImU64，也就是 8 字节的数据：只够存 1 个指针或者你选择的一个整数。Dear ImGui 不知道你存储什么在 ImTextureID 中，它传递 ImTextureID 值，直到到达你的渲染函数。

OpenGL:       ImTextureID = GLuint                      (see ImGui_ImplOpenGL3_RenderDrawData()      in imgui_impl_opengl3.cpp)
DirectX9:     ImTextureID = LPDIRECT3DTEXTURE9          (see ImGui_ImplDX9_RenderDrawData()          in imgui_impl_dx9.cpp)
DirectX11:    ImTextureID = ID3D11ShaderResourceView*   (see ImGui_ImplDX11_RenderDrawData()         in imgui_impl_dx11.cpp)
DirectX12:    ImTextureID = D3D12_GPU_DESCRIPTOR_HANDLE (see ImGui_ImplDX12_RenderDrawData()         in imgui_impl_dx12.cpp)
SDL_Renderer: ImTextureID = SDL_Texture*                (see ImGui_ImplSDLRenderer2_RenderDrawData() in imgui_impl_sdlrenderer2.cpp)
Vulkan:       ImTextureID = VkDescriptorSet             (see ImGui_ImplVulkan_RenderDrawData()       in imgui_impl_vulkan.cpp)
WebGPU:       ImTextureID = WGPUTextureView             (see ImGui_ImplWGPU_RenderDrawData()         in imgui_impl_wgpu.cpp)