nannou_draw 0.20.0

//! A simple API for drawing 2D and 3D graphics.
//!
//! See the [Draw] for more details.

use std::{
    any::TypeId,
    ops::{Deref, Range},
    sync::{Arc, RwLock},
};

use self::primitive::Primitive;
pub use self::{
    background::Background,
    drawing::{Drawing, DrawingContext},
    theme::Theme,
};
use crate::{
    draw::{indirect::Indirect, instanced::Instanced, mesh::MeshExt},
    render::{DefaultNannouShaderModel, ErasedShaderModel, ShaderModel},
    text::font::SharedTextCx,
};
use bevy::{
    asset::UntypedAssetId,
    platform::collections::{HashMap, HashSet},
    prelude::*,
    render::{
        render_resource as wgpu,
        render_resource::{BlendComponent, BlendState},
        storage::ShaderBuffer,
    },
};
use lyon::path::PathEvent;
use uuid::Uuid;

pub mod background;
mod drawing;
pub mod indirect;
pub mod instanced;
pub mod mesh;
pub mod primitive;
pub mod properties;
pub(crate) mod render;
pub mod theme;

/// A simple API for drawing 2D and 3D graphics.
///
/// [Draw] provides a simple way to compose together geometry and text with custom colours and
/// textures and draw them to the screen. A suite of methods have been provided for drawing
/// polygons, paths, meshes, text and textures in an accessible-yet-efficient manner.
///
/// [Draw] can also be used to create new [Draw] instances that refer to the same inner draw
/// state but are slightly different from one another. E.g. `draw.rotate(radians)` produces a new
/// [Draw] instance where all drawings will be rotated by the given amount. `draw.x(x)` produces
/// a new [Draw] instance where all drawings are translated along the *x* axis by the given
/// amount.
///
/// See the [draw](https://github.com/nannou-org/nannou/blob/master/examples) examples for a
/// variety of demonstrations of how the [Draw] type can be used!
#[derive(Component, Clone)]
pub struct Draw {
    /// The state of the [Draw].
    ///
    /// State is shared between this [Draw] instance and all other [Draw] instances that were
    /// produced by cloning or changing transform, scissor or blend mode.
    ///
    /// We use a `RefCell` in order to avoid requiring a `mut` handle to a `draw`. The primary
    /// purpose of a [Draw] is to be an easy-as-possible, high-level API for drawing stuff. In
    /// order to be friendlier to new users, we want to avoid them having to think about mutability
    /// and focus on creativity. Rust-lang nuances can come later.
    pub state: Arc<RwLock<State>>,
    /// The current context of this [Draw] instance.
    context: DrawContext,
    /// The current type erased shader model of this [Draw] instance.
    pub(crate) shader_model: UntypedAssetId,
    /// The window to which this [Draw] instance is associated.
    pub(crate) window: Entity,
    /// Shared text context.
    pub(crate) text_cx: SharedTextCx,
}

/// A reference to a [Draw] instance that is either borrowed or owned.
#[derive(Clone)]
pub enum DrawRef<'a> {
    Borrowed(&'a Draw),
    Owned(Draw),
}

impl<'a> Deref for DrawRef<'a> {
    type Target = Draw;

    fn deref(&self) -> &Self::Target {
        match self {
            DrawRef::Borrowed(draw) => *draw,
            DrawRef::Owned(draw) => draw,
        }
    }
}

/// The current **Transform** of a [Draw] instance.
#[derive(Clone, Debug, PartialEq)]
pub struct DrawContext {
    // TODO: figure out how to fixup camera via transform
    pub transform: Mat4,
}

impl Default for DrawContext {
    fn default() -> Self {
        Self {
            transform: Mat4::IDENTITY,
        }
    }
}

/// Commands generated by drawing that instruct how to create the meshes and shader model that will be
/// rendered.
#[derive(Clone, Debug)]
pub enum DrawCommand {
    /// Draw a primitive.
    Primitive(Primitive),
    /// Draw an instanced primitive
    Instanced(Primitive, Range<u32>),
    /// Draw a primitive using an indirect buffer.
    Indirect(Primitive, Handle<ShaderBuffer>),
    /// A change in the rendering context occurred.
    Context(DrawContext),
    /// A change in the shader model occurred.
    ShaderModel(UntypedAssetId),
    /// A change in the background color occurred.
    BackgroundColor(Color),
}

