jimgui

Linux Build	Windows Build

To jcenter users: as the deprecation of jcenter, this library is now published to maven central since v0.20. Please update your repository setting to reflect the change.

Cross-platform efficient pure Java binding for dear-imgui, Kotlin is used as code generation tool.

This binding is rather bare, that reflects imgui's API directly. I think it's good enough, but you may expect some other styles. There is a declarative wrapper of jimgui, namely flui available.

Features

Can be considered as both advantages and disadvantages.

Java

It is Java-only with an optional Kotlin DSL wrapper.

Pure

It hides everything about rendering behind-the-scene, so you don't need to worry about GLFW, OpenGL or DirectX stuffs (speaking of lwjgl or jogl integration -- see #18, it's hard).

Also, it doesn't separate jars for different platforms. One jar works on all platforms.

Usability

It is well-known that dear imgui doesn't have image loading out-of-the-box, but this library have, and it even has a wrapper for aiekick/ImGuiFileDialog and Flix01/imguidatechooser and some other minor widgets.

Efficiency

This is twofolded.

• JNI efficiency. It exploits Critical Native and it avoids accessing Java from C++. Only arrays and primitive types are passed from Java to C++, and only primitive types are returned.
• Optimization for strings. That jimgui by default uses an inefficient way to convert java.lang.String into byte arrays that C++ is happy with. You can customize the string-to-bytes function yourself by using org.ice1000.jimgui.util.JImGuiUtil.setStringToBytes the default caching JImGuiUtil.cacheStringToBytes(), or use the more efficient alternative to java.lang.String -- org.ice1000.jimgui.JImStr, which is supposed to be created as global constants.

IDE-friendliness

It exploits JetBrains annotations, particularly with MagicConstant, NotNull, Nullable and Contract.

MagicConstant annotation enables IntelliJ IDEA to provide completion for int flags arguments with only the flags needed:

This project was created for a code editor and a game engine, both dead.

For macOS users, make sure you add -XstartOnFirstThread JVM argument when running applications built with jimgui.

Demo

• Partial re-implementation of imgui_demo.cpp.
• A sample text editor
• DrawList party, with a YouTube video

Contents

Bindings to official features

• ImGui namespace getter/setter/function/javadoc generation
• ImGuiFontAtlas/ImGuiStyle/ImGuiFont/ImGuiIO/ImGuiDrawList properties getter/setter/function/javadoc generation
• ImGui*Flags constant/javadoc generation
• ImStyleVar keys using generic parameter as type constraint (type safe!)

Extra convenience provided

• Functions to access and modify platform window size/pos
• Use MagicConstant annotation to specify where the constant parameters are from (IntelliJ IDEA understands this!)
  • Generate functions with MagicConstant annotation
• Critical Native function generations
• A few extensions, including emptyButton, dragVec4, sliderVec4, lineTo, circle, bufferingBar, dialogBox, spinner (Android style!), toggleButton (iOS style!), mostly from the issues and the communities.
• Integration of aiekick/ImGuiFileDialog as JImFileDialog
• Integration of Flix01/imguidatechooser as imgui.dateChooser

C++ interoperability

• Native value pointer (bool *, int *, float *) wrappers, providing accessValue and modifyValue
• ImVec4 wrapper with optional mutability
• ImTextureID wrapper with platform-dependent implementations
  • LPDIRECT3DTEXTURE9 on WindowsXP+
  • ID3D11ShaderResourceView* on Windows7+
  • GLuint on MacOS/Linux

Backends and platforms

• Linux native library with glfw3 + opengl3 implementation
  • 32-bit hosted on ?
  • 64-bit hosted on CircleCI
• WindowsXP+ native library
  • with glfw + opengl3 implementation (no longer maintained)
    • 32-bit hosted on ?
    • 64-bit hosted on ?
  • with directX9 implementation
    • 32-bit hosted on my laptop
    • 64-bit hosted on my laptop
