diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index dca1be02..adec4998 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -49,7 +49,7 @@ jobs: shell: cmd run: | cd examples\example_null - call "%VS_PATH%\VC\Auxiliary\Build\vcvars64.bat" + call "%VS_PATH%\VC\Auxiliary\Build\vcvars64.bat" .\build_win32.bat /W4 - name: Build example_null (single file build) @@ -72,7 +72,7 @@ jobs: - name: Build example_null (as DLL) shell: cmd run: | - call "%VS_PATH%\VC\Auxiliary\Build\vcvars64.bat" + call "%VS_PATH%\VC\Auxiliary\Build\vcvars64.bat" echo #ifdef _EXPORT > example_single_file.cpp echo # define IMGUI_API __declspec(dllexport) >> example_single_file.cpp echo #else >> example_single_file.cpp @@ -393,12 +393,12 @@ jobs: emsdk-master/emsdk install latest emsdk-master/emsdk activate latest - - name: Build example_emscripten + - name: Build example_emscripten_opengl3 run: | pushd emsdk-master source ./emsdk_env.sh popd - make -C examples/example_emscripten + make -C examples/example_emscripten_opengl3 Discord-CI: runs-on: ubuntu-18.04 diff --git a/.gitignore b/.gitignore index 84014850..1ef7b007 100644 --- a/.gitignore +++ b/.gitignore @@ -34,7 +34,7 @@ xcuserdata examples/*.o.tmp examples/*.out.js examples/*.out.wasm -examples/example_emscripten/example_emscripten.* +examples/example_emscripten_opengl3/example_emscripten_opengl3.* ## JetBrains IDE artifacts .idea diff --git a/docs/BACKENDS.md b/docs/BACKENDS.md index 87d54542..835bf94e 100644 --- a/docs/BACKENDS.md +++ b/docs/BACKENDS.md @@ -42,7 +42,7 @@ It is important to understand the difference between the core Dear ImGui library and backends which we are describing here (backends/ folder). - Some issues may only be backend or platform specific. -- You should be able to write backends for pretty much any platform and any 3D graphics API. +- You should be able to write backends for pretty much any platform and any 3D graphics API. e.g. you can get creative and use software rendering or render remotely on a different machine. @@ -75,7 +75,7 @@ List of high-level Frameworks Backends (combining Platform + Renderer): imgui_impl_marmalade.cpp Emscripten is also supported. -The [example_emscripten](https://github.com/ocornut/imgui/tree/master/examples/example_emscripten) app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible. +The [example_emscripten_opengl3](https://github.com/ocornut/imgui/tree/master/examples/example_emscripten_opengl3) app uses imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp, but other combos are possible. ### Backends for third-party frameworks, graphics API or other languages @@ -129,32 +129,32 @@ If you are new to Dear ImGui, first try using the existing backends as-is. You will save lots of time integrating the library. You can LATER decide to rewrite yourself a custom backend if you really need to. In most situations, custom backends have less features and more bugs than the standard backends we provide. -If you want portability, you can use multiple backends and choose between them either at compile time -or at runtime. +If you want portability, you can use multiple backends and choose between them either at compile time +or at runtime. **Example A**: your engine is built over Windows + DirectX11 but you have your own high-level rendering system layered over DirectX11.
Suggestion: try using imgui_impl_win32.cpp + imgui_impl_dx11.cpp first. -Once it works, if you really need it you can replace the imgui_impl_dx11.cpp code with a +Once it works, if you really need it you can replace the imgui_impl_dx11.cpp code with a custom renderer using your own rendering functions, and keep using the standard Win32 code etc. **Example B**: your engine runs on Windows, Mac, Linux and uses DirectX11, Metal, Vulkan respectively.
Suggestion: use multiple generic backends! Once it works, if you really need it you can replace parts of backends with your own abstractions. -**Example C**: your engine runs on platforms we can't provide public backends for (e.g. PS4/PS5, Switch), +**Example C**: your engine runs on platforms we can't provide public backends for (e.g. PS4/PS5, Switch), and you have high-level systems everywhere.
Suggestion: try using a non-portable backend first (e.g. win32 + underlying graphics API) to get your desktop builds working first. This will get you running faster and get your acquainted with how Dear ImGui works and is setup. You can then rewrite a custom backend using your own engine API. Also: -The [multi-viewports feature](https://github.com/ocornut/imgui/issues/1542) of the 'docking' branch allows -Dear ImGui windows to be seamlessly detached from the main application window. This is achieved using an -extra layer to the Platform and Renderer backends, which allows Dear ImGui to communicate platform-specific -requests such as: "create an additional OS window", "create a render context", "get the OS position of this +The [multi-viewports feature](https://github.com/ocornut/imgui/issues/1542) of the 'docking' branch allows +Dear ImGui windows to be seamlessly detached from the main application window. This is achieved using an +extra layer to the Platform and Renderer backends, which allows Dear ImGui to communicate platform-specific +requests such as: "create an additional OS window", "create a render context", "get the OS position of this window" etc. See 'ImGuiPlatformIO' for details. -Supporting the multi-viewports feature correctly using 100% of your own abstractions is more difficult +Supporting the multi-viewports feature correctly using 100% of your own abstractions is more difficult than supporting single-viewport. If you decide to use unmodified imgui_impl_XXXX.cpp files, you can automatically benefit from improvements and fixes related to viewports and platform windows without extra work on your side. diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt index d335a07c..950e9ad0 100644 --- a/docs/CHANGELOG.txt +++ b/docs/CHANGELOG.txt @@ -76,7 +76,7 @@ Other Changes: - Metrics: Fixed mishandling of ImDrawCmd::VtxOffset in wireframe mesh renderer. - Metrics: Rebranded as "Dear ImGui Metrics/Debugger" to clarify its purpose. - Misc: Made the ItemFlags stack shared, so effectively the ButtonRepeat/AllowKeyboardFocus states - (and others exposed in internals such as PushItemFlag) are inherited by stacked Begin/End pairs, + (and others exposed in internals such as PushItemFlag) are inherited by stacked Begin/End pairs, vs previously a non-child stacked Begin() would reset those flags back to zero for the stacked window. - Misc: Replaced UTF-8 decoder with one based on branchless one by Christopher Wellons. [@rokups] Super minor fix handling incomplete UTF-8 contents: if input does not contain enough bytes, decoder @@ -93,6 +93,7 @@ Other Changes: - Backends: OSX: Fix keypad-enter key not working on MacOS. (#3554) [@rokups, @lfnoise] - Examples: Apple+Metal: Consolidated/simplified to get closer to other examples. (#3543) [@warrenm] - Examples: Apple+Metal: Forward events down so OS key combination like Cmd+Q can work. (#3554) [@rokups] +- Examples: Emscripten: Renamed example_emscripten/ to example_emscripten_opengl3/. (#3632) - CI: Fix testing for Windows DLL builds. (#3603, #3601) [@iboB] - Docs: Split examples/README.txt into docs/BACKENDS.md and docs/EXAMPLES.md improved them. - Docs: Consistently renamed all occurences of "binding" and "back-end" to "backend" in comments and docs. diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index d318bd35..d6fac021 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -2,7 +2,7 @@ _(You may browse this at https://github.com/ocornut/imgui/blob/master/docs/EXAMP ## Dear ImGui: Examples -**The [examples/](https://github.com/ocornut/imgui/blob/master/examples) folder example applications (standalone, ready-to-build) for variety of +**The [examples/](https://github.com/ocornut/imgui/blob/master/examples) folder example applications (standalone, ready-to-build) for variety of platforms and graphics APIs.** They all use standard backends from the [backends/](https://github.com/ocornut/imgui/blob/master/backends) folder. You can find Windows binaries for some of those example applications at: @@ -13,7 +13,7 @@ You can find Windows binaries for some of those example applications at: Integration in a typical existing application, should take <20 lines when using standard backends. - At initialization: + At initialization: call ImGui::CreateContext() call ImGui_ImplXXXX_Init() for each backend. @@ -35,11 +35,11 @@ Example (using [backends/imgui_impl_win32.cpp](https://github.com/ocornut/imgui/ ImGui::CreateContext(); ImGuiIO& io = ImGui::GetIO(); io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard; // Enable some options - + // Initialize Platform + Renderer backends (here: using imgui_impl_win32.cpp + imgui_impl_dx11.cpp) ImGui_ImplWin32_Init(my_hwnd); ImGui_ImplDX11_Init(my_d3d_device, my_d3d_device_context); - + // Application main loop while (true) { @@ -47,10 +47,10 @@ Example (using [backends/imgui_impl_win32.cpp](https://github.com/ocornut/imgui/ ImGui_ImplDX11_NewFrame(); ImGui_ImplWin32_NewFrame(); ImGui::NewFrame(); - + // Any application code here ImGui::Text("Hello, world!"); - + // End of frame: render Dear ImGui ImGui::Render(); ImGui_ImplDX11_RenderDrawData(ImGui::GetDrawData()); @@ -68,7 +68,7 @@ Please read 'PROGRAMMER GUIDE' in imgui.cpp for notes on how to setup Dear ImGui Please read the comments and instruction at the top of each file. Please read FAQ at http://www.dearimgui.org/faq -If you are using of the backend provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h) +If you are using of the backend provided here, you can add the backends/imgui_impl_xxxx(.cpp,.h) files to your project and use as-in. Each imgui_impl_xxxx.cpp file comes with its own individual Changelog, so if you want to update them later it will be easier to catch up with what changed. @@ -82,8 +82,8 @@ Allegro 5 example.
[example_apple_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_metal/)
OSX & iOS + Metal example.
= main.m + imgui_impl_osx.mm + imgui_impl_metal.mm
-It is based on the "cross-platform" game template provided with Xcode as of Xcode 9. -(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends. +It is based on the "cross-platform" game template provided with Xcode as of Xcode 9. +(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends. You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.) [example_apple_opengl2/](https://github.com/ocornut/imgui/blob/master/examples/example_apple_opengl2/)
@@ -92,7 +92,7 @@ OSX + OpenGL2 example.
(NB: imgui_impl_osx.mm is currently not as feature complete as other platforms backends. You may prefer to use the GLFW Or SDL backends, which will also support Windows and Linux.) -[example_emscripten/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten/)
+[example_emscripten_opengl3/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten_opengl3/)
Emcripten + SDL2 + OpenGL3+/ES2/ES3 example.
= main.cpp + imgui_impl_sdl.cpp + imgui_impl_opengl3.cpp
Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten. @@ -220,7 +220,7 @@ to the right spot at the time of EndFrame()/Render(). At 60 FPS your experience However, consider that OS mouse cursors are typically drawn through a very specific hardware accelerated path and will feel smoother than the majority of contents rendered via regular graphics API (including, -but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane +but not limited to Dear ImGui windows). Because UI rendering and interaction happens on the same plane as the mouse, that disconnect may be jarring to particularly sensitive users. You may experiment with enabling the io.MouseDrawCursor flag to request Dear ImGui to draw a mouse cursor using the regular graphics API, to help you visualize the difference between a "hardware" cursor and a diff --git a/examples/example_emscripten/Makefile b/examples/example_emscripten_opengl3/Makefile similarity index 95% rename from examples/example_emscripten/Makefile rename to examples/example_emscripten_opengl3/Makefile index 967d61fb..06baf499 100644 --- a/examples/example_emscripten/Makefile +++ b/examples/example_emscripten_opengl3/Makefile @@ -7,15 +7,15 @@ # (On Windows, you may need to execute emsdk_env.bat or encmdprompt.bat ahead) # # Running `make` will produce three files: -# - example_emscripten.html -# - example_emscripten.js -# - example_emscripten.wasm +# - example_emscripten_opengl3.html +# - example_emscripten_opengl3.js +# - example_emscripten_opengl3.wasm # # All three are needed to run the demo. CC = emcc CXX = em++ -EXE = example_emscripten.html +EXE = example_emscripten_opengl3.html IMGUI_DIR = ../.. SOURCES = main.cpp SOURCES += $(IMGUI_DIR)/imgui.cpp $(IMGUI_DIR)/imgui_demo.cpp $(IMGUI_DIR)/imgui_draw.cpp $(IMGUI_DIR)/imgui_widgets.cpp diff --git a/examples/example_emscripten/README.md b/examples/example_emscripten_opengl3/README.md similarity index 89% rename from examples/example_emscripten/README.md rename to examples/example_emscripten_opengl3/README.md index 01a4e35e..b6b8737d 100644 --- a/examples/example_emscripten/README.md +++ b/examples/example_emscripten_opengl3/README.md @@ -4,14 +4,14 @@ - You need to install Emscripten from https://emscripten.org/docs/getting_started/downloads.html, and have the environment variables set, as described in https://emscripten.org/docs/getting_started/downloads.html#installation-instructions - You may also refer to our [Continuous Integration setup](https://github.com/ocornut/imgui/tree/master/.github/workflows) for Emscripten setup. - Depending on your configuration, in Windows you may need to run `emsdk/emsdk_env.bat` in your console to access the Emscripten command-line tools. -- Then build using `make` while in the `example_emscripten/` directory. +- Then build using `make` while in the `example_emscripten_opengl3/` directory. ## How to Run To run on a local machine: - Generally you may need a local webserver. Quoting [https://emscripten.org/docs/getting_started](https://emscripten.org/docs/getting_started/Tutorial.html#generating-html):
_"Unfortunately several browsers (including Chrome, Safari, and Internet Explorer) do not support file:// [XHR](https://emscripten.org/docs/site/glossary.html#term-xhr) requests, and can’t load extra files needed by the HTML (like a .wasm file, or packaged file data as mentioned lower down). For these browsers you’ll need to serve the files using a [local webserver](https://emscripten.org/docs/getting_started/FAQ.html#faq-local-webserver) and then open http://localhost:8000/hello.html."_ -- Emscripten SDK has a handy `emrun` command: `emrun example_emscripten.html` which will spawn a temporary local webserver. See https://emscripten.org/docs/compiling/Running-html-files-with-emrun.html for details. +- Emscripten SDK has a handy `emrun` command: `emrun example_emscripten_opengl3.html` which will spawn a temporary local webserver. See https://emscripten.org/docs/compiling/Running-html-files-with-emrun.html for details. - Otherwise you may use Python builtin webserver: `python -m http.server` in Python 3 or `python -m SimpleHTTPServer` in Python 2. After doing that, you can visit http://localhost:8000/. ## Obsolete features: diff --git a/examples/example_emscripten/main.cpp b/examples/example_emscripten_opengl3/main.cpp similarity index 100% rename from examples/example_emscripten/main.cpp rename to examples/example_emscripten_opengl3/main.cpp diff --git a/examples/example_emscripten/shell_minimal.html b/examples/example_emscripten_opengl3/shell_minimal.html similarity index 100% rename from examples/example_emscripten/shell_minimal.html rename to examples/example_emscripten_opengl3/shell_minimal.html