/// The inner state of the [Draw] type.
///
/// The [Draw] type stores its [State] behind a [RwLock] - a type used for moving mutability
/// checks from compile time to runtime. We do this in order to avoid requiring a `mut` handle to a
/// `draw`. The primary purpose of a [Draw] is to be an easy-as-possible, high-level API for
/// drawing stuff. In order to be friendlier to new users, we want to avoid requiring them to think
/// about mutability and instead focus on creativity. Rust-lang nuances can come later.
pub struct State {
    /// The last shader model used to draw an image, used to detect changes and emit commands for them.
    last_shader_model: Option<UntypedAssetId>,
    /// The last context used to draw an image, used to detect changes and emit commands for them.
    last_draw_context: Option<DrawContext>,
    /// If `Some`, the [Draw] should first clear the frame's texture with the given color.
    background_color: Option<Color>,
    /// Primitives that are in the process of being drawn.
    ///
    /// Keys are indices into the `draw_commands` Vec.
    drawing: HashMap<usize, Primitive>,
    /// A map of all type erased shader models used by the draw.
    pub(crate) shader_models: HashMap<UntypedAssetId, Box<dyn ErasedShaderModel>>,
    /// A list of indices of primitives that are being drawn via an alternate method and
    /// should not be drawn
    ignored_drawings: HashSet<usize>,
    /// The list of recorded draw commands.
    ///
    /// An element may be `None` if it is a primitive in the process of being drawn.
    pub(crate) draw_commands: Vec<Option<DrawCommand>>,
    /// State made accessible via the `DrawingContext`.
    pub(crate) intermediary_state: Arc<RwLock<IntermediaryState>>,
    /// The theme containing default values.
    pub(crate) theme: Theme,
}

/// State made accessible via the `DrawingContext`.
#[derive(Clone, Debug)]
pub struct IntermediaryState {
    /// Buffers of vertex data that may be re-used for paths, meshes, etc between view calls.
    pub intermediary_mesh: Mesh,
    /// A re-usable buffer for collecting path events.
    pub path_event_buffer: Vec<PathEvent>,
    /// A re-usable buffer for collecting polyline points vertex data.
    pub path_points_vertex_buffer: Vec<(Vec2, Color, Vec2)>,
    /// A buffer containing all text.
    pub text_buffer: String,
}

impl IntermediaryState {
    pub fn reset(&mut self) {
        self.intermediary_mesh.clear();
        self.path_event_buffer.clear();
        self.path_points_vertex_buffer.clear();
        self.text_buffer.clear();
    }
}

impl State {
    // Resets all state within the `Draw` instance.
    fn reset(&mut self) {
        self.last_shader_model = None;
        self.last_draw_context = None;
        self.background_color = None;
        self.drawing.clear();
        self.shader_models.clear();
        self.draw_commands.clear();
        self.intermediary_state.write().unwrap().reset();
    }

    // Drain any remaining `drawing`s and insert them as draw commands.
    fn finish_remaining_drawings(&mut self) {
        let mut drawing = std::mem::replace(&mut self.drawing, Default::default());
        for (index, primitive) in drawing.drain() {
            self.insert_draw_command(index, primitive);
        }
        std::mem::swap(&mut self.drawing, &mut drawing);
    }

    // Finish the drawing at the given node index if it is not yet complete.
    pub(crate) fn finish_drawing(&mut self, index: usize) {
        // Don't draw if the primitive is going to be instanced
        if self.ignored_drawings.contains(&index) {
            return;
        }

        if let Some(primitive) = self.drawing.remove(&index) {
            self.insert_draw_command(index, primitive);
        }
    }

    // Insert the draw primitive command at the given index.
    fn insert_draw_command(&mut self, index: usize, prim: Primitive) {
        if let Some(elem) = self.draw_commands.get_mut(index) {
            *elem = Some(DrawCommand::Primitive(prim));
        }
    }
}

