From f03c9eb73571db1433e4c74114375ccdcefa2be9 Mon Sep 17 00:00:00 2001 From: Gnimuc Date: Thu, 28 Feb 2019 00:00:32 +0800 Subject: [PATCH] Update README --- README.md | 25 ++++++++++++++++--------- docs/src/index.md | 21 +++++++++++++++++++-- 2 files changed, 35 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0cb4e2d..2892c49 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://Gnimuc.github.io/CImGui.jl/stable) [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://Gnimuc.github.io/CImGui.jl/dev) -This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization or debug tools. Browse [Gallery](https://github.com/ocornut/imgui/issues/2265) +This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization / debug tools. You could browse [Gallery](https://github.com/ocornut/imgui/issues/2265) to get an idea of its use cases. ![demo](demo/demo.png) @@ -24,7 +24,7 @@ pkg> dev https://github.com/Gnimuc/CImGui.jl.git ## Quick Start 1. Run `demo/demo.jl` to test whether the default backend works on your machine. 2. Run `examples/demo.jl` and browse demos in the `examples` folder to learn how to use the API. -3. Press `? CImGui.xxx` to retrieve docs. +3. Read documentation or run `? CImGui.xxx` to retrieve docs: ``` help?> CImGui.Begin Begin(name, p_open=C_NULL, flags=0) -> Bool @@ -48,17 +48,24 @@ help?> CImGui.Begin │ is due to legacy reason and is inconsistent with most other functions (such as │ BeginMenu/EndMenu, BeginPopup/EndPopup, etc.) where the EndXXX call should only be │ called if the corresponding BeginXXX function returned true. +``` - ──────────────────────────────────────────────────────────────────────────────────────────────── - - Begin(handle::Ptr{ImGuiTextBuffer}) -> Cstring +## Usage +The API provided in this package is as close as possible to the original C++ API. When translating C++ code to Julia, please follow the tips below: +- Replace `ImGui::` to `CImGui.`; +- `using LibCImGui` to import all of the `ImGuiXXX` types into the current namespace; +- Member function calling should be translated in Julia style: `fonts.AddFont(cfg)` => `CImGui.Add(fonts, cfg)`; +- Prefer to define colors as `Vector{Cfloat}` instead of `CImGui.ImVec4`; +- [CSyntax.jl](https://github.com/Gnimuc/CSyntax.jl) provides two useful macros: `@c` for translating C's `&` operator on immutables and `@cstatic`-block for emulating C's `static` keyword; +- pointer arithmetic: `&A[n]` should be translated to `pointer(A) + n * sizeof(T)` - ──────────────────────────────────────────────────────────────────────────────────────────────── +As mentioned before, this package aims to provide the same user experience as the original C++ API, so any high-level abstraction should go into a more high-level package. - Begin(handle::Ptr{ImGuiListClipper}, items_count, items_height=-1.0) +### LibCImGui +LibCImGui is a thin wrapper over cimgui. It's one-to-one mapped to the original cimgui APIs. By using CImGui.LibCImGui, all of the ImGui-prefixed types, enums and ig-prefixed functions are imported into the current namespace. - Automatically called by constructor if you passed items_count or by Step in Step 1. -``` +### Backend +The default backend is based on [ModernGL](https://github.com/JuliaGL/ModernGL.jl) and [GLFW](https://github.com/JuliaGL/GLFW.jl) which are stable and under actively maintained. Other popular backends like [SFML](https://github.com/zyedidia/SFML.jl) and [SDL](https://github.com/ariejdl/SDL.jl) could be added in the future if someone would invest time to make these packages work in post Julia 1.0 era. ## License Only the Julia code in this repo is released under MIT license. Other assets such as those fonts in the `fonts` folder are released under their own license. diff --git a/docs/src/index.md b/docs/src/index.md index 567cbe5..5a2115e 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,5 +1,5 @@ # CImGui -This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization or debug tools. Browse [Gallery](https://github.com/ocornut/imgui/issues/2265) +This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization / debug tools. You could browse [Gallery](https://github.com/ocornut/imgui/issues/2265) to get an idea of its use cases. ![demo](demo/demo.png) @@ -10,4 +10,21 @@ pkg> add CImGui ``` ## Usage -TODO... +The API provided in this package is as close as possible to the original C++ API. When translating C++ code to Julia, please follow the tips below: +- Replace `ImGui::` to `CImGui.`; +- `using LibCImGui` to import all of the `ImGuiXXX` types into the current namespace; +- Member function calling should be translated in Julia style: `fonts.AddFont(cfg)` => `CImGui.Add(fonts, cfg)`; +- Prefer to define colors as `Vector{Cfloat}` instead of `CImGui.ImVec4`; +- [CSyntax.jl](https://github.com/Gnimuc/CSyntax.jl) provides two useful macros: `@c` for translating C's `&` operator on immutables and `@cstatic`-block for emulating C's `static` keyword; +- pointer arithmetic: `&A[n]` should be translated to `pointer(A) + n * sizeof(T)` + +As mentioned before, this package aims to provide the same user experience as the original C++ API, so any high-level abstraction should go into a more high-level package. + +### LibCImGui +LibCImGui is a thin wrapper over cimgui. It's one-to-one mapped to the original cimgui APIs. By using CImGui.LibCImGui, all of the ImGui-prefixed types, enums and ig-prefixed functions are imported into the current namespace. + +### Backend +The default backend is based on [ModernGL](https://github.com/JuliaGL/ModernGL.jl) and [GLFW](https://github.com/JuliaGL/GLFW.jl) which are stable and under actively maintained. Other popular backends like [SFML](https://github.com/zyedidia/SFML.jl) and [SDL](https://github.com/ariejdl/SDL.jl) could be added in the future if someone would invest time to make these packages work in post Julia 1.0 era. + +## License +Only the Julia code in this repo is released under MIT license. Other assets such as those fonts in the `fonts` folder are released under their own license.