Backends, Examples: Added support for WebGPU and corresponding example (#3632)

(Squashed 11 commits)

.github/workflows/build.yml

@@ -400,6 +400,13 @@ jobs:
         popd
         make -C examples/example_emscripten_opengl3
 
+    - name: Build example_emscripten_wgpu
+      run: |
+        pushd emsdk-master
+        source ./emsdk_env.sh
+        popd
+        make -C examples/example_emscripten_wgpu
+
   Discord-CI:
     runs-on: ubuntu-18.04
     if: always()

backends/imgui_impl_wgpu.h

@@ -0,0 +1,26 @@
+// dear imgui: Renderer for WebGPU
+// This needs to be used along with a Platform Binding (e.g. GLFW)
+
+// Implemented features:
+//  [X] Renderer: User texture binding. Use 'WGPUTextureView' as ImTextureID. Read the FAQ about ImTextureID!
+//  [X] Renderer: Support for large meshes (64k+ vertices) with 16-bit indices.
+
+// You can copy and use unmodified imgui_impl_* files in your project. See examples/ folder for examples of using this.
+// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
+// Read online: https://github.com/ocornut/imgui/tree/master/docs
+
+#pragma once
+#include "imgui.h"      // IMGUI_IMPL_API
+
+// WebGPU
+#include <webgpu/webgpu.h>
+
+// cmd_list is the command list that the implementation will use to render imgui draw lists.
+IMGUI_IMPL_API bool ImGui_ImplWGPU_Init(WGPUDevice device, int num_frames_in_flight, WGPUTextureFormat rt_format);
+IMGUI_IMPL_API void ImGui_ImplWGPU_Shutdown();
+IMGUI_IMPL_API void ImGui_ImplWGPU_NewFrame();
+IMGUI_IMPL_API void ImGui_ImplWGPU_RenderDrawData(ImDrawData* draw_data, WGPURenderPassEncoder pass_encoder);
+
+// Use if you want to reset your rendering device without losing Dear ImGui state.
+IMGUI_IMPL_API void ImGui_ImplWGPU_InvalidateDeviceObjects();
+IMGUI_IMPL_API bool ImGui_ImplWGPU_CreateDeviceObjects();

docs/BACKENDS.md

@@ -68,6 +68,7 @@ List of Renderer Backends:
     imgui_impl_opengl2.cpp    ; OpenGL 2 (legacy, fixed pipeline <- don't use with modern OpenGL context)
     imgui_impl_opengl3.cpp    ; OpenGL 3/4, OpenGL ES 2, OpenGL ES 3 (modern programmable pipeline)
     imgui_impl_vulkan.cpp     ; Vulkan
+    imgui_impl_wgpu.cpp       ; WebGPU
 
 List of high-level Frameworks Backends (combining Platform + Renderer):
 

docs/CHANGELOG.txt

@@ -94,6 +94,7 @@ Breaking Changes:
   confusion with Tables API. Keep redirection enums (will obsolete). (#125, #513, #913, #1204, #1444, #2142, #2707)
 - Renamed io.ConfigWindowsMemoryCompactTimer to io.ConfigMemoryCompactTimer as the feature now applies
   to other data structures. (#2636)
+- Backends: WebGPU: Added backend for WebGPU support in imgui_impl_wgpu [@bfierz]
 
 Other Changes:
 

docs/EXAMPLES.md

@@ -98,6 +98,10 @@ Emcripten + SDL2 + OpenGL3+/ES2/ES3 example. <BR>
 Note that other examples based on SDL or GLFW + OpenGL could easily be modified to work with Emscripten.
 We provide this to make the Emscripten differences obvious, and have them not pollute all other examples.
 
+[example_emscripten_wgpu/](https://github.com/ocornut/imgui/blob/master/examples/example_emscripten_wgpu/) <BR>
+Emcripten + GLFW + WebGPU example. <BR>
+= main.cpp + imgui_impl_glfw.cpp + imgui_impl_wgpu.cpp
+
 [example_glfw_metal/](https://github.com/ocornut/imgui/blob/master/examples/example_glfw_metal/) <BR>
 GLFW (Mac) + Metal example. <BR>
 = main.mm + imgui_impl_glfw.cpp + imgui_impl_metal.mm

examples/example_emscripten_wgpu/Makefile

@@ -0,0 +1,80 @@
+#
+# Makefile to use with emscripten
+# See https://emscripten.org/docs/getting_started/downloads.html
+# for installation instructions.
+#
+# This Makefile assumes you have loaded emscripten's environment.
+# (On Windows, you may need to execute emsdk_env.bat or encmdprompt.bat ahead)
+#
+# Running `make` will produce two files:
+#  - example_emscripten_wgpu.js
+#  - example_emscripten_wgpu.wasm
+#
+# All three are needed to run the demo.
+
+CC = emcc
+CXX = em++
+EXE = example_emscripten_wgpu.js
+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
+SOURCES += $(IMGUI_DIR)/backends/imgui_impl_glfw.cpp $(IMGUI_DIR)/backends/imgui_impl_wgpu.cpp
+OBJS = $(addsuffix .o, $(basename $(notdir $(SOURCES))))
+UNAME_S := $(shell uname -s)
+
+##---------------------------------------------------------------------
+## EMSCRIPTEN OPTIONS
+##---------------------------------------------------------------------
+
+EMS += -s USE_GLFW=3 -s USE_WEBGPU=1 -s WASM=1
+EMS += -s ALLOW_MEMORY_GROWTH=1
+EMS += -s DISABLE_EXCEPTION_CATCHING=1 -s NO_EXIT_RUNTIME=0
+EMS += -s ASSERTIONS=1
+
+# Emscripten allows preloading a file or folder to be accessible at runtime.
+# The Makefile for this example project suggests embedding the misc/fonts/ folder into our application, it will then be accessible as "/fonts"
+# See documentation for more details: https://emscripten.org/docs/porting/files/packaging_files.html
+# (Default value is 0. Set to 1 to enable file-system and include the misc/fonts/ folder as part of the build.)
+USE_FILE_SYSTEM ?= 0
+ifeq ($(USE_FILE_SYSTEM), 0)
+EMS += -s NO_FILESYSTEM=1 -DIMGUI_DISABLE_FILE_FUNCTIONS
+endif
+ifeq ($(USE_FILE_SYSTEM), 1)
+LDFLAGS += --no-heap-copy --preload-file ../../misc/fonts@/fonts
+endif
+
+##---------------------------------------------------------------------
+## FINAL BUILD FLAGS
+##---------------------------------------------------------------------
+
+CPPFLAGS += -I$(IMGUI_DIR)/ -I$(IMGUI_DIR)/backends
+#CPPFLAGS += -g
+CPPFLAGS += -Wall -Wformat -Os
+CPPFLAGS += $(EMS)
+LIBS += $(EMS)
+#LDFLAGS += --shell-file shell_minimal.html
+
+##---------------------------------------------------------------------
+## BUILD RULES
+##---------------------------------------------------------------------
+
+%.o:%.cpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $<
+
+%.o:../%.cpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $<
+
+%.o:$(IMGUI_DIR)/%.cpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $<
+
+%.o:$(IMGUI_DIR)/backends/%.cpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $<
+
+all: $(EXE)
+	@echo Build complete for $(EXE)
+
+$(EXE): $(OBJS)
+	$(CXX) -o $@ $^ $(LIBS) $(LDFLAGS)
+
+clean:
+	rm -f $(EXE) $(OBJS) *.js *.wasm *.wasm.pre

examples/example_emscripten_wgpu/README.md

@@ -0,0 +1,10 @@
+
+# How to Build
+
+- 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
+
+- 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_wgpu/` directory.
+
+- Requires Emscripten 2.0.10 (December 2020) due to GLFW adaptations

examples/example_emscripten_wgpu/example_emscripten_wgpu.html

@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en-us">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no"/>
+    <title>Dear ImGui Emscripten example</title>
+    <style>
+        body { margin: 0; background-color: black }
+        .emscripten {
+            position: absolute;
+            top: 0px;
+            left: 0px;
+            margin: 0px;
+            border: 0;
+            width: 100%;
+            height: 100%;
+            overflow: hidden;
+            display: block;
+            image-rendering: optimizeSpeed;
+            image-rendering: -moz-crisp-edges;
+            image-rendering: -o-crisp-edges;
+            image-rendering: -webkit-optimize-contrast;
+            image-rendering: optimize-contrast;
+            image-rendering: crisp-edges;
+            image-rendering: pixelated;
+            -ms-interpolation-mode: nearest-neighbor;
+        }
+    </style>
+  </head>
+  <body>
+    <canvas class="emscripten" id="canvas" oncontextmenu="event.preventDefault()"></canvas>
+    <script type='text/javascript'>
+      var Module;
+      (async () => {
+        Module = {
+          preRun: [],
+          postRun: [],
+          print: (function() {
+              return function(text) {
+                  text = Array.prototype.slice.call(arguments).join(' ');
+                  console.log(text);
+              };
+          })(),
+          printErr: function(text) {
+              text = Array.prototype.slice.call(arguments).join(' ');
+              console.error(text);
+          },
+          canvas: (function() {
+              var canvas = document.getElementById('canvas');
+              //canvas.addEventListener("webglcontextlost", function(e) { alert('FIXME: WebGL context lost, please reload the page'); e.preventDefault(); }, false);
+              return canvas;
+          })(),
+          setStatus: function(text) {
+              console.log("status: " + text);
+          },
+          monitorRunDependencies: function(left) {
+              // no run dependencies to log
+          }
+        };
+        window.onerror = function() {
+          console.log("onerror: " + event);
+        };
+
+      // Initialize the graphics adapter
+      {
+          const adapter = await navigator.gpu.requestAdapter();
+          const device = await adapter.requestDevice();
+          Module.preinitializedWebGPUDevice = device;
+      }
+
+      {
+          const js = document.createElement('script');
+          js.async = true;
+          js.src = "example_emscripten_wgpu.js";
+          document.body.appendChild(js);
+      }
+      })();
+    </script>
+  </body>
+</html>

examples/example_emscripten_wgpu/main.cpp

@@ -0,0 +1,257 @@
+// Dear ImGui: standalone example application for Emscripten, using GLFW + WebGPU
+// (Emscripten is a C++-to-javascript compiler, used to publish executables for the web. See https://emscripten.org/)
+// If you are new to Dear ImGui, read documentation from the docs/ folder + read the top of imgui.cpp.
+// Read online: https://github.com/ocornut/imgui/tree/master/docs
+
+// This is mostly the same code as the SDL2 + OpenGL3 example, simply with the modifications needed to run on Emscripten.
+// It is possible to combine both code into a single source file that will compile properly on Desktop and using Emscripten.
+// See https://github.com/ocornut/imgui/pull/2492 as an example on how to do just that.
+
+#include "imgui.h"
+#include "imgui_impl_glfw.h"
+#include "imgui_impl_wgpu.h"
+#include <stdio.h>
+#include <emscripten.h>
+#include <emscripten/html5.h>
+#include <emscripten/html5_webgpu.h>
+#include <GLFW/glfw3.h>
+#include <webgpu/webgpu.h>
+#include <webgpu/webgpu_cpp.h>
+
+// Global WebGPU required states
+static WGPUDevice    wgpu_device = NULL;
+static WGPUSurface   wgpu_surface = NULL;
+static WGPUSwapChain wgpu_swap_chain = NULL;
+
+static int           wgpu_swap_chain_width = 0;
+static int           wgpu_swap_chain_height = 0;
+
+// States tracked across render frames
+static bool show_demo_window = true;
+static bool show_another_window = false;
+static ImVec4 clear_color = ImVec4(0.45f, 0.55f, 0.60f, 1.00f);
+
+// Forward declartions
+bool init_wgpu();
+void main_loop(void* window);
+void print_glfw_error(int error, const char* description);
+void print_wgpu_error(WGPUErrorType error_type, const char* message, void*);
+
+int main(int, char**)
+{
+    glfwSetErrorCallback(print_glfw_error);
+    if (!glfwInit())
+        return 1;
+
+    // Make sure GLFW does not initialize any graphics context.
+    // This needs to be done explicitly later
+    glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
+
+    GLFWwindow* window = glfwCreateWindow(1280, 720, "Dear ImGui GLFW+WebGPU example", NULL, NULL);
+    if (!window) {
+        glfwTerminate();
+        return 1;
+    }
+
+    // Initialize the WebGPU environment
+    if (!init_wgpu()) {
+        if (window)
+            glfwDestroyWindow(window);
+        glfwTerminate();
+        return 1;
+    }
+    glfwShowWindow(window);
+
+    // Setup Dear ImGui context
+    IMGUI_CHECKVERSION();
+    ImGui::CreateContext();
+    ImGuiIO& io = ImGui::GetIO(); (void)io;
+    //io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;     // Enable Keyboard Controls
+    //io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;      // Enable Gamepad Controls
+
+    // For an Emscripten build we are disabling file-system access, so let's not attempt to do a fopen() of the imgui.ini file.
+    // You may manually call LoadIniSettingsFromMemory() to load settings from your own storage.
+    io.IniFilename = NULL;
+
+    // Setup Dear ImGui style
+    ImGui::StyleColorsDark();
+    //ImGui::StyleColorsClassic();
+
+    // Setup Platform/Renderer backends
+    ImGui_ImplGlfw_InitForVulkan(window, true);
+    ImGui_ImplWGPU_Init(wgpu_device, 3, WGPUTextureFormat_RGBA8Unorm);
+
+    // Load Fonts
+    // - If no fonts are loaded, dear imgui will use the default font. You can also load multiple fonts and use ImGui::PushFont()/PopFont() to select them.
+    // - AddFontFromFileTTF() will return the ImFont* so you can store it if you need to select the font among multiple.
+    // - If the file cannot be loaded, the function will return NULL. Please handle those errors in your application (e.g. use an assertion, or display an error and quit).
+    // - The fonts will be rasterized at a given size (w/ oversampling) and stored into a texture when calling ImFontAtlas::Build()/GetTexDataAsXXXX(), which ImGui_ImplXXXX_NewFrame below will call.
+    // - Read 'docs/FONTS.md' for more instructions and details.
+    // - Remember that in C/C++ if you want to include a backslash \ in a string literal you need to write a double backslash \\ !
+    // - Emscripten allows preloading a file or folder to be accessible at runtime. See Makefile for details.
+    //io.Fonts->AddFontDefault();
+#ifndef IMGUI_DISABLE_FILE_FUNCTIONS
+    io.Fonts->AddFontFromFileTTF("fonts/Roboto-Medium.ttf", 16.0f);
+    //io.Fonts->AddFontFromFileTTF("fonts/Cousine-Regular.ttf", 15.0f);
+    //io.Fonts->AddFontFromFileTTF("fonts/DroidSans.ttf", 16.0f);
+    //io.Fonts->AddFontFromFileTTF("fonts/ProggyTiny.ttf", 10.0f);
+    //ImFont* font = io.Fonts->AddFontFromFileTTF("fonts/ArialUni.ttf", 18.0f, NULL, io.Fonts->GetGlyphRangesJapanese());
+    //IM_ASSERT(font != NULL);
+#endif
+
+    // This function will directly return and extit he main function.
+    // Make sure that no required objects get cleaned up.
+    // This way we can use the browsers 'requestAnimationFrame' to control the rendering.
+    emscripten_set_main_loop_arg(main_loop, window, 0, false);
+
+    return 0;
+}
+
+bool init_wgpu()
+{
+    wgpu_device = emscripten_webgpu_get_device();
+    if (!wgpu_device)
+        return false;
+
+    wgpuDeviceSetUncapturedErrorCallback(wgpu_device, print_wgpu_error, nullptr);
+
+    // Use C++ wrapper due to malbehaviour in Emscripten.
+    // Some offset computation for wgpuInstanceCreateSurface in JavaScript
+    // seem to be inline with struct alignments in the C++ structure
+    wgpu::SurfaceDescriptorFromCanvasHTMLSelector html_surface_desc{};
+    html_surface_desc.selector = "#canvas";
+
+    wgpu::SurfaceDescriptor surface_desc{};
+    surface_desc.nextInChain = &html_surface_desc;
+
+    // Use 'null' instance
+    wgpu::Instance instance{};
+    wgpu_surface = instance.CreateSurface(&surface_desc).Release();
+
+    return true;
+}
+
+void main_loop(void* window)
+{
+    glfwPollEvents();
+
+    int width, height;
+    glfwGetFramebufferSize((GLFWwindow*) window, &width, &height);
+
+    // React to changes in screen size
+    if (width != wgpu_swap_chain_width && height != wgpu_swap_chain_height)
+    {
+        ImGui_ImplWGPU_InvalidateDeviceObjects();
+
+        if (wgpu_swap_chain)
+            wgpuSwapChainRelease(wgpu_swap_chain);
+
+        wgpu_swap_chain_width = width;
+        wgpu_swap_chain_height = height;
+
+        WGPUSwapChainDescriptor swap_chain_desc = {};
+        swap_chain_desc.usage = WGPUTextureUsage_OutputAttachment;
+        swap_chain_desc.format = WGPUTextureFormat_RGBA8Unorm;
+        swap_chain_desc.width = width;
+        swap_chain_desc.height = height;
+        swap_chain_desc.presentMode = WGPUPresentMode_Fifo;
+        wgpu_swap_chain = wgpuDeviceCreateSwapChain(wgpu_device, wgpu_surface, &swap_chain_desc);
+
+        ImGui_ImplWGPU_CreateDeviceObjects();
+    }
+
+    // Start the Dear ImGui frame
+    ImGui_ImplWGPU_NewFrame();
+    ImGui_ImplGlfw_NewFrame();
+    ImGui::NewFrame();
+
+    // 1. Show the big demo window (Most of the sample code is in ImGui::ShowDemoWindow()! You can browse its code to learn more about Dear ImGui!).
+    if (show_demo_window)
+        ImGui::ShowDemoWindow(&show_demo_window);
+
+    // 2. Show a simple window that we create ourselves. We use a Begin/End pair to created a named window.
+    {
+        static float f = 0.0f;
+        static int counter = 0;
+
+        ImGui::Begin("Hello, world!");                                // Create a window called "Hello, world!" and append into it.
+
+        ImGui::Text("This is some useful text.");                     // Display some text (you can use a format strings too)
+        ImGui::Checkbox("Demo Window", &show_demo_window);            // Edit bools storing our window open/close state
+        ImGui::Checkbox("Another Window", &show_another_window);
+
+        ImGui::SliderFloat("float", &f, 0.0f, 1.0f);                  // Edit 1 float using a slider from 0.0f to 1.0f
+        ImGui::ColorEdit3("clear color", (float*)&clear_color);       // Edit 3 floats representing a color
+
+        if (ImGui::Button("Button"))                                  // Buttons return true when clicked (most widgets return true when edited/activated)
+            counter++;
+        ImGui::SameLine();
+        ImGui::Text("counter = %d", counter);
+
+        ImGui::Text("Application average %.3f ms/frame (%.1f FPS)", 1000.0f / ImGui::GetIO().Framerate, ImGui::GetIO().Framerate);
+        ImGui::End();
+    }
+
+    // 3. Show another simple window.
+    if (show_another_window)
+    {
+        ImGui::Begin("Another Window", &show_another_window);         // Pass a pointer to our bool variable (the window will have a closing button that will clear the bool when clicked)
+        ImGui::Text("Hello from another window!");
+        if (ImGui::Button("Close Me"))
+            show_another_window = false;
+        ImGui::End();
+    }
+    
+    // Render the generated ImGui frame
+    ImGui::Render();
+
+    WGPURenderPassColorAttachmentDescriptor color_attachments = {};
+    color_attachments.loadOp = WGPULoadOp_Clear;
+    color_attachments.storeOp = WGPUStoreOp_Store;
+    color_attachments.clearColor = { clear_color.x, clear_color.y, clear_color.z, clear_color.w };
+    color_attachments.attachment = wgpuSwapChainGetCurrentTextureView(wgpu_swap_chain);
+    WGPURenderPassDescriptor render_pass_desc = {};
+    render_pass_desc.colorAttachmentCount = 1;
+    render_pass_desc.colorAttachments = &color_attachments;
+    render_pass_desc.depthStencilAttachment = nullptr;
+
+    WGPUCommandEncoderDescriptor enc_desc = {};
+    WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(wgpu_device, &enc_desc);
+
+    WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder, &render_pass_desc);
+    ImGui_ImplWGPU_RenderDrawData(ImGui::GetDrawData(), pass);
+    wgpuRenderPassEncoderEndPass(pass);
+
+    WGPUCommandBufferDescriptor cmd_buffer_desc = {};
+    WGPUCommandBuffer cmd_buffer = wgpuCommandEncoderFinish(encoder, &cmd_buffer_desc);
+    WGPUQueue queue = wgpuDeviceGetDefaultQueue(wgpu_device);
+    wgpuQueueSubmit(queue, 1, &cmd_buffer);
+}
+
+void print_glfw_error(int error, const char* description)
+{
+    printf("Glfw Error %d: %s\n", error, description);
+}
+
+void print_wgpu_error(WGPUErrorType error_type, const char* message, void*)
+{
+    const char* error_type_lbl = "";
+    switch (error_type) {
+    case WGPUErrorType_Validation:
+        error_type_lbl = "Validation";
+        break;
+    case WGPUErrorType_OutOfMemory:
+        error_type_lbl = "Out of memory";
+        break;
+    case WGPUErrorType_Unknown:
+        error_type_lbl = "Unknown";
+        break;
+    case WGPUErrorType_DeviceLost:
+        error_type_lbl = "Device lost";
+        break;
+    default:
+        error_type_lbl = "Unknown";
+    }
+
+    printf("%s error: %s\n", error_type_lbl, message);
+}