From 6a0e442ad68c2b104b7e91ef80798610a79aca6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Fri, 22 Nov 2019 22:14:24 +0100 Subject: [PATCH] Write docs for `iced_wgpu` --- wgpu/src/image.rs | 10 +++++----- wgpu/src/lib.rs | 26 ++++++++++++++++++++++++++ wgpu/src/primitive.rs | 23 +++++++++++++++++++++++ wgpu/src/quad.rs | 1 + wgpu/src/renderer.rs | 8 ++++++-- wgpu/src/renderer/target.rs | 10 ++++++---- wgpu/src/text.rs | 12 +++++++----- 7 files changed, 74 insertions(+), 16 deletions(-) diff --git a/wgpu/src/image.rs b/wgpu/src/image.rs index 75cfa166..96c9ab6d 100644 --- a/wgpu/src/image.rs +++ b/wgpu/src/image.rs @@ -1,11 +1,9 @@ use crate::Transformation; use iced_native::Rectangle; -use std::cell::RefCell; -use std::collections::HashMap; -use std::mem; -use std::rc::Rc; +use std::{cell::RefCell, collections::HashMap, mem, rc::Rc}; +#[derive(Debug)] pub struct Pipeline { cache: RefCell>, @@ -207,7 +205,8 @@ impl Pipeline { if !self.cache.borrow().contains_key(path) { let image = image::open(path).expect("Load image").to_bgra(); - self.cache + let _ = self + .cache .borrow_mut() .insert(path.to_string(), Memory::Host { image }); } @@ -308,6 +307,7 @@ impl Pipeline { } } +#[derive(Debug)] enum Memory { Host { image: image::ImageBuffer, Vec>, diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index d770f872..9f9ed8db 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -1,3 +1,29 @@ +//! A [`wgpu`] renderer for [`iced_native`]. +//! +//! ![`iced_wgpu` crate graph](https://github.com/hecrj/iced/blob/cae26cb7bc627f4a5b3bcf1cd023a0c552e8c65e/docs/graphs/wgpu.png?raw=true) +//! +//! For now, it is the default renderer of [Iced] in native platforms. +//! +//! [`wgpu`] supports most modern graphics backends: Vulkan, Metal, DX11, and +//! DX12 (OpenGL and WebGL are still WIP). Additionally, it will support the +//! incoming [WebGPU API]. +//! +//! Currently, `iced_wgpu` supports the following primitives: +//! - Text, which is rendered using [`wgpu_glyph`]. No shaping at all. +//! - Quads or rectangles, with rounded borders and a solid background color. +//! - Images, lazily loaded from the filesystem. +//! - Clip areas, useful to implement scrollables or hide overflowing content. +//! +//! [Iced]: https://github.com/hecrj/iced +//! [`iced_native`]: https://github.com/hecrj/iced/tree/master/native +//! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs +//! [WebGPU API]: https://gpuweb.github.io/gpuweb/ +//! [`wgpu_glyph`]: https://github.com/hecrj/wgpu_glyph +#![deny(missing_docs)] +#![deny(missing_debug_implementations)] +#![deny(unused_results)] +#![deny(unsafe_code)] +#![deny(rust_2018_idioms)] mod image; mod primitive; mod quad; diff --git a/wgpu/src/primitive.rs b/wgpu/src/primitive.rs index 564dbda4..9efd74f6 100644 --- a/wgpu/src/primitive.rs +++ b/wgpu/src/primitive.rs @@ -3,33 +3,56 @@ use iced_native::{ VerticalAlignment, }; +/// A rendering primitive. #[derive(Debug, Clone)] pub enum Primitive { + /// An empty primitive None, + /// A group of primitives Group { + /// The primitives of the group primitives: Vec, }, + /// A text primitive Text { + /// The contents of the text content: String, + /// The bounds of the text bounds: Rectangle, + /// The color of the text color: Color, + /// The size of the text size: f32, + /// The font of the text font: Font, + /// The horizontal alignment of the text horizontal_alignment: HorizontalAlignment, + /// The vertical alignment of the text vertical_alignment: VerticalAlignment, }, + /// A quad primitive Quad { + /// The bounds of the quad bounds: Rectangle, + /// The background of the quad background: Background, + /// The border radius of the quad border_radius: u16, }, + /// An image primitive Image { + /// The path of the image path: String, + /// The bounds of the image bounds: Rectangle, }, + /// A clip primitive Clip { + /// The bounds of the clip bounds: Rectangle, + /// The offset transformation of the clip offset: Vector, + /// The content of the clip content: Box, }, } diff --git a/wgpu/src/quad.rs b/wgpu/src/quad.rs index 4356f8af..3d797758 100644 --- a/wgpu/src/quad.rs +++ b/wgpu/src/quad.rs @@ -3,6 +3,7 @@ use iced_native::Rectangle; use std::mem; +#[derive(Debug)] pub struct Pipeline { pipeline: wgpu::RenderPipeline, constants: wgpu::BindGroup, diff --git a/wgpu/src/renderer.rs b/wgpu/src/renderer.rs index 4199eee5..f27a4b8a 100644 --- a/wgpu/src/renderer.rs +++ b/wgpu/src/renderer.rs @@ -14,6 +14,10 @@ mod widget; pub use target::Target; +/// A [`wgpu`] renderer. +/// +/// [`wgpu`]: https://github.com/gfx-rs/wgpu-rs +#[derive(Debug)] pub struct Renderer { device: Device, queue: Queue, @@ -22,7 +26,7 @@ pub struct Renderer { text_pipeline: text::Pipeline, } -pub struct Layer<'a> { +struct Layer<'a> { bounds: Rectangle, offset: Vector, quads: Vec, @@ -304,7 +308,7 @@ impl Renderer { &mut self, dpi: f32, transformation: Transformation, - layer: &Layer, + layer: &Layer<'_>, encoder: &mut wgpu::CommandEncoder, target: &wgpu::TextureView, ) { diff --git a/wgpu/src/renderer/target.rs b/wgpu/src/renderer/target.rs index eeeb629a..569f3c62 100644 --- a/wgpu/src/renderer/target.rs +++ b/wgpu/src/renderer/target.rs @@ -2,6 +2,8 @@ use crate::{Renderer, Transformation}; use raw_window_handle::HasRawWindowHandle; +/// A rendering target. +#[derive(Debug)] pub struct Target { surface: wgpu::Surface, width: u16, @@ -12,19 +14,19 @@ pub struct Target { } impl Target { - pub fn dimensions(&self) -> (u16, u16) { + pub(crate) fn dimensions(&self) -> (u16, u16) { (self.width, self.height) } - pub fn dpi(&self) -> f32 { + pub(crate) fn dpi(&self) -> f32 { self.dpi } - pub fn transformation(&self) -> Transformation { + pub(crate) fn transformation(&self) -> Transformation { self.transformation } - pub fn next_frame(&mut self) -> wgpu::SwapChainOutput { + pub(crate) fn next_frame(&mut self) -> wgpu::SwapChainOutput<'_> { self.swap_chain.get_next_texture() } } diff --git a/wgpu/src/text.rs b/wgpu/src/text.rs index da070f5c..bf37abe5 100644 --- a/wgpu/src/text.rs +++ b/wgpu/src/text.rs @@ -2,8 +2,7 @@ mod font; use crate::Transformation; -use std::cell::RefCell; -use std::collections::HashMap; +use std::{cell::RefCell, collections::HashMap}; pub const BUILTIN_ICONS: iced_native::Font = iced_native::Font::External { name: "iced_wgpu icons", @@ -12,6 +11,7 @@ pub const BUILTIN_ICONS: iced_native::Font = iced_native::Font::External { pub const CHECKMARK_ICON: char = '\u{F00C}'; +#[derive(Debug)] pub struct Pipeline { draw_brush: RefCell>, draw_font_map: RefCell>, @@ -56,7 +56,7 @@ impl Pipeline { wgpu_glyph::FontId(0) } - pub fn queue(&mut self, section: wgpu_glyph::Section) { + pub fn queue(&mut self, section: wgpu_glyph::Section<'_>) { self.draw_brush.borrow_mut().queue(section); } @@ -134,7 +134,8 @@ impl Pipeline { // it uses a lifetimed `GlyphCalculatorGuard` with side-effects on drop. // This makes stuff quite inconvenient. A manual method for trimming the // cache would make our lives easier. - self.measure_brush + let _ = self + .measure_brush .borrow_mut() .process_queued(|_, _| {}, |_| {}) .expect("Trim text measurements"); @@ -154,7 +155,8 @@ impl Pipeline { let font_id = self.draw_brush.borrow_mut().add_font_bytes(bytes); - self.draw_font_map + let _ = self + .draw_font_map .borrow_mut() .insert(String::from(name), font_id);