|
1 | 1 | # imgui-java |
2 | | -A handcrafted 1-1 Java binding for [Dear-ImGui](https://github.com/ocornut/imgui). |
| 2 | + |
| 3 | +[](https://bintray.com/spair/io.imgui.java/binding/_latestVersion) |
| 4 | +[](https://bintray.com/spair/io.imgui.java/lwjgl3/_latestVersion) |
| 5 | +[](https://javadoc.io/doc/io.imgui.java/binding) |
| 6 | + |
| 7 | +A handcrafted/generated Java binding for the [Dear-ImGui](https://github.com/ocornut/imgui) with no dependencies |
| 8 | +and ready to use pre-compiled binaries. |
| 9 | + |
| 10 | +It's a straightforward binding, which uses JNI to do a direct calls to the Dear-ImGui API.<br> |
| 11 | +Since we live in Java world - some things require to do them respectively to that fact. Please read **Binding notice**. |
| 12 | +Despite this fact, see official [documentation](https://github.com/ocornut/imgui#usage) and [wiki](https://github.com/ocornut/imgui/wiki) |
| 13 | +to get more info about how to do things in ImGui. |
| 14 | + |
| 15 | +Binding doesn't force you to use backend renderer which is introduced here. Feel free to use your own renderer engine if you need so. |
| 16 | +See how things are done in [ImGuiImplGl3](https://github.com/SpaiR/imgui-java/blob/master/imgui-lwjgl3/src/main/java/imgui/gl3/ImGuiImplGl3.java). |
| 17 | + |
| 18 | +Binding has the next version naming: `imguiVersion-bindingVersion`.<br> |
| 19 | +For example `1.74-0.1` means that binding uses `1.74` version of **ImGui** and binding itself has version `0.1`. |
3 | 20 |
|
4 | 21 | *Some of the very specific features are still in a wip state.* |
5 | 22 |
|
| 23 | +## How to try |
| 24 | +_Make sure you have installed Java 8 or higher._ |
| 25 | + |
| 26 | +You can try this binding by yourself in a three simple steps: |
| 27 | + |
| 28 | +``` |
| 29 | +git clone https://github.com/SpaiR/imgui-java.git |
| 30 | +cd imgui-java |
| 31 | +gradlew :imgui-lwjgl3:startExample |
| 32 | +``` |
| 33 | + |
| 34 | +That's it! This will start an example app [ImGuiGlfwExample](https://github.com/SpaiR/imgui-java/blob/master/imgui-lwjgl3/src/test/java/ImGuiGlfwExample.java) |
| 35 | +which relies on the GLFW and LWJGL3. Feel free to modify [ImGuiGlfwExample#showUi](https://github.com/SpaiR/imgui-java/blob/master/imgui-lwjgl3/src/test/java/ImGuiGlfwExample.java#L271) |
| 36 | +method to try different ImGui widgets in action. |
| 37 | + |
| 38 | +<details> |
| 39 | + <summary>GIF with example</summary> |
| 40 | + <img src="https://i.imgur.com/ZGHx4xf.gif"/> |
| 41 | +</details> |
| 42 | + |
6 | 43 | ## How to use |
7 | | -TBA |
| 44 | +#### Step 1 |
| 45 | +Add jcenter repository: |
| 46 | +``` |
| 47 | +repositories { |
| 48 | + jcenter() |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +#### Step 2 |
| 53 | +Add binding dependency: |
| 54 | +``` |
| 55 | +dependecies { |
| 56 | + implementation 'io.imgui.java:binding:1.74-0.1' |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +#### Step 3 (optional, but recommended) |
| 61 | +If you want to use LWJGL3 renderer: |
| 62 | +``` |
| 63 | +dependecies { |
| 64 | + implementation 'io.imgui.java:binding:1.74-0.1' |
| 65 | + implementation 'io.imgui.java:lwjgl3:1.74-0.1' |
| 66 | +} |
| 67 | +``` |
| 68 | +**Disclaimer!**<br> |
| 69 | +LWJGL3 renderer is based on the `3.2.3` version of the [LWJGL](https://www.lwjgl.org/). |
| 70 | +You'll need to add additional dependencies to it. Specifically `lwjgl` itself, `glfw` and `opengl` modules. |
| 71 | +You can find how to do it [here](https://www.lwjgl.org/customize). |
| 72 | + |
| 73 | +#### Step 4 |
| 74 | +Go to the `/bin` folder and pick a native library for your OS. Then you'll need to provide `java.library.path` VM option with folder |
| 75 | +where you placed the downloaded file. |
| 76 | + |
| 77 | +**You are ready to use imgui-java binding!** |
8 | 78 |
|
9 | | -##### Binding notice: |
10 | | -* Since it's a 1-1 binding please consider to see official [documentation](https://github.com/ocornut/imgui#usage) and [wiki](https://github.com/ocornut/imgui/wiki) |
11 | | - to get more info about how to do things. |
12 | | -* In places where in C++ you need to pass `ImVec2` or `ImVec4`, you'll need to pass two or four float parameters respectively. |
13 | | -* When you need to get an output from the Dear-ImGui use wrappers for primitives: `ImBool`, `ImInt` etc. |
| 79 | +#### Binding notice: |
| 80 | +* All ImGui methods are available in `camelCase`, not in `PascalCase`. |
| 81 | +* In places where in C++ you need to pass `ImVec2` or `ImVec4`, here you'll need to pass two or four float parameters respectively. |
| 82 | +* When you need to get an input/output to/from the Dear-ImGui use primitive wrappers: `ImBool`, `ImInt` etc. |
14 | 83 | * Due to the Java and JNI restrictions we can't provide a fully fledged callbacks to the ImGui::InputText*() methods. |
15 | | - Partly you could replace some of the features (like providing of the allowed chars to input) by using the ImGuiInputTextData class. Read javadoc to get more info. |
| 84 | + Partly you could replace some of the features (like setting of the allowed chars to input) by using the ImGuiInputTextData class. |
| 85 | + Read javadoc to get more info. |
16 | 86 |
|
17 | 87 | ## How to build |
18 | | -TBA |
| 88 | +To build native libraries you should install mingw-w64. Then modify [GenerateLibs](https://github.com/SpaiR/imgui-java/blob/master/buildSrc/src/main/groovy/imgui/generate/GenerateLibs.groovy) |
| 89 | +to build specific binaries you need. After you configured everything run `gradlew :imgui-binding:generateLibs` task. |
| 90 | +This will build native libraries and place them in `~/imgui-binding/build/libsNative` folder. |
19 | 91 |
|
20 | 92 | ## Credits |
21 | | -This binding is based on the work of [xpenatan](https://github.com/xpenatan) and his version of the binding [jDear-imgui](https://github.com/xpenatan/jDear-imgui). |
| 93 | +This binding is partly based on the work of [xpenatan](https://github.com/xpenatan) and his version [jDear-imgui](https://github.com/xpenatan/jDear-imgui). |
22 | 94 |
|
23 | 95 | ## License |
24 | 96 | See the LICENSE file for license rights and limitations (Apache-2.0). |
0 commit comments