Merge pull request #692 from dbr/examples-reorg

Reorganization of examples

README.markdown

@@ -25,12 +25,28 @@ ui.window("Hello world")
 
 ## Main library crates
 
-- imgui: High-level safe API
-- imgui-winit-support: Backend platform implementation that uses the `winit`
-  crate (latest by default, but earlier versions are supported via feature flags)
-- imgui-glow-renderer: Renderer implementation that uses the `glow` crate
-- imgui-glium-renderer: Renderer implementation that uses the `glium` crate
-- imgui-sys: Low-level unsafe API (automatically generated)
+The core of imgui-rs consists of:
+
+- [`imgui`](./imgui): High-level safe API
+- [`imgui-sys`](./imgui-sys): Low-level unsafe API (automatically generated)
+
+Next, we provide two example renderers, and two example backend platform implementations:
+
+- [`imgui-winit-support`](./imgui-winit-support): Backend platform implementation that uses the `winit` crate
+- [`imgui-sdl2-support`](./imgui-sdl2-support): Backend platform using SDL2
+- [`imgui-glow-renderer`](./imgui-glow-renderer): Renderer implementation that uses the `glow` crate
+- [`imgui-glium-renderer`](./imgui-glium-renderer): Renderer implementation that uses the `glium` crate
+
+Each of these contain an `examples` folder showing their usage. Check
+their respective `Cargo.toml` to find compatible versions (e.g
+`imgui-glow-renderer/Cargo.toml` the `[dependencies]` describes the
+compatible `glow` version and `[dev-dependencies]` describes the
+compatible `glutin` version)
+
+Finally the [`imgui-examples`](./imgui-examples) folder contains
+examples of how to use the `imgui` crate itself - this covers general
+topics like how to show text, how to create buttons, etc - and should
+be applicable to usage with any backend/renderer.
 
 ## Features
 
@@ -39,8 +55,8 @@ ui.window("Hello world")
 - Builder structs for use cases where the original C++ library uses optional
   function parameters
 - Easy integration with `glow`/ `glium`
-- Easy integration with winit (backend platform)
-- Optional support for the freetype font rasterizer
+- Easy integration with winit and sdl2 (backend platform)
+- Optional support for the freetype font rasterizer and the docking branch
 
 ## Minimum Support Rust Version (MSRV)
 
