JNI based binding for Dear ImGui with no dependencies.
Read official documentation and wiki to see how to work with Dear ImGui.
Almost everything from C++ could be done in Java in the same way.
Binding has an OpenGL renderer and a GLFW backend implementation, using a LWJGL3 library. Could be found in imgui-lwjgl3 module.
They are recommended, yet optional to use. The advantage of Dear ImGui is a portability, so feel free to copy-paste classes or write your own implementations.
Additionally, there is an imgui-app module, which provides a high abstraction layer.
It hides all low-level stuff under one class to extend, so you can build your GUI application instantly.
- Small and Efficient
Binding has a very small memory footprint and uses direct native calls to work. - Fully Featured
All public API was carefully implemented with Java usage in mind. - Multi-Viewports/Docking Branch
Binding has a full support of Multi-Viewports and Docking. - FreeType Font Renderer
FreeType font renderer provides a much better fonts quality. See how to use. - Extensions
Binding includes several useful extensions for Dear ImGui. See full list.
Make sure you have installed Java 8 or higher.
You can try binding by yourself in three simple steps:
git clone --branch v1.86.3 https://github.com/SpaiR/imgui-java.git
cd imgui-java
./gradlew :example:run
See example module to try other widgets in action.
ImGui in LWJGL YouTube video by GamesWithGabe.
You can use this video as a basic step-by-step tutorial. It shows how to integrate binding with the usage of jar files. Gradle and Maven dependecies could be used for this purpose as well.
Take a note, that integration itself is a very flexible process. It could be done in one way or another. If you just need a framework for your GUI - use Application module. Otherwise, if you need more control, the best way is not just to repeat steps, but to understand what each step does.
If you don't care about OpenGL or other low-level stuff, then you can use application layer from imgui-app module.
It is a one jar solution which includes: GLFW, OpenGL and Dear ImGui itself. So you only need one dependency line or one jar in classpath to make everything to work. You don't need to add separate dependencies to LWJGL or native libraries, since they are already included.
Application module is the best choice if everything you care is the GUI for your app.
At the same time, Application gives an option to override any life-cycle method it has. That means that if you're seeking for a bit more low-level control - you can gain it too.
A very simple application may look like this:
import imgui.ImGui;
import imgui.app.Application;
public class Main extends Application {
@Override
protected void configure(Configuration config) {
config.setTitle("Dear ImGui is Awesome!");
}
@Override
public void process() {
ImGui.text("Hello, World!");
}
public static void main(String[] args) {
launch(new Main());
}
}
Read imgui.app.Application
javadoc to understand how it works under the hood.
Gradle
repositories {
mavenCentral()
}
dependencies {
implementation "io.github.spair:imgui-java-app:1.86.3"
}
Maven
<dependencies>
<dependency>
<groupId>io.github.spair</groupId>
<artifactId>imgui-java-app</artifactId>
<version>1.86.3</version>
</dependency>
</dependencies>
Raw Jar
- Go to the release page;
- Download
imgui-app-${version}.jar
; - Add the jar to your classpath.
If using Java 9 modules, you will need to require the imgui.app
module.
Using binding without the wrapper requires to "attach" it to your application manually. You can refer to imgui-app module and see how things are done there.
For simplicity, example of dependencies for Gradle/Maven only shows how to add natives for Windows. Feel free to add other platforms.
Native Binaries | System |
---|---|
imgui-java-natives-windows | Windows |
imgui-java-natives-linux | Linux |
imgui-java-natives-macos | MacOS |
Take a note, that you also need to add dependencies to LWJGL. Examples below shows how to do it as well.
Gradle
repositories {
mavenCentral()
}
ext {
lwjglVersion = '3.3.1'
imguiVersion = '1.86.3'
}
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>1.86.3</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>
Raw Jars
- Go to the release page;
- Download
imgui-binding-${version}.jar
,imgui-lwjgl3-${version}.jar
and binary libraries for your OS;
- imgui-java64.dll - Windows
- libimgui-java64.so - Linux
- libimgui-java64.dylib - MacOS
- Add jars to your classpath;
- Provide a VM option:
imgui.library.path
orjava.library.path
. It should point to the folder where you've placed downloaded native libraries.
If using Java 9 modules, imgui-java has Automatic Module Names:
Package | Module |
---|---|
imgui-java-app | imgui.app |
imgui-java-binding | imgui.binding |
imgui-java-lwjgl3 | imgui.lwjgl3 |
imgui-java-natives | imgui.natives |
- ImNodes | Example
A small, dependency-free node editor for dear imgui. (A good choice for simple start.) - imgui-node-editor | Example
Node Editor using ImGui. (A bit more complex than ImNodes, but has more features.) - ImGuizmo | Example
Immediate mode 3D gizmo for scene editing and other controls based on Dear Imgui. - implot | Example
Advanced 2D Plotting for Dear ImGui. - ImGuiColorTextEdit | Example
Syntax highlighting text editor for ImGui. - ImGuiFileDialog | Example
A file selection dialog built for ImGui. - ImGui Club MemoryEditor | Example
Memory editor and viewer for ImGui.
By default, Dear ImGui uses stb-truetype to render fonts. Yet there is an option to use FreeType font renderer. Go to the imgui_freetype to read about the difference. Binding has this option too. Freetype especially useful when you use custom font with small (~<16px) size. If you use the default font or a large font, stb will be fine for you.
There are two types of precompiled binaries: 1. with stb (the default one) 2. with freetype. You can decide by yourself, which kind of libraries for any system you want to use.
Take a note, that for Linux and Mac users using of freetype will add an additional dependency to the libfreetype
itself.
This is not the case for Windows users, since dll
binaries are compiled fully statically and already include freetype in themselves.
For fully portable application use default binaries.
You can still use freetype binaries for Windows builds without worry though.
For better fonts use freetype binaries.
Don't forget to make clear for your Linux/Mac users, that they will need to install freetype on their systems as well.
-
Maven/Gradle:
Use the same native libraries as you would, but with-ft
suffix in the end.Modified Gradle Example
repositories { mavenCentral() } ext { lwjglVersion = '3.3.1' imguiVersion = '1.86.3' } 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" // This is the main difference implementation "io.github.spair:imgui-java-natives-windows-ft:$imguiVersion" }
-
If you're using raw dll/so files, go to the
bin/freetype
folder and take them from there.
Native Binaries With FreeType | System |
---|---|
imgui-java-natives-windows-ft | Windows |
imgui-java-natives-linux-ft | Linux |
imgui-java-natives-macos-ft | MacOS |
Binding was made with java usage in mind. Some places of the original library were adapted for that.
For example, in places where in C++ you need to pass a reference value, in Java you pass primitive wrappers: ImInt
, ImFloat
etc.
One important thing is how natives structs work. All of them have a public field with a pointer to the natively allocated memory.
By changing the pointer it's possible to use the same Java instance to work with different native structs.
Most of the time you can ignore this fact and just work with objects in a common way.
Read javadoc and source comments to get more info about how to do specific stuff.
Ensure you've downloaded git submodules. That could be achieved:
- When cloning the repository:
git clone --recurse-submodules https://github.com/SpaiR/imgui-java.git
- When the repository cloned:
git submodule init
+git submodule update
- Make sure you have installed and available in PATH:
- Java 8 or higher
- Ant
- Mingw-w64 (recommended way: use MSYS2 and install mingw-w64-x86_64-toolchain group)
- Build with:
./gradlew :imgui-binding:generateLibs -Denvs=win -Dlocal
- Run with:
./gradlew :example:run -PlibPath="../imgui-binding/build/libsNative/windows64"
- Install dependencies:
openjdk8
,mingw-w64-gcc
,ant
. (Package names could vary from system to system.) - Build with:
./gradlew :imgui-binding:generateLibs -Denvs=linux -Dlocal
- Run with:
./gradlew :example:run -PlibPath=../imgui-binding/build/libsNative/linux64
- Check dependencies from "Linux" section and make sure you have them installed.
- Build with:
./gradlew :imgui-binding:generateLibs -Denvs=mac -Dlocal
- Run with:
./gradlew :example:run -PlibPath=../imgui-binding/build/libsNative/macosx64
In envs
parameter next values could be used win
, linux
or mac
.
-Dlocal
is optional and means that natives will be built under the ./imgui-binding/build/
folder. Otherwise /tmp/imgui
folder will be used.
On Windows always use local build.
You can support the project to motivate its further development.
See the LICENSE file for license rights and limitations (Apache-2.0).