imgui-java

JNI based binding for Dear ImGui with no dependencies, ready to use pre-compiled binaries and renderer for LWJGL3.

Please read Binding Notice to get more info about java-specific things of the API.
See official documentation and wiki to get more info about how to do things in Dear ImGui.

Binding provides all the data you need to render Dear ImGui. If, for some reason, you want to use your own backend renderer, see ImGuiImplGl3 for reference.

Versioning semantic of the binding: imguiVersion-bindingVersion.
For example 1.74-0.1 means that imgui-java uses 1.74 version of Dear ImGui and binding itself has the version 0.1.

Additional available features:

Multi-Viewports/Docking
FreeType font renderer

How to Try

Make sure you have installed Java 8 or higher.

You can try Dear ImGui with Java by yourself in a three simple steps:

git clone --branch v1.78-1.2.0 https://github.com/SpaiR/imgui-java.git
cd imgui-java
gradlew :imgui-lwjgl3:startExample

That's all! You will start an example app ImGuiGlfwExample. Feel free to modify ExampleUi class to try different Dear ImGui widgets in action.

How to Use

With Gradle

repositories {
    jcenter()
    mavenCentral()
}

ext {
    lwjglVersion = '3.2.3'
    imguiVersion = '1.78-1.2.0'
}

switch (OperatingSystem.current()) {
	case OperatingSystem.LINUX:
		project.ext.imguiNatives = "imgui-java-natives-linux"
		project.ext.lwjglNatives = "natives-linux"
		break
	case OperatingSystem.MAC_OS:
		project.ext.imguiNatives = "imgui-java-natives-macos"
		project.ext.lwjglNatives = "natives-macos"
		break
	case OperatingSystem.WINDOWS:
		project.ext.imguiNatives = System.getProperty("os.arch").contains("64") ? "imgui-java-natives-windows" : "imgui-java-natives-windows-x86"
		project.ext.lwjglNatives = System.getProperty("os.arch").contains("64") ? "natives-windows" : "natives-windows-x86"
		break
}

dependencies {
    implementation "io.imgui.java:imgui-java-binding:$imguiVersion"
    implementation "io.imgui.java:imgui-java-lwjgl3:$imguiVersion"
    runtimeOnly "io.imgui.java:$imguiNatives:$imguiVersion"

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

    ['', '-opengl', '-glfw'].each {
        implementation "org.lwjgl:lwjgl$it:$lwjglVersion"
        runtimeOnly "org.lwjgl:lwjgl$it::$lwjglNatives"
    }
}

With Maven

<!-- Used to import imgui-java -->
<repositories>
    <repository>
        <id>jcenter</id>
        <url>https://jcenter.bintray.com/</url>
    </repository>
</repositories>

<properties>
    <lwjgl.version>3.2.3</lwjgl.version>
    <imgui.java.version>1.78-1.2.0</imgui.java.version>
</properties>

<!-- Resolve OS version for native libraries -->
<!-- imgui-java uses the same naming convention as LWJGL3 -->
<profiles>
    <profile>
        <id>natives-linux-amd64</id>
        <activation>
            <os>
                <family>unix</family>
                <arch>amd64</arch>
            </os>
        </activation>
        <properties>
            <imguiNatives>imgui-java-natives-linux</imguiNatives>
            <lwjglNatives>natives-linux</lwjglNatives>
        </properties>
    </profile>
    <profile>
        <id>natives-macos-amd64</id>
        <activation>
            <os>
                <family>mac</family>
                <arch>amd64</arch>
            </os>
        </activation>
        <properties>
            <imguiNatives>imgui-java-natives-macos</lwjgl.imguiNatives>
            <lwjglNatives>natives-macos</lwjgl.lwjglNatives>
        </properties>
    </profile>
    <profile>
        <id>natives-windows-amd64</id>
        <activation>
            <os>
                <family>windows</family>
                <arch>amd64</arch>
            </os>
        </activation>
        <properties>
            <imguiNatives>imgui-java-natives-windows</imguiNatives>
            <lwjglNatives>natives-windows</lwjglNatives>
        </properties>
    </profile>
    <profile>
        <id>natives-windows-x86</id>
        <activation>
            <os>
                <family>windows</family>
                <arch>x86</arch>
            </os>
        </activation>
        <properties>
            <imguiNatives>imgui-java-natives-windows-x86</imguiNatives>
            <lwjglNatives>natives-windows-x86</lwjglNatives>
        </properties>
    </profile>
</profiles>

<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>
    <!-- imgui-java -->
    <dependency>
        <groupId>io.imgui.java</groupId>
        <artifactId>binding</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>
    <dependency>
        <groupId>io.imgui.java</groupId>
        <artifactId>lwjgl3</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>
    <dependency>
        <groupId>io.imgui.java</groupId>
        <artifactId>${imguiNatives}</artifactId>
        <version>${imgui.java.version}</version>
    </dependency>

    <!-- LWJGL -->
    <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>${lwjglNatives}</classifier>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-glfw</artifactId>
        <classifier>${lwjglNatives}</classifier>
    </dependency>
    <dependency>
        <groupId>org.lwjgl</groupId>
        <artifactId>lwjgl-opengl</artifactId>
        <classifier>${lwjglNatives}</classifier>
    </dependency>
</dependencies>

With Raw Jars

Go to the release page
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 - MacOsX 64bit
Add jars to your classpath.
Provide a VM option: imgui.library.path or java.library.path. It should point to the folder where you've placed downloaded native libraries.

Important!
If you're using native libs directly, you'll need to provide a VM option: imgui.library.path or java.library.path. It should point to the folder where you've placed downloaded binaries.

You are ready to use imgui-java binding!

Using Multi-Viewports and Docking

Binding based on the Dear ImGui docking branch, commit: 05bc204dbd80dfebb3dab1511caf1cb980620c76. That branch contains two important features: multi-viewports and docking. See an official documentation about how to work with them.

Important!

Take a note that multi-viewports api is VERY complex to implement. It's highly recommended to use imgui.glfw.ImGuiImplGlfw class as it's done in the example. Otherwise, if you're using your own backed implementation, there are no guarantees it will work.

Using FreeType

Dear ImGui by default uses a stb_strutype library to render a fonts atlas. It's possible to use FreeType instead to get better fonts quality. See an example in ImGuiGlfwExample. Read more

Binding Notice

All Dear ImGui methods are available in camelCase, not in PascalCase.
To pass ImVec2/ImVec4 - provide two/four float numbers. To get ImVec2/ImVec4 - provide a destination object.
To get an input/output to/from Dear ImGui - use primitive wrappers: ImBool, ImInt etc.
Due to the Java and JNI restrictions we can't provide a fully fledged callbacks to the ImGui::InputText methods. To replace some features use an ImGuiInputTextData class.
All classes which are represent Dear ImGui structs have a field with a pointer to those structs. Field is public and could be modified without restrictions. So by changing the pointer it's possible to use the same java class to modify different native structs. Commonly you don't need to mind about that. Just keep in mind that you are able to do advanced stuff with it like: save pointers to the structs to modify them later.
Read javadoc and sources comments to get more info.

How to Build

To build native libraries you need:

Unix-like system (MacOS to build natives for Mac)
Installed dependencies: mingw-w64, ant, freetype2

After you've configured everything, run gradlew :imgui-binding:generateLibs -Denvs=${envShortcut} -Dlocal.
envShortcut could be 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.

Credits

Binding partly based on the work of xpenatan and his version jDear-imgui.

License

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

aeris170 / imgui-java