impl Draw {
    pub fn new(window: Entity, text_cx: SharedTextCx) -> Self {
        let mut state = State::default();
        let context = DrawContext::default();
        let model = DefaultNannouShaderModel::default();
        let model_id = UntypedAssetId::Uuid {
            type_id: TypeId::of::<DefaultNannouShaderModel>(),
            uuid: Uuid::new_v4(),
        };
        state.shader_models.insert(model_id, Box::new(model));

        Draw {
            state: Arc::new(RwLock::new(state)),
            context,
            shader_model: model_id,
            window,
            text_cx,
        }
    }

    /// Resets all state within the `Draw` instance.
    pub fn reset(&mut self) {
        self.state.write().unwrap().reset();
        self.insert_default_shader_model();
    }

    fn insert_default_shader_model(&mut self) {
        let mut state = self.state.write().unwrap();
        let model = DefaultNannouShaderModel::default();
        let model_id = UntypedAssetId::Uuid {
            type_id: TypeId::of::<DefaultNannouShaderModel>(),
            uuid: Uuid::new_v4(),
        };
        state.shader_models.insert(model_id, Box::new(model));
        self.shader_model = model_id;
    }

    // Context changes.

    /// Produce a new [Draw] instance transformed by the given transform matrix.
    ///
    /// The resulting [Draw] instance will be have a transform equal to the new transform applied
    /// to the existing transform.
    pub fn transform(&self, transform_matrix: Mat4) -> Self {
        let mut context = self.context.clone();
        context.transform = context.transform * transform_matrix;
        self.context(context)
    }

    /// Translate the position of the origin by the given translation vector.
    pub fn translate(&self, v: Vec3) -> Self {
        self.transform(Mat4::from_translation(v))
    }

    /// Translate the position of the origin by the given translation vector.
    ///
    /// This method is short for `translate`.
    pub fn xyz(&self, v: Vec3) -> Self {
        self.translate(v)
    }

    /// Translate the position of the origin by the given translation vector.
    pub fn xy(&self, v: Vec2) -> Self {
        self.xyz(v.extend(0.0))
    }

    /// Translate the position of the origin by the given amount across each axis.
    pub fn x_y_z(&self, x: f32, y: f32, z: f32) -> Self {
        self.xyz([x, y, z].into())
    }

    /// Translate the position of the origin by the given amount across each axis.
    pub fn x_y(&self, x: f32, y: f32) -> Self {
        self.xy([x, y].into())
    }

    /// Translate the position of the origin along the x axis.
    pub fn x(&self, x: f32) -> Self {
        self.x_y(x, 0.0)
    }

    /// Translate the position of the origin along the y axis.
    pub fn y(&self, y: f32) -> Self {
        self.x_y(0.0, y)
    }

    /// Translate the position of the origin along the z axis.
    pub fn z(&self, z: f32) -> Self {
        self.x_y_z(0.0, 0.0, z)
    }

    /// Produce a new [Draw] instance where the contents are scaled uniformly by the given value.
    pub fn scale(&self, s: f32) -> Self {
        self.scale_axes(Vec3::new(s, s, s))
    }

    /// Produce a new [Draw] instance where the contents are scaled by the given amount across
    /// each axis.
    pub fn scale_axes(&self, v: Vec3) -> Self {
        self.transform(Mat4::from_scale(v))
    }

    /// Produce a new [Draw] instance where the contents are scaled by the given amount along the
    /// x axis
    pub fn scale_x(&self, s: f32) -> Self {
        self.scale_axes(Vec3::new(s, 1.0, 1.0))
    }

    /// Produce a new [Draw] instance where the contents are scaled by the given amount along the
    /// y axis
    pub fn scale_y(&self, s: f32) -> Self {
        self.scale_axes(Vec3::new(1.0, s, 1.0))
    }

    /// Produce a new [Draw] instance where the contents are scaled by the given amount along the
    /// z axis
    pub fn scale_z(&self, s: f32) -> Self {
        self.scale_axes(Vec3::new(1.0, 1.0, s))
    }

    /// The given vector is interpreted as a Euler angle in radians and a transform is applied
    /// accordingly.
    pub fn euler(&self, euler: Vec3) -> Self {
        self.transform(Mat4::from_euler(EulerRot::XYZ, euler.x, euler.y, euler.z))
    }

    /// Specify the orientation with the given **Quaternion**.
    pub fn quaternion(&self, q: Quat) -> Self {
        self.transform(Mat4::from_quat(q))
    }

