ImGui Java

基于JNI的 Dear ImGui 绑定

</div>

特性

基于JNI 使用生成的JNI代码实现原生通信层。无依赖，无问题。
小巧高效 绑定具有小内存占用，并使用直接原生调用工作。
功能齐全 所有公共API都经过精心实现，以Java使用为导向。
多视口 / 停靠分支 绑定完全支持多视口和停靠。
FreeType字体渲染器 FreeType字体渲染器提供更好的字体质量。查看如何使用。
扩展 绑定包含了几个有用的Dear ImGui扩展。查看完整列表。

要了解如何使用ImGui Java，请阅读官方文档和wiki。绑定采用C++ API for Java，但几乎所有内容都可以以相同的方式使用。

ImGui Java有一个可直接使用的GLFW和OpenGL API实现，使用LWJGL3库。参见imgui-lwjgl3模块。 该实现是可选的。Dear ImGui的优势在于完全可移植性，所以可以自由复制粘贴类或编写自己的实现。

此外，还有一个imgui-app模块，它提供了高级抽象层。 它将所有底层代码隐藏在一个可扩展的类中。使用它，您可以立即构建GUI应用程序。

支持

您可以支持该项目以激励其进一步发展。

如何尝试

确保您已安装JDK 8或更高版本。

演示

您可以通过三个简单的步骤自行尝试绑定：

git clone git@github.com:SpaiR/imgui-java.git
cd imgui-java
./gradlew :example:run

查看example模块以尝试其他小部件的实际效果。

如何使用

LWJGL中的ImGui YouTube视频 由GamesWithGabe制作。 您可以将此视频作为基本的逐步教程。它展示了如何使用jar文件集成绑定。 Gradle和Maven依赖也可以用于此目的。

请注意，集成本身是一个非常灵活的过程。它可以以不同的方式完成。如果您只需要GUI框架，请使用Application模块。否则，如果您需要更多控制，最好不仅仅是重复步骤，而是要理解每个步骤的作用。

对于macOS M芯片用户

macOS版本的绑定编译为通用二进制文件。这意味着您可以在x86_64和aarch64平台上使用它，无需任何额外操作。

应用程序

如果您不关心OpenGL和其他底层内容，那么可以使用imgui-app模块中的应用程序层。它是一个单jar解决方案，包括：GLFW、OpenGL和Dear ImGui本身。所以您只需要一行依赖或类路径中的一个jar就可以让一切工作。 <ins>您不需要添加单独的LWJGL或原生库依赖，因为它们已经包含在内。</ins>

如果您只关心GUI本身，应用程序模块是最佳选择。

同时，Application提供了覆盖其任何生命周期方法的选项。这意味着如果您寻求更多底层控制，也可以获得。

示例

一个非常简单的应用程序可能如下所示：

import imgui.ImGui;
import imgui.app.Application;
import imgui.app.Configuration;

public class Main extends Application {
    @Override
    protected void configure(Configuration config) {
        config.setTitle("Dear ImGui 真棒！");
    }

    @Override
    public void process() {
        ImGui.text("你好，世界！");
    }

    public static void main(String[] args) {
        launch(new Main());
    }
}

阅读imgui.app.Application javadoc以了解它在底层是如何工作的。

依赖

Maven Central

<details> <summary>Gradle</summary>

repositories {
    mavenCentral()
}

dependencies {
    implementation "io.github.spair:imgui-java-app:${version}"
}

</details> <details> <summary>Maven</summary> ``` <dependencies> <dependency> <groupId>io.github.spair</groupId> <artifactId>imgui-java-app</artifactId> <version>${version}</version> </dependency> </dependencies> ``` <details> <summary>原始Jar文件</summary>

前往发布页面;
下载java-libraries.zip;
获取imgui-app-${version}-all.jar;
将jar文件添加到你的classpath中。

带有all标识符的jar文件已经包含了binding和lwjgl3模块。如果你使用的是不带all标识符的jar文件，请同时添加相应的jar文件。

无论是带还是不带all标识符的jar文件，都已经包含了所有必需的本地库。

</details>

Java模块系统

如果使用Java 9模块，你需要引入imgui.app模块。

绑定

不使用imgui-app模块而直接使用绑定需要手动将其"附加"到应用程序中。你可以参考imgui-app模块来了解具体的操作方法。

依赖

Maven Central

为简单起见，Gradle / Maven的依赖示例仅展示了如何添加Windows平台的本地库。你可以自由添加其他平台。

本地二进制文件	系统
imgui-java-natives-windows	Windows
imgui-java-natives-linux	Linux
imgui-java-natives-macos	macOS

请注意，你还需要添加LWJGL库的依赖。下面的示例也展示了如何添加这些依赖。

<details> <summary>Gradle</summary>

repositories {
    mavenCentral()
}

ext {
    lwjglVersion = '3.3.3'
    imguiVersion = "${version}"
}

dependencies {
    implementation platform("org.lwjgl:lwjgl-bom:$lwjglVersion")

    ['', '-opengl', '-glfw'].each {
        implementation "org.lwjgl:lwjgl$it:$lwjglVersion"
        implementation "org.lwjgl:lwjgl$it::natives-windows"
    }
    
    implementation "io.github.spair:imgui-java-binding:$imguiVersion"
    implementation "io.github.spair:imgui-java-lwjgl3:$imguiVersion"
    
    implementation "io.github.spair:imgui-java-natives-windows:$imguiVersion"
}

</details> <details> <summary>Maven</summary>

