imgui-java

Important News!

(If you are using raw jars, you can skip this section.)
Because of JCenter shutdown library has moved to Maven Central. That fact affects nothing, but the groupId parameter in your Gradle and Maven configuration files. From version 1.80-1.5.0 use io.github.spair instead of io.imgui.java. See an updated How To Use section for details.

Old versions will not be transferred to Maven Central and will become unavailable after JCenter goes down.

---

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.

Features

• 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 is included by default to draw a better quality fonts. Should be enabled though.
  
• Extensions
  Binding includes several useful extensions for Dear ImGui. See full list.

How to Try

Make sure you have installed Java 8 or higher.

Demo

You can try binding by yourself in three simple steps:

git clone --branch v1.80-1.5.0 https://github.com/SpaiR/imgui-java.git
cd imgui-java
./gradlew :example:start

See example module to try other widgets in action.

How To Use

Application

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 everything you need to build your user interface with Dear ImGui!
At the same time, every life-cycle method of the application could be overridden, so you can extend class in the way you need.

Example

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.

Dependencies

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation "io.github.spair:imgui-java-app:1.80-1.5.0"
}

Maven

<dependencies>
    <dependency>
        <groupId>io.github.spair</groupId>
        <artifactId>imgui-java-app</artifactId>
        <version>1.80-1.5.0</version>
    </dependency>
</dependencies>

Raw Jar

1. Go to the release page;
2. Download imgui-app-${version}.jar;
3. Add the jar to your classpath.

Binding

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.

Dependencies

For simplicity, example of dependencies for Gradle and Maven only show how to add natives for Windows.
Feel free to add other platforms: imgui-java-natives-windows-x86, imgui-java-natives-linux, imgui-java-natives-linux-x86, imgui-java-natives-macos.

Gradle

repositories {
    mavenCentral()
}

ext {
    lwjglVersion = '3.2.3'
    imguiVersion = '1.80-1.5.0'
}

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.2.3</lwjgl.version>
    <imgui.java.version>1.80-1.5.0</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

1. Go to the release page;
2. Download imgui-binding-${version}.jar, imgui-lwjgl3-${version}.jar and binary libraries for your OS;

• imgui-java.dll - Windows 32bit
• imgui-java64.dll - Windows 64bit
• libimgui-java.so - Linux 32bit
• libimgui-java64.so - Linux 64bit
• libimgui-java64.dylib - MacOS

3. Add jars to your classpath;
4. Provide a VM option: imgui.library.path or java.library.path. It should point to the folder where you've placed downloaded native libraries.

Extensions

• 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.)

Binding Notice

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.

How to Build Native Libraries

Windows

• 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=win64 -Dlocal
• Run with: ./gradlew :example:start -DlibPath="../imgui-binding/build/libsNative/windows64"

Linux

• Install dependencies: openjdk8, mingw-w64-gcc, ant. (Package names could vary from system to system.)
• Build with: ./gradlew :imgui-binding:generateLibs -Denvs=linux64 -Dlocal
• Run with: ./gradlew :example:start -DlibPath=../imgui-binding/build/libsNative/linux64

MacOS

• Check dependencies from "Linux" section and make sure you have them installed.
• Build with: ./gradlew :imgui-binding:generateLibs -Denvs=mac64 -Dlocal
• Run with: ./gradlew :example:start -DlibPath=../imgui-binding/build/libsNative/macosx64

In envs parameter next values could be used win32, win64, linux32, linux64 or mac64.
-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.

License

See the LICENSE file for license rights and limitations (Apache-2.0).