ITADN
AllenDang/cimgui-go
代码 动态 Issues115 合并请求250 版本6
AllenDang/cimgui-go · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Go Report Card Build Status Linter Status GoDoc Mentioned in Awesome Go

cimgui-go

本项目旨在为 Dear ImGui 生成 go 封装。

它附带了多个已实现的默认后端。

它支持 macOS(arm64/x86)、windows(x64)、Arch Linux (Gnome/KDE) 以及 Fedora Workstation 36+，理想情况下其他 linux GUI 也应该可以正常工作。请查看 examples：进入目录并执行 go run .。

[!note] 已知问题是，较新版本的 cimgui-go 在某些较旧的 linux 发行版（例如 Debian）上无法编译。 这是由于共享库是使用 GitHub Actions 版本的 Ubuntu 编译的（查看此表格以获取确切的 Ubuntu 版本），并且与较旧版本的 glibc 不兼容。 跟踪 #157。

设置

您可能需要在 linux 机器上安装一些依赖项。 请查看此处

模块概览

此模块包含几个可能需要解释的包：

包描述
imgui, implot, imnodes, e.t.c.实际的 Dear ImGui（及插件）绑定。用于显示控件和其他 UI 元素。
examples顾名思义 - 一组展示如何使用 cimgui-go 的示例
cmd/codegen生成 Go 绑定的代码生成器。
backend针对各种后端（glfw, sdl, ebiten, e.t.c.）的抽象层。
backend/*利用系统库来渲染 ImGui 的具体后端（实现 backend.Bckend）。
impl负责 imgui <-> 后端交互的包。（如果您想实现自己的后端，请使用它们。如果使用 backend/* 中的实现，则不需要）。
cwrappersDear ImGui 及其团队的 C 封装。还包含源代码（C++）。
lib用于与 cimgui-go 链接的预编译库集合。包含 ImGui、GLFW、SDL2 和其他依赖项的静态库。
thirdparty如 GLFW 和 SDL2 等第三方头文件。由后端使用。
utilscimgui-go 使用的一些实用函数。还包含 Vector 的实现。
templates (not package)存储生成过程中使用的文件。

支持的后端

为了便于使用，cimgui-go 实现了几个 imgui 后端。它们都位于 backend/ 子包中。 要了解特定后端的使用详情，请查看 examples。

我们支持以下后端：

  • GLFW. (GLFW 3.3 + OpenGL)
  • SDL2. (SDL 2 + OpenGL)
  • Ebitengine (import "github.com/AllenDang/cimgui-go/backend/ebitenbackend").
  • DRM/EGL (import "github.com/AllenDang/cimgui-go/backend/drmeglbackend", 仅限 Linux).
  • RayLib (import "github.com/AllenDang/cimgui-go/backend/raylibbackend").

[!important] 请记住，各种解决方案使用不同的 C 库，这些库可能会相互冲突。 建议不要同时导入例如 GLFW 和 SDL 后端，因为这可能会导致链接器崩溃。

[!note] DRM/EGL 后端旨在用于嵌入式 Linux / 信息亭设置，通过 DRM/KMS 直接渲染，而不使用 X11 或 Wayland。它目前专注于渲染和纹理上传；桌面风格的窗口管理、拖放和输入事件接线尚未实现。

[!tip] 要构建 DRM/EGL 示例/后端，请安装 libdrm-dev、libgbm-dev、libegl1-mesa-dev、libgles2-mesa-dev，然后使用 go run ./examples/drm-egl。

[!tip] 由于 glfw v3.4 在可能的情况下默认使用 wayland，而 wayland 不支持 imgui 的某些功能，因此存在一个 glfwbackend.ForceX11()。请在创建 glfwbackend.GLFWBakend 实例之前调用它。

命名约定

  • 对于函数，会去除 'Im/ImGui/ig'。
  • 也会去除 Get 前缀（有一些例外）。
  • 如果函数来自 imgui_internal.h，则会添加 Internal 前缀。

[!note] 您可能会注意到一些可能没有意义的函数签名（例如 Text(fmt string) 与 TextUnformatted(text string)）。 这是因为在原始代码中有一些“可变参数”（...）参数（void Text(const char* fmt, ...)）。 不幸的是，在 CGO 的当前状态下，没有办法将可变参数传递给 C 函数，因此这些函数是在没有可变参数的情况下生成的。另请参阅.

指针与切片

不幸的是，在 C 语言中无法区分指针和切片。 我们不得不将这一不便也带到了 Go 中。 我们的代码默认使用指针，但你可以通过简单地 &(slice[0]) 轻松将切片转换为指针。

[!tip] utils 包中有一些实用函数，包括：

  • utils.SliceToPtr(slice []T) *T - 将切片转换为指针。
  • utils.PtrToSlice(ptr *T, size int) []T - 将指针转换为指定大小的切片。请小心大小！如果错误使用，可能会导致段错误。

回调

请注意，目前（2025 年 6 月）go (1.24) 不支持通过 CGO 向 C 传递匿名函数。 我们有一个变通方案——预先生成大量全局函数和一个池。 详情请参见 https://github.com/AllenDang/cimgui-go/issues/224。 只需注意这一限制：你可能会用完预生成的池并导致崩溃。

函数覆盖

目前大多数函数已生成，除了内存相关的部分（例如内存分配器、存储管理等...）。 如果你发现缺少任何函数，请报告问题。

贡献

欢迎任何形式的贡献！

[!warning] 你永远不应该手动修改自动生成的文件！（每个文件顶部都放置了足够的注释） 所有违反此规则的 Pull Request 都无法通过自动检查，也不会被合并。

当前解决方案是：

  1. 使用 cimgui 的 lua 生成器将函数和结构体定义生成为 json。
  2. 根据定义生成相应的 go 代码（通过手动编写的 go 程序）。
  3. 使用 来自 imgui 的后端实现。
  4. 使用 github workflow 将 cimgui、glfw 和其他 C 依赖项编译为静态库，并将其放置在 ./lib 文件夹中以便后续链接。

您的贡献可能涉及以下几个领域：

代码生成

实际绑定是如何生成的方式。 此类修改应在 cmd/codegen 模块中进行。

[!tip] 建议将代码重新生成与代码生成修改分开提交（但这并非强制规则）。

要实际生成 Go 绑定，您需要以下设置：

  • 安装 GNU make
  • 您还需要 Go :smile:

然后，只需运行 make，或 make XXX，其中 XXX 是您想要生成的包名（例如 make imgui、make implot 等）。

硬编码绑定

包装器中有一些文件是硬编码的，并非自动生成。这些包括（但不限于）：

  • imgui/extra_types.go
  • imgui/extra_types.h
  • imgui/clipboard.go

[!note] 如果您认为应该修改，这些文件可以安全地修改。

同样适用于 backend/ 包。

更新插件

我们有一个特殊的系统，以便更轻松地更新依赖项。为了发布更新，请执行以下操作：

  • 确保您的系统上已安装 luajit。
  • 运行 make update。这需要一些时间，因为它会重新下载所有依赖项并重新生成整个 C 和 Go 绑定。
  • 提交您的更改并将其推送到 GitHub。
  • 按照下文描述执行 cimgui 编译：
如何在 GitHub 上运行 cimgui 编译

preview

  1. 前往你的 fork
  2. 导航至 "Actions" 选项卡
  3. 选择 "Compile cimgui" 工作流选项卡
  4. 点击 "Run workflow" 按钮
  5. 选择要运行工作流的分支
  6. 点击 "Run workflow" 按钮

在本地预编译代码

[!warning] 不要从你的本地机器推送预编译的代码！这可能包含你的本地路径，而你可能不希望与全世界分享它们。让 GitHub Actions 来完成编译。

由于 GitHub Actions 有时会有些慢，在本地机器上预编译代码可能有助于加快开发过程。 要在本地预编译代码，请执行以下操作：

  • 确保你的系统上已安装 cmake 以及合适的 C/C++ 工具链。
  • 进入 lib 目录。
  • 运行 cmake -Bbuild .
  • 然后，cd build 并运行 make -j$(nproc) 以编译所有 imgui 库。
  • 将 cimgui.a 复制到 lib/<your operatign system>/<your architecture>/cimgui.a

预编译代码

为了加快最终的 Go 构建过程，我们预编译了 C/C++ 库，并将它们放置在 libs/ 目录中。

这些库包括：

  • ImGui 及其所有插件（implot, imnodes, 等等。）
  • GLFW, SDL2 后端组件。

不幸的是，这意味着某些操作系统将无法开箱即用。 目前，我们针对以下操作系统进行编译：

  • macOS (arm64/x86_64)
  • Windows (x86_64)
  • Linux (x86_64)

如果你运行的是上述列表中未列出的任何系统，你需要在使用 cimgui-go 之前自行编译这些库。 请遵循这些说明。。如果你成功了，请通过提交 issue（或 pull request）告知我们，以便我们尝试为你的系统添加支持。

[!important] 预编译的共享库链接在名为 cflags.go 的文件中。你可以在 templates/cflags.go.template 中找到一个全局模板。修改后，只需运行一次常规生成，它应该会更新所有位置。

图库

App demo