Merge #54

54: Document how to run examples r=grovesNL a=rukai

I had assumed the triangle example wasn't functional yet, because I didn't realize I had to specify a feature. I only realized it was supposed to work when I saw a screenshot of the cube example.

I'm not sure what the future is of the triangle example? Will it remain outside of the gfx-examples folder?

Co-authored-by: Rukai <rubickent@gmail.com>

README.md

@@ -10,3 +10,30 @@ The implementation consists of the following parts:
   - `wgpu-bindings` - automatic generator of actual C headers
   - `wgpu-remote` - remoting layer to work with WebGPU across the process boundary
   - `wgpu-rs` - idiomatic Rust wrapper of the native library
+
+## Example
+
+To run an example, simply `cd` to the `examples` or `gfx-examples` directory, then use `cargo run` with `--features {backend}` to specify the backend (where `{backend}` is either `vulkan`, `dx12`, `dx11` or `metal`). For example:
+
+```bash
+# Clone the wgpu repository
+git clone https://github.com/gfx-rs/wgpu
+# Change directory to `examples`
+cd wgpu/examples
+# Vulkan (Linux/Windows)
+cargo run --bin hello_triangle --features vulkan
+# Metal (macOS/iOS)
+cargo run --bin hello_triangle --features metal
+# DirectX12 (Windows)
+cargo run --bin hello_triangle --features dx12
+
+cd ../gfx-examples
+# Vulkan (Linux/Windows)
+cargo run --bin cube --features vulkan
+# Metal (macOS/iOS)
+cargo run --bin cube --features metal
+# DirectX12 (Windows)
+cargo run --bin cube --features dx12
+```
+
+These examples assume that necessary dependencies for the graphics backend are already installed. For more information about installation and usage, refer to the [Getting Started](https://github.com/gfx-rs/gfx/blob/master/info/getting_started.md) guide.

examples/Cargo.toml

@@ -18,7 +18,6 @@ path = "hello_compute_rust/main.rs"
 [features]
 default = []
 remote = ["wgpu-native/remote"]
-winit = ["wgpu/winit"]
 metal = ["wgpu-native/gfx-backend-metal"]
 dx11 = ["wgpu-native/gfx-backend-dx11"]
 dx12 = ["wgpu-native/gfx-backend-dx12"]
@@ -26,5 +25,5 @@ vulkan = ["wgpu-native/gfx-backend-vulkan"]
 
 [dependencies]
 wgpu-native = { path = "../wgpu-native" }
-wgpu = { path = "../wgpu-rs" }
+wgpu = { path = "../wgpu-rs", features=["winit"] }
 env_logger = "0.5"

examples/hello_triangle_rust/main.rs

@@ -58,67 +58,64 @@ fn main() {
         vertex_buffers: &[],
     });
 