• Windows7+ native library with directX11 implementation
  • 32-bit hosted on my laptop
  • 64-bit hosted on my laptop
• MacOS native library with Cocoa, glut as additions to Linux implementation
  • hosted on @newk5 's VM

Usage

Code example

import org.ice1000.jimgui.JImGui;
import org.ice1000.jimgui.util.JniLoader;

public class Main {
  public static void main(String... args){
    JniLoader.load();
    try (JImGui imGui = new JImGui()) {
      // load fonts, global initializations, etc.
      while (!imGui.windowShouldClose()) {
        // some drawing-unrelated initializations
        // mostly do nothing here
        imGui.initNewFrame();
        // draw your widgets here, like this
        imGui.text("Hello, World!");
        imGui.render();
        // mostly do nothing here
      }
    }
  }
}

Kotlin DSL:

runPer(10) {
  "Window with Tabs" {
    tabBar("tab bar id") {
      tabItem("Tab One") { text("I am in Tab one!") }
      tabItem("Tab Two") { button("I am in Tab two!") }
      tabItem("Tab Three") { bulletText("I am in Tab three!") }
    }

    treeNode("PsiClassBody") {
      treeNode("PsiConstructor") {
        text("PsiIdentifier")
      }
      treeNode("PsiMethod") {
        text("PsiAnnotation")
        text("PsiLeafElement")
      }
    }
  }
}

Using Unicode strings

You can use ImGuiFontAtlas in order to extend glyph ranges for your font, which is needed if you want to display Unicode characters. You can find more info about glyph ranges at the dear-imgui repository.

Notice that in order to display Unicode characters you need to have your Java sources encoded and compiled as UTF-8. To compile the sources as UTF-8, add the following line to your build.gradle:

compileJava.options.encoding = 'UTF-8'

Gradle

import org.apache.tools.ant.taskdefs.condition.Os
// ...
dependencies {
  String jimguiVersion = 'v0.20.3'
  implementation "org.ice1000.jimgui:core:$jimguiVersion" // basic functionality
  implementation "org.ice1000.jimgui:kotlin-dsl:$jimguiVersion" // kotlin dsl wrapper
}
// ...
tasks.withType(JavaExec).configureEach {
  if (Os.isFamily(Os.FAMILY_MAC)) jvmArgs "-XstartOnFirstThread"
}

Gradle Kotlin DSL

import org.apache.tools.ant.taskdefs.condition.Os
dependencies {
  val jimguiVersion = "v0.20.3"
  implementation("org.ice1000.jimgui:core:$jimguiVersion") // basic functionality
  implementation("org.ice1000.jimgui:kotlin-dsl:$jimguiVersion") // kotlin dsl wrapper
}

tasks.withType<JavaExec>().configureEach {
  if (Os.isFamily(Os.FAMILY_MAC)) jvmArgs("-XstartOnFirstThread")
}

Maven

<dependency>
  <groupId>org.ice1000.jimgui</groupId>
  <!-- basic functionality -->
  <artifactId>core</artifactId>
  <version>v0.20.3</version>
  <type>pom</type>
</dependency>

Build

First you need to make sure you have cmake newer than 3.14 and the following software installed:

• For Linux
  • make
  • pkg-config
  • libglfw3-dev
• For Windows (>= XP)
  • Visual Studio 2019 with msbuild (needs to be on PATH)
  • DirectX 9 Libraries (should be pre-installed on Windows or with Visual Studio)
  • DirectX SDK
• For macOS
  • Everything needed on Linux
  • Frameworks including Cocoa, GLUT, OpenGL
  • Run with JVM Argument: -XstartOnFirstThread (You can use export _JAVA_OPTIONS='-XstartOnFirstThread')

To compile a jar library, run (you need to use the developer command prompt for this on Windows):

$ ./gradlew jar

To run tests, run:

$ ./gradlew test