    /// Specify the orientation along each axis with the given **Vector** of radians.
    ///
    /// This currently has the same affect as calling `euler`.
    pub fn radians(&self, v: Vec3) -> Self {
        self.euler(v)
    }

    /// Specify the orientation around the *x* axis in radians.
    pub fn x_radians(&self, x: f32) -> Self {
        self.radians(Vec3::new(x, 0.0, 0.0))
    }

    /// Specify the orientation around the *y* axis in radians.
    pub fn y_radians(&self, y: f32) -> Self {
        self.radians(Vec3::new(0.0, y, 0.0))
    }

    /// Specify the orientation around the *z* axis in radians.
    pub fn z_radians(&self, z: f32) -> Self {
        self.radians(Vec3::new(0.0, 0.0, z))
    }

    /// Specify the orientation along each axis with the given **Vector** of degrees.
    pub fn degrees(&self, v: Vec3) -> Self {
        self.radians(Vec3::new(
            v.x.to_radians(),
            v.y.to_radians(),
            v.z.to_radians(),
        ))
    }

    /// Specify the orientation around the *x* axis in degrees.
    pub fn x_degrees(&self, x: f32) -> Self {
        self.x_radians(x.to_radians())
    }

    /// Specify the orientation around the *y* axis in degrees.
    pub fn y_degrees(&self, y: f32) -> Self {
        self.y_radians(y.to_radians())
    }

    /// Specify the orientation around the *z* axis in degrees.
    pub fn z_degrees(&self, z: f32) -> Self {
        self.z_radians(z.to_radians())
    }

    /// Specify the orientation along each axis with the given **Vector** of degrees.
    pub fn turns(&self, v: Vec3) -> Self {
        self.radians(v * std::f32::consts::TAU)
    }

    /// Specify the orientation around the *x* axis as a number of turns around the axis.
    pub fn x_turns(&self, x: f32) -> Self {
        self.x_radians(x * std::f32::consts::TAU)
    }

    /// Specify the orientation around the *y* axis as a number of turns around the axis.
    pub fn y_turns(&self, y: f32) -> Self {
        self.y_radians(y * std::f32::consts::TAU)
    }

    /// Specify the orientation around the *z* axis as a number of turns around the axis.
    pub fn z_turns(&self, z: f32) -> Self {
        self.z_radians(z * std::f32::consts::TAU)
    }

    /// Specify the "pitch" of the orientation in radians.
    ///
    /// This has the same effect as calling `x_radians`.
    pub fn pitch(&self, pitch: f32) -> Self {
        self.x_radians(pitch)
    }

    /// Specify the "yaw" of the orientation in radians.
    ///
    /// This has the same effect as calling `y_radians`.
    pub fn yaw(&self, yaw: f32) -> Self {
        self.y_radians(yaw)
    }

    /// Specify the "roll" of the orientation in radians.
    ///
    /// This has the same effect as calling `z_radians`.
    pub fn roll(&self, roll: f32) -> Self {
        self.z_radians(roll)
    }

    /// Assuming we're looking at a 2D plane, positive values cause a clockwise rotation where the
    /// given value is specified in radians.
    ///
    /// This is equivalent to calling the `z_radians` or `roll` methods.
    pub fn rotate(&self, radians: f32) -> Self {
        self.z_radians(radians)
    }

    /// Produce a new [Draw] instance with the given context.
    fn context(&self, context: DrawContext) -> Draw {
        let state = self.state.clone();
        let shader_model = self.shader_model.clone();
        let window = self.window;
        let text_cx = self.text_cx.clone();
        Draw {
            state,
            context,
            shader_model,
            window,
            text_cx,
        }
    }

    /// Clone the active shader model if it is the default nannou shader model.
    ///
    /// Returns `None` if a custom shader model type is active.
    fn clone_default_shader_model(&self) -> Option<DefaultNannouShaderModel> {
        let state = self.state.read().unwrap();
        let shader_model = state.shader_models.get(&self.shader_model)?;
        shader_model
            .as_any()
            .downcast_ref::<DefaultNannouShaderModel>()
            .cloned()
    }