-    #[cfg(feature = "winit")]
-    {
-        use wgpu_native::winit::{ControlFlow, Event, ElementState, EventsLoop, KeyboardInput, Window, WindowEvent, VirtualKeyCode};
+    use wgpu_native::winit::{ControlFlow, Event, ElementState, EventsLoop, KeyboardInput, Window, WindowEvent, VirtualKeyCode};
 
-        let mut events_loop = EventsLoop::new();
-        let window = Window::new(&events_loop).unwrap();
-        let size = window
-            .get_inner_size()
-            .unwrap()
-            .to_physical(window.get_hidpi_factor());
+    let mut events_loop = EventsLoop::new();
+    let window = Window::new(&events_loop).unwrap();
+    let size = window
+        .get_inner_size()
+        .unwrap()
+        .to_physical(window.get_hidpi_factor());
 
-        let surface = instance.create_surface(&window);
-        let mut swap_chain = device.create_swap_chain(&surface, &wgpu::SwapChainDescriptor {
-            usage: wgpu::TextureUsageFlags::OUTPUT_ATTACHMENT,
-            format: wgpu::TextureFormat::B8g8r8a8Unorm,
-            width: size.width as u32,
-            height: size.height as u32,
-        });
+    let surface = instance.create_surface(&window);
+    let mut swap_chain = device.create_swap_chain(&surface, &wgpu::SwapChainDescriptor {
+        usage: wgpu::TextureUsageFlags::OUTPUT_ATTACHMENT,
+        format: wgpu::TextureFormat::B8g8r8a8Unorm,
+        width: size.width as u32,
+        height: size.height as u32,
+    });
 
-        events_loop.run_forever(|event| {
-            match event {
-                Event::WindowEvent { event, .. } => match event {
-                    WindowEvent::KeyboardInput {
-                        input: KeyboardInput { virtual_keycode: Some(code), state: ElementState::Pressed, .. },
-                        ..
-                    } => match code {
-                        VirtualKeyCode::Escape => {
-                            return ControlFlow::Break
-                        }
-                        _ => {}
-                    }
-                    WindowEvent::CloseRequested => {
+    events_loop.run_forever(|event| {
+        match event {
+            Event::WindowEvent { event, .. } => match event {
+                WindowEvent::KeyboardInput {
+                    input: KeyboardInput { virtual_keycode: Some(code), state: ElementState::Pressed, .. },
+                    ..
+                } => match code {
+                    VirtualKeyCode::Escape => {
                         return ControlFlow::Break
                     }
                     _ => {}
                 }
+                WindowEvent::CloseRequested => {
+                    return ControlFlow::Break
+                }
                 _ => {}
             }
+            _ => {}
+        }
 
-            let frame = swap_chain.get_next_texture();
-            let mut cmd_buf = device.create_command_buffer(&wgpu::CommandBufferDescriptor { todo: 0 });
-            {
-                let mut rpass = cmd_buf.begin_render_pass(&wgpu::RenderPassDescriptor {
-                    color_attachments: &[wgpu::RenderPassColorAttachmentDescriptor {
-                        attachment: &frame.view,
-                        load_op: wgpu::LoadOp::Clear,
-                        store_op: wgpu::StoreOp::Store,
-                        clear_color: wgpu::Color::GREEN,
-                    }],
-                    depth_stencil_attachment: None,
-                });
-                rpass.set_pipeline(&render_pipeline);
-                rpass.draw(0..3, 0..1);
-                rpass.end_pass();
-            }
+        let frame = swap_chain.get_next_texture();
+        let mut cmd_buf = device.create_command_buffer(&wgpu::CommandBufferDescriptor { todo: 0 });
+        {
+            let mut rpass = cmd_buf.begin_render_pass(&wgpu::RenderPassDescriptor {
+                color_attachments: &[wgpu::RenderPassColorAttachmentDescriptor {
+                    attachment: &frame.view,
+                    load_op: wgpu::LoadOp::Clear,
+                    store_op: wgpu::StoreOp::Store,
+                    clear_color: wgpu::Color::GREEN,
+                }],
+                depth_stencil_attachment: None,
+            });
+            rpass.set_pipeline(&render_pipeline);
+            rpass.draw(0..3, 0..1);
+            rpass.end_pass();
+        }
 
-            device
-                .get_queue()
-                .submit(&[cmd_buf]);
+        device
+            .get_queue()
+            .submit(&[cmd_buf]);
 
-            ControlFlow::Continue
-        });
-    }
+        ControlFlow::Continue
+    });
 }

gfx-examples/README.md

@@ -1,6 +1,6 @@
 # gfx pre-ll examples
 
-The original gfx-rs examples had grown over several years, but then were abandoned owhen the gfx API was changed to match Vulkan:
+The original gfx-rs examples had grown over several years, but then were abandoned when the gfx API was changed to match Vulkan:
 https://github.com/gfx-rs/gfx/tree/pre-ll/examples
 
 wgpu-rs is considered to be the spiritual successor of gfx pre-ll, so this is the new home for the examples.