Skip to content

docs: concise README (mcpp-style) #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sunrisepeak merged 1 commit into from
Jun 4, 2026
Merged

docs: concise README (mcpp-style) #9

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 57 additions & 167 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,207 +1,97 @@
# imgui

C++23 module package for Dear ImGui on mcpp.

This package uses `compat.imgui` for upstream Dear ImGui sources and provides
module interfaces for the core API plus GLFW/OpenGL3 backend entry points.

## Modules

Three tiers of consumer UX:

- **Tier-0** `imgui.app` — the convenience facade. Owns the whole window/context
lifecycle; you supply only a per-frame UI callback.
- **Tier-1** automatic via the `imgui.backend` contract — write backend-agnostic
code against the `BackendApi` concept and shared types.
- **Tier-2** explicit `imgui.backend.<impl>` — import a concrete backend module
and alias it (`using Backend = ...;`); swap backend with one import + alias.

- `imgui.app`
- Tier-0 facade. `ImGui::App::run(opts, ui)` / `ImGui::App::run(ui)` drive the
full GLFW/OpenGL3 lifecycle using the default backend. `export import`s
`imgui.core` so a consumer gets the `ImGui::*` surface for free.
- `imgui.core`
- Core Dear ImGui context, frame, widget, and draw-data APIs.
- `imgui.backend`
- Generic backend abstraction layer: shared value types (`GlConfig`, `Error`,
`FbSize`), `RecommendedGlConfig()` cross-platform defaults, and the
compile-time `BackendApi` contract every backend satisfies. No platform code.
- `imgui.backend.platform.glfw`
- GLFW platform piece: window/event management + `ImGui_ImplGlfw_*` binding.
- `imgui.backend.renderer.opengl3`
- OpenGL3 renderer piece: GL framebuffer ops + `ImGui_ImplOpenGL3_*` binding.
- `imgui.backend.glfw_opengl3`
- Concrete backend: assembles the GLFW platform and OpenGL3 renderer pieces
into a single `ImGui::Backend::GlfwOpenGL3` type satisfying `BackendApi`.
Re-exports `imgui.backend` (shared types) but **not** `imgui.core`.

Backends expose one `Backend` type with a uniform static API, so swapping
backend is just a different `import` plus a one-line `using Backend = ...;`
alias — the rest of the consumer code is identical. Cross-platform GL/GLSL
configuration (incl. macOS forward-compat) is handled by `RecommendedGlConfig()`,
which `CreateWindow`/`Init` use by default.
> Dear ImGui 的 C++23 模块化封装 — `import` 即用 · 跨平台 · 特性可插拔

## Features

- `docking` — dockable panels inside the main window (Wayland-safe). Exports the Dock* API surface (`DockSpace`, `DockSpaceOverViewport`,
`SetNextWindowDockID`, `IsWindowDocked`, ...) and makes the `imgui.app` facade
enable `ImGuiConfigFlags_DockingEnable` automatically:

```toml
[dependencies]
imgui = { version = "0.0.4", features = ["docking"] }
```

- `viewports` — panels dragged (or positioned) outside the main window detach
into real OS windows (multi-viewport). X11/Windows/macOS; note GLFW/Wayland
does not support it upstream.
- `docking-full = ["docking", "viewports"]` — convenience bundle: the full
docking experience.