    /// Produce a new [Draw] instance that will draw with the given shader model.
    pub fn shader_model<SM: ShaderModel>(&self, model: SM) -> Draw {
        let context = self.context.clone();
        let DrawContext { transform, .. } = context;
        let context = DrawContext { transform };
        let state = self.state.clone();
        let window = self.window;
        let text_cx = self.text_cx.clone();
        let model_id = UntypedAssetId::Uuid {
            type_id: TypeId::of::<SM>(),
            uuid: Uuid::new_v4(),
        };

        state
            .write()
            .unwrap()
            .shader_models
            .insert(model_id, Box::new(model));

        Draw {
            state,
            context,
            shader_model: model_id,
            window,
            text_cx,
        }
    }

    // Primitives.

    /// Specify a color with which the background should be cleared.
    pub fn background<'a>(&'a self) -> Background<'a> {
        background::new(self)
    }

    /// Draw an instanced drawing
    pub fn instanced<'a>(&'a self) -> Instanced<'a> {
        instanced::new(self)
    }

    pub fn indirect<'a>(&'a self) -> Indirect<'a> {
        indirect::new(self)
    }

    /// Add the given type to be drawn.
    pub fn a<T>(&self, primitive: T) -> Drawing<'_, T>
    where
        T: Into<Primitive>,
    {
        let (index, model_index) = self.insert_primitive(primitive.into());
        drawing::new(self, index, model_index)
    }

    // Record the primitive in the draw state, returning the indices of the draw command slots
    // reserved for the primitive and for a potential shader model change.
    fn insert_primitive(&self, primitive: Primitive) -> (usize, usize) {
        let mut state = self.state.write().unwrap();
        // If drawing with a different context, insert the necessary command to update it.
        if state.last_draw_context.as_ref() != Some(&self.context) {
            state
                .draw_commands
                .push(Some(DrawCommand::Context(self.context.clone())));
            state.last_draw_context = Some(self.context.clone());
        }

        let id = &self.shader_model;
        if state.last_shader_model.as_ref() != Some(id) {
            state
                .draw_commands
                .push(Some(DrawCommand::ShaderModel(id.clone())));
            state.last_shader_model = Some(id.clone());
        }

        // Insert a model slot to be used if the drawing switches models.
        let shader_model_index = state.draw_commands.len();
        state.draw_commands.push(None);

        // The primitive will be inserted in the next element.
        let index = state.draw_commands.len();
        state.draw_commands.push(None);
        state.drawing.insert(index, primitive);
        (index, shader_model_index)
    }

    /// Begin drawing a **Path**.
    pub fn path(&self) -> Drawing<'_, primitive::PathInit> {
        self.a(Default::default())
    }

    /// Begin drawing an **Ellipse**.
    pub fn ellipse(&self) -> Drawing<'_, primitive::Ellipse> {
        self.a(Default::default())
    }

    /// Begin drawing a **Line**.
    pub fn line(&self) -> Drawing<'_, primitive::Line> {
        self.a(Default::default())
    }

    /// Begin drawing an **Arrow**.
    pub fn arrow(&self) -> Drawing<'_, primitive::Arrow> {
        self.a(Default::default())
    }

    /// Begin drawing a **Quad**.
    pub fn quad(&self) -> Drawing<'_, primitive::Quad> {
        self.a(Default::default())
    }

    /// Begin drawing a **Rect**.
    pub fn rect(&self) -> Drawing<'_, primitive::Rect> {
        self.a(Default::default())
    }

    /// Begin drawing a **Triangle**.
    pub fn tri(&self) -> Drawing<'_, primitive::Tri> {
        self.a(Default::default())
    }

    /// Begin drawing a **Polygon**.
    pub fn polygon(&self) -> Drawing<'_, primitive::PolygonInit> {
        self.a(Default::default())
    }

    /// Begin drawing a **Mesh**.
    pub fn mesh(&self) -> Drawing<'_, primitive::mesh::Vertexless> {
        self.a(Default::default())
    }

    /// Begin drawing a **Polyline**.
    ///
    /// Note that this is simply short-hand for `draw.path().stroke()`
    pub fn polyline(&self) -> Drawing<'_, primitive::PathStroke> {
        self.path().stroke()
    }

    /// Begin drawing a **Text**.
    pub fn text(&self, s: &str) -> Drawing<'_, primitive::Text> {
        let text = {
            let state = self.state.read().expect("lock poisoned");
            let mut intermediary_state = state.intermediary_state.write().expect("lock poisoned");
            let ctxt = DrawingContext::from_intermediary_state(&mut *intermediary_state);
            primitive::text::Text::new(ctxt, s)
        };
        self.a(text)
    }

    /// Build a text layout immediately for measurement or glyph extraction.
    ///
    /// Unlike `draw.text()` which defers layout to the render pass, this
    /// returns a `text::Builder` whose `.build(rect)` computes layout eagerly.
    pub fn text_layout<'b>(&self, s: &'b str) -> crate::text::Builder<'b> {
        crate::text::Builder::new(s, self.text_cx.clone())
    }

    /// Finish any drawings-in-progress and produce an iterator draining the inner draw commands
    /// and yielding them by value.
    pub fn drain_commands(&self) -> impl Iterator<Item = DrawCommand> {
        self.finish_remaining_drawings();
        let cmds = {
            let mut state = self.state.write().unwrap();
            let empty = Vec::with_capacity(state.draw_commands.len());
            std::mem::replace(&mut state.draw_commands, empty)
        };
        cmds.into_iter().filter_map(|opt| opt)
    }

    /// Drain any remaining `drawing`s and convert them to draw commands.
    pub fn finish_remaining_drawings(&self) {
        let mut state = self.state.write().unwrap();
        state.finish_remaining_drawings()
    }

    // Map the default nannou shader model to a new instance, drawing with the result.
    //
    // These methods only apply to the default nannou shader model; if a custom shader model is
    // active, a warning is emitted and the operation is skipped.
    fn map_default_shader_model<F>(&self, map: F) -> Self
    where
        F: FnOnce(&mut DefaultNannouShaderModel),
    {
        match self.clone_default_shader_model() {
            Some(mut model) => {
                map(&mut model);
                self.shader_model(model)
            }
            None => {
                bevy::log::warn_once!(
                    "this operation only applies to the default nannou shader model; \
                     a custom shader model is active, so it has been skipped"
                );
                self.clone()
            }
        }
    }

    /// Produce a new [Draw] instance that will draw with the given alpha blend descriptor.
    pub fn alpha_blend(&self, blend_descriptor: wgpu::BlendComponent) -> Self {
        // TODO: check if blend is already set and only update if necessary
        self.map_default_shader_model(|model| {
            model.blend = Some(BlendState {
                color: BlendComponent::REPLACE,
                alpha: blend_descriptor,
            });
        })
    }

    /// Produce a new [Draw] instance that will draw with the given color blend descriptor.
    pub fn color_blend(&self, blend_descriptor: wgpu::BlendComponent) -> Self {
        // TODO: check if blend is already set and only update if necessary
        self.map_default_shader_model(|model| {
            model.blend = Some(BlendState {
                color: blend_descriptor,
                alpha: BlendComponent::REPLACE,
            });
        })
    }

    /// Short-hand for `color_blend`, the common use-case.
    pub fn blend(&self, blend_descriptor: wgpu::BlendComponent) -> Self {
        self.color_blend(blend_descriptor)
    }

    /// Produce a new [Draw] instance that will use the given polygon mode.
    pub fn polygon_mode(&self, polygon_mode: wgpu::PolygonMode) -> Self {
        self.map_default_shader_model(|model| model.polygon_mode = polygon_mode)
    }
}

impl Default for IntermediaryState {
    fn default() -> Self {
        let intermediary_mesh = Mesh::init();
        let path_event_buffer = Default::default();
        let path_points_vertex_buffer = Default::default();
        let text_buffer = Default::default();
        IntermediaryState {
            intermediary_mesh,
            path_event_buffer,
            path_points_vertex_buffer,
            text_buffer,
        }
    }
}

impl Default for State {
    fn default() -> Self {
        let last_shader_model = None;
        let last_draw_context = None;
        let background_color = Default::default();
        let draw_commands = Default::default();
        let drawing = Default::default();
        let intermediary_state = Arc::new(Default::default());
        let theme = Default::default();
        State {
            last_shader_model,
            last_draw_context,
            draw_commands,
            drawing,
            intermediary_state,
            theme,
            background_color,
            ignored_drawings: Default::default(),
            shader_models: Default::default(),
        }
    }
}