Skip to content

Home

Jump to bottom
Sammy Fatnassi edited this page Jan 22, 2021 · 15 revisions

Integration

Setup

  1. Copy the sources files in .\Code\Client\ to your codebase and add them to your build process.
  2. (Optional) Generate the solutions with .\Build\GenerateProject.bat after downloading the sources from the NetImgui Git depot.
    • Note : Outputed to .\Build\projects\

Integration

  1. Edit 'NetImgui_Config.h' with the valid path to your Dear ImGui header file : #include <imgui.h>.

    • Note : Your project should now compile

  2. On platforms without support for either Winsocks or POSIX, the functions declared in 'NetImgui_Network.h' needs to be implemented.

    • Allows data exchange between the NetImgui server and your application using socket connection.
    • 'NetImgui_NetworkWin32.cpp' can be used as a reference.

Note : Every memory allocations done by NetImgui Client code are using the Dear ImGui allocator. Note : For user wanting to minimize changes to their project, by adding #define NETIMGUI_IMPLEMENTATION once, before #include NetImgui_Api.h, all needed source files will also be added for compilation.

Changes to codebase

Very few changes needed when displaying same local Dear ImGui content on the remote NetImgui server.

Note 1: 'vs2019_netImgui_Sample.sln' offers a good example of integrating NetImgui to a codebase, 'SampleBasic.cpp' source file in particular.

1. [Init]
  • In your program startup, add a call to : NetImgui::Startup()
2. [Connect]

  • In your program startup (or potentially elsewhere), add a call to : NetImgui::ConnectToApp() or NetImgui::ConnectFromApp()

  • Note 1: Connection can be initiated from either the Server (ConnectFromApp) or Client (ConnectToApp), it is up to the integrater to decide which one they prefer.

  • Note 2: When initializing a connection, a new communication thread will be created using std::thread by default. A custom threading implementation can be used instead, by providing a callback function to the connection function.

  • Note 3: The connection status can be determined with : NetImgui::IsConnected() and NetImgui::IsConnectionPending().

3. [Send Texture]
  • Textures used by your Dear ImGui menus need to be forwarded to the netImgui server using NetImgui::SendDataTexture() (otherwise, content using it will be invisible).
  • The Font texture is automatically forwarded to the NetImgui Server if the Dear Imgui Font data hasn't been cleared. Otherwise, you will need to manually send it before releasing the Font.
  • Updating the textures can be done before or after establishing a connection to the netImgui server.
4. [Step Draw]

In your codebase, replace calls to these functions :

  • ImGui::NewFrame() with NetImgui::NewFrame()

  • ImGui::Render() / ImGui::EndFrame() with NetImGui::EndFrame() .

  • Note 1 (Important): When remote drawing, we don't need to update the Dear ImGui content every frame. If your UI drawing code can handle skipping frames, let NetImgui::NewFrame() know and it will returns false when no refresh is expected. NetImgui::IsDrawing() can also be relied on to know about the status. This can reduce CPU usage of updating unused Dear ImGui content.

  • Note 2: NetImgui::IsDrawingRemote() can be used to customize the content when drawing Dear ImGui content.

  • Note 3: It is possible to have content displayed simultaneously on the remote netImgui server and locally, with distinct content on each output. The Sample SampleDualUI has more information.

5. [Step Shutdown]

In your program shutdown, add a call to : NetImgui::Shutdown()

FAQ

  • A connection seems to be sucessfully established, but nothing is drawed on the Server :

  • A missing Font texture is the most likely cause.

  • Either avoid releasing the Dear Imgui's Font data by not calling ImGui::GetIO().Fonts->ClearTexData().

  • Or manually send the texture before releasing the Font data :

unsigned char* pixels(nullptr); int width(0), height(0); ImGui::GetIO().Fonts->GetTexDataAsAlpha8(&pixels, &width, &height); NetImgui::SendDataTexture(ImGui::GetIO().Fonts->TexID, pixels, static_cast<uint16_t>(width), static_cast<uint16_t>(height), NetImgui::eTexFormat::kTexFmtA8);

Clone this wiki locally