```toml
[dependencies]
imgui = { version = "0.0.5", features = ["docking-full"] }
```
[![Release](https://img.shields.io/github/v/release/mcpplibs/imgui-m)](https://github.com/mcpplibs/imgui-m/releases)
[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

See `examples/docking/`. Sources come from upstream's docking tag
(`compat.imgui 1.92.8-docking`, a superset of mainline — identical behavior
while the features are off).
| [mcpp 构建工具](https://github.com/mcpp-community/mcpp) · [包索引 mcpp-index](https://github.com/mcpp-community/mcpp-index) · [Dear ImGui 上游](https://github.com/ocornut/imgui) · [Issues](https://github.com/mcpplibs/imgui-m/issues) · [Releases](https://github.com/mcpplibs/imgui-m/releases) |
|:---:|
| [![CI](https://github.com/mcpplibs/imgui-m/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpplibs/imgui-m/actions/workflows/ci.yml) |

## Dependencies
## 核心特性

The root package depends on:
- **纯模块导入** — `import imgui.core;`,消费者代码零 `#include`
- **三档使用体验** — `imgui.app` 一行出窗口(默认档)/ `imgui.backend` 编译期契约(自动档)/ `imgui.backend.<impl>` 显式选后端(专家档),换后端 = 改一行 import + alias
- **特性可插拔** — `features = ["docking-full"]` 解锁面板停靠 + 拖出主窗口变独立 OS 窗口
- **不绑定工具链、不打包 GL 驱动** — Linux / macOS / Windows 三平台 CI;GL 运行时由 mcpp 生态自动闭合

- `compat.imgui = "1.92.8"`
- `compat.glfw = "3.4"`
- `compat.opengl = "2026.05.31"`

The repository does not vendor Dear ImGui sources. Source and header files come
from compat packages through mcpp dependency metadata.

### Toolchain and GL runtime

The package does not pin a toolchain; mcpp resolves the environment/default
toolchain. The GL runtime is closed by mcpp/mcpp-index (`compat.glx-runtime`,
pulled in transitively by `compat.glfw` on Linux), not bundled by this package.

## Quick Start
## 快速开始

```bash
mcpp build
mcpp test
cd examples/basic
mcpp run
mcpp new myapp --template gui && cd myapp && mcpp run # 窗口直接出现
```

Expected headless example output:

```text
Dear ImGui 1.92.8 module frame ok
```

## Backend Example

The minimal GLFW/OpenGL3 window example uses the combined backend module and
does not use `#include` in consumer code:

```bash
cd examples/minimal_window
mcpp build
mcpp run
```

It requires an OpenGL runtime that is visible to the mcpp/xlings runtime. If
GLFW cannot create the window, the example prints the GLFW error text. The
`compat.opengl` package supplies OpenGL registry/header content; it does not
bundle a platform `libGL`/GLX runtime.

The larger GLFW/OpenGL3 example builds on CI but should be run only in an
environment with a working display and OpenGL context:

```bash
cd examples/glfw_opengl3
mcpp build
mcpp run
```

## Consumer Usage
或在已有项目中手动接入:

```toml
[dependencies]
imgui = "0.0.1"
imgui = "0.0.5"
```

Then import the modules you need.

Tier-0 (`imgui.app` facade — least code):

```cpp
import imgui.core;
import imgui.app;

int main() {
return ImGui::App::run([] {
ImGui::Begin("hi");
ImGui::TextUnformatted("imgui.app facade");
ImGui::Begin("hello");
ImGui::TextUnformatted("mcpp + imgui");
ImGui::End();
});
}
```

Tier-2 (explicit backend module + alias — full control):
## 模块一览

```cpp
import imgui.core;
import imgui.backend.glfw_opengl3;
using Backend = ImGui::Backend::GlfwOpenGL3; // swap import + alias to switch backends
| 模块 | 说明 |
|---|---|
| `imgui.core` | Dear ImGui 核心:context / frame / widgets / draw-data |
| `imgui.app` | Tier-0 facade:平台默认后端 + 一行帧循环 |
| `imgui.backend` | 后端契约:`BackendApi` concept + 共享类型(`GlConfig`/`Error`/`FbSize`) |
| `imgui.backend.glfw_opengl3` | GLFW + OpenGL3 窗口后端(单一 `Backend` 类型) |
| `imgui.backend.headless` | 无显示后端:同一业务循环跑 CI / 逻辑测试 |

int main() {
Backend::InitGlfw();
auto* window = Backend::CreateWindow(960, 540, "demo"); // cross-platform GL hints
Backend::MakeContextCurrent(window);

ImGuiContext* context = ImGui::CreateContext();
ImGui::SetCurrentContext(context);
Backend::Init(window); // RecommendedGlConfig() default
// ... frame loop: Backend::NewFrame / ImGui::* / Backend::RenderDrawData ...
Backend::Shutdown();
ImGui::DestroyContext(context);
Backend::DestroyWindow(window);
Backend::TerminateGlfw();
}
```
后端实现模块**不 re-export** `imgui.core`,消费者需各自显式 `import`;换后端只改 import 行与一行 `using Backend = ...;`。

## Module Surface
## Features

`src/core.cppm` wraps `imgui.h` through a global module fragment and exports a
tested core API surface:
| Feature | 说明 |
|---|---|
| `docking` | 主窗口内面板停靠(Wayland 安全) |
| `viewports` | 面板拖出主窗口分离为独立 OS 窗口(X11 / Windows / macOS) |
| `docking-full` | 组合糖 = `["docking", "viewports"]`,完整 docking 体验 |

- Types: `ImGuiContext`, `ImFontAtlas`, `ImGuiIO`, `ImDrawData`, `ImVec2`,
`ImVec4`.
- Functions: context lifecycle, `GetIO`, `NewFrame`, `Begin`, `Button`,
`TextUnformatted`, `End`, `Render`, and `GetDrawData`.
```toml
[dependencies]
imgui = { version = "0.0.5", features = ["docking-full"] }
```

`imgui.core` exports a curated core subset; for rarely used APIs not yet
exported, a consumer translation unit can still `#include <imgui.h>` directly
alongside the module imports.
docking/viewports 源码来自上游 docking tag(`compat.imgui 1.92.8-docking`,主线超集——特性关闭时行为与主线一致)。需 mcpp ≥ 0.0.47。

Backend modules adapt the official Dear ImGui backend headers internally and
expose a single `Backend` type per backend (uniform static API constrained by
`ImGui::Backend::BackendApi`). Consumer code only needs module imports for the
surfaces exposed by this package.
## 示例

| 示例 | 内容 |
|---|---|
| [`examples/app_minimal`](examples/app_minimal) | facade 三行出窗口 |
| [`examples/docking`](examples/docking) | IDE 式四分屏 + 面板分离为独立 OS 窗口 |
| [`examples/minimal_window`](examples/minimal_window) | 显式后端 API 的最小窗口(带诊断) |
| [`examples/glfw_opengl3`](examples/glfw_opengl3) | 显式后端的完整事件循环 |
| [`examples/basic`](examples/basic) | headless 核心 API(CI 可跑) |

```bash
cd examples/docking && mcpp run
```

## Verification
## 工具链与运行时

The `0.0.1` release state is verified with mcpp `0.0.44`:
包不固定工具链(mcpp 解析环境默认,如 Linux glibc gcc);GL/GLX 运行时由生态包 `compat.glx-runtime` 透传闭合,不打包驱动。解析结果可用 `mcpp why` / `mcpp self doctor` 查看。

- `mcpp build`
- `mcpp test`
- `cd examples/basic && mcpp run`
- `cd examples/app_minimal && mcpp build`
- `cd examples/minimal_window && mcpp build`
- `cd examples/glfw_opengl3 && mcpp build`
> [!NOTE]
> 早期版本,接口可能调整。问题与想法欢迎提 [issue](https://github.com/mcpplibs/imgui-m/issues)。

## License

The wrapper code in this repository is MIT licensed. Dear ImGui is MIT licensed
and provided by the `compat.imgui` package.
封装代码 MIT;Dear ImGui 本体 MIT(经 `compat.imgui` 提供)。
Loading