@@ -84,6 +100,7 @@ Additionally, there are other libraries which provide other kinds of renderers,
  2. [`imgui-d3d12-renderer`](https://github.com/curldivergence/imgui-d3d12-renderer)
  3. [`imgui-dx11-renderer`](https://github.com/veykril/imgui-dx11-renderer)
  4. [`imgui-gfx-renderer`](https://github.com/imgui-rs/imgui-gfx-renderer): Deprecated (no longer maintained beyond imgui-rs v0.8). Renderer implementation that uses the `gfx` crate (_not the new gfx-hal crate_)
+ 5. Many more can be found on [crates.io](https://crates.io) either using search or the ["dependents" page](https://crates.io/crates/imgui/reverse_dependencies) (the "depends on" text indicates if the crate has been updated for current versions of imgui-rs)
 
 
 You can also write your own support code if you have a more advanced use case, because **imgui-rs is not tied to any specific graphics / OS API**.

imgui-glium-renderer/Cargo.toml

@@ -12,3 +12,6 @@ categories = ["gui", "rendering"]
 [dependencies]
 glium = { version = "0.32.1", default-features = false }
 imgui = { version = "0.9.0", path = "../imgui" }
+
+[dev-dependencies]
+imgui-winit-support = {path = "../imgui-winit-support"}

imgui-glium-renderer/examples/glium_01_basic.rs

@@ -0,0 +1,98 @@
+use glium::glutin::event::{Event, WindowEvent};
+use glium::glutin::event_loop::{ControlFlow, EventLoop};
+use glium::Surface;
+
+const TITLE: &str = "Hello, imgui-rs!";
+
+fn main() {
+    // Common setup for creating a winit window and imgui context, not specifc
+    // to this renderer at all except that glutin is used to create the window
+    // since it will give us access to a GL context
+    let (event_loop, display) = create_window();
+    let (mut winit_platform, mut imgui_context) = imgui_init(&display);
+
+    // Create renderer from this crate
+    let mut renderer = imgui_glium_renderer::Renderer::init(&mut imgui_context, &display)
+        .expect("Failed to initialize renderer");
+
+    // Timer for FPS calculation
+    let mut last_frame = std::time::Instant::now();
+
+    // Standard winit event loop
+    event_loop.run(move |event, _, control_flow| match event {
+        Event::NewEvents(_) => {
+            let now = std::time::Instant::now();
+            imgui_context.io_mut().update_delta_time(now - last_frame);
+            last_frame = now;
+        }
+        Event::MainEventsCleared => {
+            let gl_window = display.gl_window();
+            winit_platform
+                .prepare_frame(imgui_context.io_mut(), gl_window.window())
+                .expect("Failed to prepare frame");
+            gl_window.window().request_redraw();
+        }
+        Event::RedrawRequested(_) => {
+            // Create frame for the all important `&imgui::Ui`
+            let ui = imgui_context.frame();
+
+            // Draw our example content
+            ui.show_demo_window(&mut true);
+
+            // Setup for drawing
+            let gl_window = display.gl_window();
+            let mut target = display.draw();
+
+            // Renderer doesn't automatically clear window
+            target.clear_color_srgb(1.0, 1.0, 1.0, 1.0);
+
+            // Perform rendering
+            winit_platform.prepare_render(ui, gl_window.window());
+            let draw_data = imgui_context.render();
+            renderer
+                .render(&mut target, draw_data)
+                .expect("Rendering failed");
+            target.finish().expect("Failed to swap buffers");
+        }
+        Event::WindowEvent {
+            event: WindowEvent::CloseRequested,
+            ..
+        } => *control_flow = ControlFlow::Exit,
+        event => {
+            let gl_window = display.gl_window();
+            winit_platform.handle_event(imgui_context.io_mut(), gl_window.window(), &event);
+        }
+    });
+}
+
+fn create_window() -> (EventLoop<()>, glium::Display) {
+    let event_loop = EventLoop::new();
+    let context = glium::glutin::ContextBuilder::new().with_vsync(true);
+    let builder = glium::glutin::window::WindowBuilder::new()
+        .with_title(TITLE.to_owned())
+        .with_inner_size(glium::glutin::dpi::LogicalSize::new(1024f64, 768f64));
+    let display =
+        glium::Display::new(builder, context, &event_loop).expect("Failed to initialize display");
+
+    (event_loop, display)
+}
+
+fn imgui_init(display: &glium::Display) -> (imgui_winit_support::WinitPlatform, imgui::Context) {
+    let mut imgui_context = imgui::Context::create();
+    imgui_context.set_ini_filename(None);
+
+    let mut winit_platform = imgui_winit_support::WinitPlatform::init(&mut imgui_context);
+
+    let gl_window = display.gl_window();
+    let window = gl_window.window();
+
+    let dpi_mode = imgui_winit_support::HiDpiMode::Default;
+
+    winit_platform.attach_window(imgui_context.io_mut(), window, dpi_mode);
+
+    imgui_context
+        .fonts()
+        .add_font(&[imgui::FontSource::DefaultFontData { config: None }]);
+
+    (winit_platform, imgui_context)
+}

imgui-winit-support/examples/README.md

@@ -0,0 +1,5 @@
+See the examples for [`imgui-glium-renderer`][glium] or [`imgui-glow-renderer`][glow]
+for simple examples of this platform backend with different renderers
+
+[glium]: ../../imgui-glium-renderer/examples
+[glow]: ../../imgui-glow-renderer/examples