DOCSEARCHbyAlgolia
Submit Docs

NetImgui

repository·master·Indexed 20 days ago

https://github.com/sammyfreg/netimgui

A C++ library that enables remote display and control of Dear ImGui menus. It uses a client-server model to forward UI rendering (textures, vertices, indices, and draw commands) from a C++ application to a separate server application for display, facilitating UI for headless servers, devices without native displays, or remote debug windows.

Tokens
1.9K
Snippets
4
Records
12
Agent score
72%

What's inside NetImgui

  1. Overview of NetImgui

    master

    NetImgui is a library designed to remotely display and control Dear ImGui menus using an associated NetImgui Server application. It allows a C++ program (the Client) to receive input from a remote PC and forward its UI rendering (textures, vertices, indices, and draw commands) to that PC for display.

    This is particularly useful for:

    • Providing UI for devices without native displays or input (e.g., Raspberry Pi, headless servers).
    • Improving ease of use for text input or complex controls on devices like game consoles or VR headsets.
    • Decluttering the local display by moving debug UI to a separate remote window.

  2. How NetImgui works

    master

    NetImgui operates via a Client-Server model:

    1. NetImgui Server: Captures user mouse/keyboard inputs.
    2. NetImgui Server: Sends inputs to the client and requests a draw update.
    3. NetImgui Client: Draws the Dear ImGui content normally (without needing a local display).
    4. NetImgui Client: Sends the drawing results (vertices, indices, textures, etc.) to the server.
    5. NetImgui Server: Receives the drawing results and displays them in a window.
    6. The cycle repeats.

  3. Connection methods between Server and Client

    master

    There are four ways to establish a connection between the NetImgui Server and a netImGui Client:

    1. Server waits for connection: The Client calls ConnectToApp() providing the Server's address.
    2. Client waits for connection (Server-initiated): The Client calls ConnectFromApp(), and the Server is configured with the Client's address to connect to it.
    3. Client waits for connection (Command line): The Client calls ConnectFromApp(), and the Server is launched with the Client's address passed as a command-line argument.
    4. Client waits for connection (Named Pipe): The Server receives the Client's address from another application via a Windows named pipe: \\.\pipe\netImgui.

  4. Generate compatibility tests for older Dear ImGui versions

    master

    If you need to test the compatibility of NetImgui against older versions of Dear ImGui, you can run the compatibility test generation script.

    • Windows: Run GenerateCompatibilityTest.bat
    GenerateCompatibilityTest.bat

  5. Generate NetImgui projects

    master

    To generate the various NetImgui projects, run the appropriate generation script for your operating system. Most users should only interact with these scripts and can otherwise ignore the contents of the Build/ folder.

    • Windows: Run GenerateProject.bat
    • macOS: Run GenerateProject.sh
    # On Windows
GenerateProject.bat

# On macOS
./GenerateProject.sh

  6. Configure Visual Studio Debugger with Natstepfilter and Natvis

    master

    To improve the debugging experience in Visual Studio, use the following helper files:

    1. imgui.natstepfilter: Use this to disable stepping into trivial functions.
    2. imgui.natvis: Use this to provide better visual descriptions of Dear ImGui types. For example, it allows types like ImVector<> to be displayed in a human-readable format within the debugger windows.

    Refer to the comments inside each file for detailed setup instructions.

  7. Integrate NetImgui into your codebase

    master

    To use NetImgui in your C++ project, follow these steps:

    1. Download the latest version of the NetImgui library.
    2. Add the contents of the Code\Client directory to your codebase.
    3. Initialization (Once at program start/exit):
      • Call NetImgui::Startup() at the beginning of your program.
      • Call NetImgui::Shutdown() at the end of your program.
      • Call either NetImgui::ConnectToApp() or NetImgui::ConnectFromApp() to establish the connection.
    4. Per-Frame Logic (Every redraw):
      • Draw your ImGui menu as usual.
      • Important for Dear ImGui 1.80 and lower (or for frameskip support):
        • Replace ImGui::NewFrame() with NetImgui::NewFrame().
        • Replace ImGui::Render() or ImGui::EndFrame() with NetImgui::EndFrame().
    5. Start the NetImgui server application and connect your application to it.
    // Initialization
NetImgui::Startup();
NetImgui::ConnectToApp(); // Or ConnectFromApp()

// Main Loop
while (running) {
    // If using older ImGui versions or needing frameskip:
    NetImgui::NewFrame();
    
    // Your standard ImGui code
    ImGui::Begin("Remote Menu");
    ImGui::Text("Hello from Client!");
    ImGui::End();

    NetImgui::EndFrame();
}

// Cleanup
NetImgui::Shutdown();

  10. Selective UI rendering with IsConnected and IsDrawingRemote

    master

    You can use the following functions during your Dear ImGui drawing code to make decisions about which UI elements to show locally versus remotely:

    • NetImgui::IsConnected(): Checks if a connection to the server is active.
    • NetImgui::IsDrawingRemote(): Checks if the current drawing is being sent to a remote display.

  11. API changes in NetImgui v1.13

    master

    Version 1.13 introduced several changes to the API:

    • NetImgui::SetBackground(...): Now supports a new ImTextureRef parameter.
    • NetImgui::eTexFormat: The enum entries have been shuffled.
    • Font Creation Callback: The FontCreation callback parameter in ConnectToApp(...) and ConnectFromApp(...) is now ignored if you are using Dear ImGui 1.92+. This is because 1.92+ handles the font atlas differently (containing only needed glyphs), making manual regeneration on DPI change unnecessary. If you implemented this callback for older versions, it can be safely removed when moving to 1.92+.
    • Custom Texture Format: This feature has been disabled to allow transmitting data for user-managed custom texture formats, though full functionality is pending updates to the texture system.

  12. View netImguiApp resource identifiers

    master

    The netImguiApp.rc file defines several resource identifiers used by the ServerApp component. These identifiers are used for application icons, menu structures, accelerators, and string tables within the Windows environment.

    // Icon Identifiers
IDI_NETIMGUIAPP    ICON    "netImguiApp.ico"
IDI_SMALL          ICON    "small.ico"

// Menu Identifiers
IDC_NETIMGUIAPP    MENU
BEGIN
    MENUITEM "&Exit", IDM_EXIT
END

// Accelerator Identifiers
IDC_NETIMGUIAPP    ACCELERATORS
BEGIN
    "?", IDM_ABOUT, ASCII, ALT
    "/", IDM_ABOUT, ASCII, ALT
END

// String Table Identifiers
IDS_APP_TITLE      "netImgui"
IDC_NETIMGUIAPP    "NETIMGUIAPP"