<properties>
    <lwjgl.version>3.3.1</lwjgl.version>
    <imgui.java.version>${version}</imgui.java.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.lwjgl</groupId>
            <artifactId>lwjgl-bom</artifactId>
            <version>${lwjgl.version}</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl</artifactId>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-glfw</artifactId>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-opengl</artifactId>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl</artifactId>
        <classifier>natives-windows</classifier>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-glfw</artifactId>
        <classifier>natives-windows</classifier>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-opengl</artifactId>
        <classifier>natives-windows</classifier>
    </dependency>
    
    <dependency>
        <groupId>io.github.spair</groupId>
        <artifactId>imgui-java-binding</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>
    <dependency>
        <groupId>io.github.spair</groupId>
        <artifactId>imgui-java-lwjgl3</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>
    <dependency>
        <groupId>io.github.spair</groupId>
        <artifactId>imgui-java-natives-windows</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>
</dependencies>

</details> <details> <summary>原始Jar文件</summary>

前往发布页面;
下载java-libraries.zip和native-libraries.zip;
从java-libraries中获取imgui-binding-${version}.jar和imgui-lwjgl3-${version}.jar，以及从native-libraries压缩包中获取所需操作系统的二进制库;
将jar文件添加到你的classpath中;
提供一个VM选项，指定native-libraries压缩包中文件的位置。

VM选项示例：

-Dimgui.library.path=${路径}
-Djava.library.path=${路径}

imgui.library.path和java.library.path是等效的，区别在于java.library.path是JVM提供本地库的标准选项。

</details>

Java模块系统

如果使用Java 9模块，ImGui Java有自动模块名：

包名	模块名
imgui-java-app	imgui.app
imgui-java-binding	imgui.binding
imgui-java-lwjgl3	imgui.lwjgl3
imgui-java-natives-windows	imgui.natives.windows
imgui-java-natives-linux	imgui.natives.linux
imgui-java-natives-macos	imgui.natives.macos

扩展

所有扩展都已包含在绑定中，可以直接使用。有关如何使用它们的更多信息，请参阅example模块中的示例。

ImNodes | 示例 一个小型、无依赖的 Dear ImGui 节点编辑器。（适合简单入门的不错选择。）
imgui-node-editor | 示例 使用 ImGui 的节点编辑器。（比 ImNodes 稍复杂，但功能更多。）
ImGuizmo | 示例 基于 Dear ImGui 的即时模式 3D 操纵器，用于场景编辑和其他控制。
implot | 示例 Dear ImGui 的高级 2D 绘图工具。
ImGuiColorTextEdit | 示例 ImGui 的语法高亮文本编辑器。
ImGuiFileDialog | 示例 为 ImGui 构建的文件选择对话框。
ImGui Club MemoryEditor | 示例 ImGui 的内存编辑器和查看器。

FreeType

默认情况下，Dear ImGui 使用 stb-truetype 来渲染字体。但是，还有一个选项可以使用 FreeType 字体渲染器。要了解它们之间的区别，请访问 imgui_freetype 页面。

这个绑定也支持 FreeType 选项。 FreeType 被静态预编译到库中，这意味着它默认启用，没有禁用选项。因此，你可以在字体配置中自由使用 ImGuiFreeTypeBuilderFlags。

如果你不想使用 FreeType 字体渲染器，你需要构建自己的二进制文件并使用它们。

绑定说明

绑定是考虑到 Java 使用而制作的。原始库的某些地方已经为此进行了调整。 例如，在 C++ 中需要传递引用值的地方，在 Java 中你需要传递原始类型的包装器：ImInt、ImFloat 等。

一个重要的事情是原生结构体的工作方式。它们都有一个指向本地分配内存的公共字段指针。 通过更改指针，可以使用相同的 Java 实例来处理不同的本地结构体。 大多数情况下，你可以忽略这一点，只需以常规方式使用对象即可。

阅读 javadoc 和源代码注释以获取更多关于如何执行特定操作的信息。

如何构建本地库

确保你已经下载了 git 子模块。可以通过以下方式实现：

克隆仓库时：git clone --recurse-submodules https://github.com/SpaiR/imgui-java.git
仓库克隆后：git submodule init 和 git submodule update

Windows

确保你已安装并在 PATH 中可用：
- JDK 8 或更高版本
- Ant
- Mingw-w64（推荐方式：使用 MSYS2 并安装 mingw-w64-x86_64-toolchain 组）
使用以下命令构建：./gradlew imgui-binding:generateLibs -Denvs=windows -Dlocal
使用以下命令运行：./gradlew example:run -PlibPath="../imgui-binding/build/libsNative/windows64"
始终使用 -Dlocal 标志。

Linux

安装依赖项：openjdk8、mingw-w64-gcc、ant。（包名可能因系统而异。）
使用以下命令构建：./gradlew imgui-binding:generateLibs -Denvs=linux -Dlocal
使用以下命令运行：./gradlew example:run -PlibPath=../imgui-binding/build/libsNative/linux64

macOS

检查"Linux"部分中的依赖项，并确保已安装。
使用以下命令构建：./gradlew imgui-binding:generateLibs -Denvs=macos -Dlocal
使用以下命令运行：./gradlew example:run -PlibPath=../imgui-binding/build/libsNative/macosx64

macOS (arm64)

检查"Linux"部分中的依赖项，并确保已安装。
使用以下命令构建：./gradlew imgui-binding:generateLibs -Denvs=macosarm64 -Dlocal
使用以下命令运行：./gradlew example:run -PlibPath=../imgui-binding/build/libsNative/macosxarm64

在 envs 参数中可以使用以下值：windows、linux、macos 或 macosarm64。

-Dlocal 是可选的，表示本地库将在 ./imgui-binding/build/ 文件夹下构建。否则将使用 /tmp/imgui 文件夹。