特性
- 基于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就可以让一切工作。
您不需要添加单独的LWJGL或原生库依赖,因为它们已经包含在内。
如果您只关心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以了解它在底层是如何工作的。
依赖
Gradle
repositories {
mavenCentral()
}
dependencies {
implementation "io.github.spair:imgui-java-app:${version}"
}
Maven
```原始Jar文件
- 前往发布页面;
- 下载
java-libraries.zip
; - 获取
imgui-app-${version}-all.jar
; - 将jar文件添加到你的classpath中。
带有all
标识符的jar文件已经包含了binding
和lwjgl3
模块。
如果你使用的是不带all
标识符的jar文件,请同时添加相应的jar文件。
无论是带还是不带all
标识符的jar文件,都已经包含了所有必需的本地库。
Java模块系统
如果使用Java 9模块,你需要引入imgui.app
模块。
绑定
不使用imgui-app
模块而直接使用绑定需要手动将其"附加"到应用程序中。
你可以参考imgui-app
模块来了解具体的操作方法。
依赖
为简单起见,Gradle / Maven的依赖示例仅展示了如何添加Windows平台的本地库。你可以自由添加其他平台。
本地二进制文件 | 系统 |
---|---|
imgui-java-natives-windows | Windows |
imgui-java-natives-linux | Linux |
imgui-java-natives-macos | macOS |
请注意,你还需要添加LWJGL库的依赖。下面的示例也展示了如何添加这些依赖。
Gradle
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"
}
Maven
<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>
原始Jar文件
- 前往发布页面;
- 下载
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提供本地库的标准选项。
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
文件夹。
FreeType
要构建带有 FreeType 的库版本,你需要先运行 buildSrc/scripts/vendor_freetype.sh
脚本。
这个脚本会配置 FreeType 库以静态编译到你的项目中。
许可证
有关许可权利和限制(MIT),请参阅 LICENSE 文件。