mew/

lib.rs

#![doc(html_logo_url = "https://64-tesseract.ftp.sh/tesseract.gif", html_favicon_url = "https://64-tesseract.ftp.sh/tesseract.gif")]
#![doc = include_str!("../README.md")]

#![cfg_attr(docs, feature(doc_cfg))]
#![cfg_attr(docs, doc(auto_cfg(hide(docs))))]

use std::{
    any::TypeId,
    cell::RefCell,
    collections::BTreeMap,
};
use thiserror::Error;

pub use wgpu;
#[cfg(feature = "poll")]
pub use pollster;
#[cfg(feature = "winit")]
pub use winit;

pub mod doc_example;

mod macromath;
pub mod bindgroup;
pub mod buffer;
pub mod pipeline;
pub mod sampler;
pub mod shaderprimitive;
pub mod shaderstruct;
pub mod texture;
//pub mod typemap;
pub mod vertexformat;
pub mod vertexstruct;
#[cfg(any(feature = "winit", docs))]
pub mod winitutils;

pub mod prelude {
    pub use crate::{
        bindgroup::*,
        buffer::*,
        pipeline::*,
        sampler::*,
        shaderprimitive,
        shaderstruct::*,
        texture::*,
        vertexformat,
        vertexstruct::*,
        *,
    };
    #[cfg(feature = "winit")]
    pub use crate::winitutils::*;
}


/*
/// The master object that manages everything `wgpu`-related.
///
/// On construction it initializes the instance, adapter, device, and queue
/// using some default settings so you don't need to worry about that repetitive
/// boilerplate. Not all options are customizable but it should work well
/// enough.
///
/// The render context also keeps track of your buffer, bind group, texture,
/// and pipeline definition types, so you can construct the from a central
/// location. Since regular macros don't support changing identifiers, this is
/// implemented by type parameters.
///
/// ```
/// render_context! { Context {
///     // List of `wgpu::Features` for the device
///     features: [MULTIVIEW, VERTEX_WRITABLE_STORAGE],  // idk I usually just leave these blank
///     // Map of values to override from `wgpu::Limits` defaults for the device
///     limits: {max_vertex_attributes: 17, max_vertex_buffers: 4},  // same here, random values - definitely don't use
///     // Numbered (and ordered!) list of your bind group definitions
///     bind_groups: [
///         0 => GroupOne,
///         1 => GroupThree,
///         2 => GroupNegativeSixtyNine,
///     ],
///     // Also numbered (and also ordered!) list of your pipeline definitions
///     pipelines: [
///         0 => MainPipeline,
///         1 => NotMainPipeline,
///     ],
/// } }
/// ```
#[macro_export]
macro_rules! render_context {
    { $struct:ident {
        features: [
            $( $feature:ident ),* $(,)?
        ],
        limits: {
            $( $limit:ident : $limitval:expr ),* $(,)?
        },
        bind_groups: [
            $( $bindgroupnum:tt => $bindgroup:ty ),* $(,)?
        ],
        pipelines: [
            $( $pipelinenum:tt => $pipeline:ty ),* $(,)?
        ] $(,)?
    } } => {
        typemap! { BindGroupLayoutTypes [
            $( $bindgroupnum => $crate::bindgroup::MewBindGroupLayout<$bindgroup> , )*
        ] }

        typemap! { PipelineLayoutTypes [
            $( $pipelinenum => $crate::pipeline::MewPipelineLayout<$pipeline> , )*
        ] }

        pub struct $struct {
            pub instance: $crate::wgpu::Instance,
            pub adapter: $crate::wgpu::Adapter,
            pub device: $crate::wgpu::Device,
            pub queue: $crate::wgpu::Queue,
            bind_group_layouts: BindGroupLayoutTypes,
            pipeline_layouts: PipelineLayoutTypes,
        }

        impl $struct {
            pub async fn new(backends: $crate::wgpu::Backends) -> Result<Self, Box<dyn ::std::error::Error>> {
                let instance = $crate::wgpu::Instance::new(&wgpu::InstanceDescriptor {
                    backends,
                    flags: $crate::wgpu::InstanceFlags::empty(),
                    ..Default::default()
                });

                Self::new_with_instance(instance).await
            }

            pub async fn new_with_instance(instance: $crate::wgpu::Instance) -> Result<Self, Box<dyn ::std::error::Error>> {
                let adapter = instance.request_adapter(
                    &$crate::wgpu::RequestAdapterOptions {
                        power_preference: $crate::wgpu::PowerPreference::default(),
                        compatible_surface: None,
                        force_fallback_adapter: false,
                    },
                ).await.inspect_err(|e| eprintln!("Could not get display adapter: {e}"))?;

                let (device, queue) = adapter.request_device(
                    &$crate::wgpu::DeviceDescriptor {
                        label: Some("Device"),
                        required_features: $crate::wgpu::Features::empty() $( | $crate::wgpu::Features::$feature )*,
                        required_limits: $crate::wgpu::Limits {
                            $( $limit: $limitval, )*
                            ..Default::default()
                        },
                        memory_hints: Default::default(),
                        trace: $crate::wgpu::Trace::Off,
                    }
                ).await.inspect_err(|e| eprintln!("Could not get display device: {e}"))?;

                let bind_group_layouts = BindGroupLayoutTypes (
                    $( {
                        let desc = <$bindgroup>::layout_desc();
                        let layout = device.create_bind_group_layout(&desc);
                        $crate::bindgroup::MewBindGroupLayout::new(layout)
                    }, )*
                );

                let pipeline_layouts = PipelineLayoutTypes (
                    $( {
                        let bind_groups = <$pipeline>::get_layouts_from_refs(&bind_group_layouts);
                        let bind_groups_arr = <$pipeline>::bind_group_layouts(&bind_groups);
                        let desc = <$pipeline>::layout_desc(&bind_groups_arr);
                        let layout = device.create_pipeline_layout(&desc);
                        $crate::pipeline::MewPipelineLayout::new(layout)
                    }, )*
                );

                Ok(Self {
                    instance,
                    adapter,
                    device,
                    queue,
                    bind_group_layouts,
                    pipeline_layouts,
                })
            }

            pub fn new_buffer<BUFFER: $crate::buffer::MewBuffer>(&self, inner_size: u64) -> BUFFER {
                let raw_buffer = self.device.create_buffer(&BUFFER::buffer_desc(inner_size));
                BUFFER::new(raw_buffer)
            }

            pub fn new_sampler<SAMPLER: $crate::sampler::MewSampler>(&self) -> SAMPLER {
                let raw_sampler = self.device.create_sampler(&SAMPLER::buffer_desc());
                SAMPLER::new(raw_sampler)
            }

            pub fn new_texture<TEXTURE: $crate::texture::MewTexture>(&self, inner_size: (u32, u32, u32), format: $crate::wgpu::TextureFormat) -> TEXTURE {
                let raw_texture = self.device.create_texture(&TEXTURE::buffer_desc(inner_size, format));
                TEXTURE::new(raw_texture)
            }

            pub fn new_bind_group<BIND: $crate::bindgroup::MewBindGroup>(&self, buffers: BIND::BufferSet) -> BIND
            where
                BindGroupLayoutTypes: AsRef<$crate::bindgroup::MewBindGroupLayout<BIND>>
            {
                let raw_bind_group = {
                    let layout: &$crate::bindgroup::MewBindGroupLayout<BIND> = self.bind_group_layouts.as_ref();
                    let entries = BIND::bind_group_entries(&buffers);
                    let desc = BIND::bind_group_desc(layout, &entries);
                    self.device.create_bind_group(&desc)
                };
                BIND::new(raw_bind_group, buffers)
            }

            pub fn new_pipeline<PIPE: $crate::pipeline::MewPipeline>(
                &self,
                surface_fmt: Option<$crate::wgpu::TextureFormat>,
                shader: &$crate::wgpu::ShaderModule,
                vertex_entry: Option<&str>,
                fragment_entry: Option<&str>,
            ) -> PIPE
            where
                PipelineLayoutTypes: AsRef<$crate::pipeline::MewPipelineLayout<PIPE>>
            {
                let raw_pipeline = {
                    let layout: &$crate::pipeline::MewPipelineLayout<PIPE> = self.pipeline_layouts.as_ref();
                    let targets = PIPE::fragment_targets(surface_fmt);
                    let desc = &PIPE::pipeline_desc(layout, shader, vertex_entry, fragment_entry, &targets);
                    self.device.create_render_pipeline(desc)
                };
                PIPE::new(raw_pipeline)
            }
        }

        impl $crate::MewRenderContext for $struct {
            fn instance(&self) -> &wgpu::Instance {
                &self.instance
            }

            fn adapter(&self) -> &wgpu::Adapter {
                &self.adapter
            }

            fn device(&self) -> &wgpu::Device {
                &self.device
            }

            fn queue(&self) -> &wgpu::Queue {
                &self.queue
            }
        }
    };
}
*/


/// Error returned when trying to build a context.
#[derive(Clone, Debug, Error)]
pub enum BuildContextError {
    /// Requesting the adapter failed, see
    /// [`wgpu::Instance::request_adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html#method.request_adapter).
    #[error(transparent)]
    Adapter(#[from] wgpu::RequestAdapterError),
    /// Requesting the device failed, see
    /// [`wgpu::Adapter::request_device`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html#method.request_device).
    #[error(transparent)]
    Device(#[from] wgpu::RequestDeviceError),
}


/// A builder abstraction for making a [`RenderContext`].
///
/// It's possible to make one directly with [`RenderContext::new`], but you need
/// to provide everything manually. This builder takes care of initilizing the
/// _wgpu_ handles for you with default values.
#[must_use]
#[derive(Clone, Debug)]
pub struct RenderContextBuilder {
    instance: Result<wgpu::Instance, wgpu::Backends>,
    compatible_surface: Option<std::sync::Arc<wgpu::Surface<'static>>>,
    features: wgpu::Features,
    limits: wgpu::Limits,
}

impl RenderContextBuilder {
    /// Prepare a new builder, providing your own
    /// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html).
    pub fn new_with_instance(instance: wgpu::Instance) -> Self {
        #[allow(unused_mut)]
        let mut builder = Self {
            instance: Ok(instance),
            compatible_surface: None,
            features: wgpu::Features::default(),
            limits: wgpu::Limits::default(),
        };
        #[cfg(feature = "webgl")]
        builder.with_limits(wgpu::Limits::downlevel_webgl2_defaults());
        builder
    }

    /// Prepare a new builder, specifying the
    /// [`wgpu::Backends`](https://docs.rs/wgpu/latest/wgpu/struct.Backends.html)
    /// you want to support.
    ///
    /// The
    /// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html)
    /// will be built later when needed with these backends.
    pub fn new_with_backends(backends: wgpu::Backends) -> Self {
        #[allow(unused_mut)]
        let mut builder = Self {
            instance: Err(backends),
            compatible_surface: None,
            features: wgpu::Features::default(),
            limits: wgpu::Limits::default(),
        };
        #[cfg(feature = "webgl")]
        builder.with_limits(wgpu::Limits::downlevel_webgl2_defaults());
        builder
    }

    /// Specify a compatible surface for the
    /// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html).
    ///
    /// This is required by WebGL and really annoying to set up, see
    /// [`winitutils::DeferredContext`].
    pub fn with_compatible_surface(&mut self, surface: Option<std::sync::Arc<wgpu::Surface<'static>>>) -> &mut Self {
        self.compatible_surface = surface;
        self
    }

    /// Specify the
    /// [`wgpu::Features`](https://docs.rs/wgpu/latest/wgpu/struct.Features.html)
    /// the
    /// [`wgpu::Device`](https://docs.rs/wgpu/latest/wgpu/struct.Device.html)
    /// will require.
    pub fn with_features(&mut self, features: wgpu::Features) -> &mut Self {
        self.features = features;
        self
    }

    /// Specify the
    /// [`wgpu::Limits`](https://docs.rs/wgpu/latest/wgpu/struct.Limits.html)
    /// the
    /// [`wgpu::Device`](https://docs.rs/wgpu/latest/wgpu/struct.Device.html)
    /// will require.
    ///
    /// On web, this is automatically set to
    /// [`wgpu::Limits::downlevel_webgl2_defaults`](https://docs.rs/wgpu/latest/wgpu/struct.Limits.html#method.downlevel_webgl2_defaults),
    /// but is overridable if you really want to.  
    /// On native, it's just [`Default::default`].
    pub fn with_limits(&mut self, limits: wgpu::Limits) -> &mut Self {
        self.limits = limits;
        self
    }

    /// Get a copy of the
    /// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html)
    /// that'll be used to get the rest of the _wgpu_ handles.
    ///
    /// If this wasn't provided when building, it'll be generated now.
    pub fn get_instance(&mut self) -> wgpu::Instance {
        self.instance = Ok(self.instance.clone().unwrap_or_else(|backends| wgpu::Instance::new(&wgpu::InstanceDescriptor {
            backends,
            ..Default::default()
        })));
        self.instance.clone().unwrap()
    }

    /// Try to build the [`RenderContext`] with the configured settings.
    ///
    /// This function is `async` because
    /// [`wgpu::Instance::request_adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html#method.request_adapter)
    /// and
    /// [`wgpu::Adapter::request_device`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html#method.request_device)
    /// are for some reason.  
    /// On native, you can use [`Self::build_poll`]. On web, you need to spawn a JS
    /// thread to await this, or use [`Self::deferred`] which does this internally.
    pub async fn build(mut self) -> Result<RenderContext, BuildContextError> {
        let instance = self.get_instance();

        let adapter = instance.request_adapter(
            &wgpu::RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::default(),
                compatible_surface: self.compatible_surface.as_deref(),
                force_fallback_adapter: false,
            },
        ).await?;

        let (device, queue) = adapter.request_device(
            &wgpu::DeviceDescriptor {
                label: Some("Device"),
                required_features: self.features,
                required_limits: self.limits,
                ..Default::default()
            }
        ).await?;

        Ok(RenderContext::new(instance, adapter, device, queue))
    }

    /// Try to build the [`RenderContext`] with the configured settings, but block
    /// on the result with _pollster_.
    #[cfg(any(feature = "poll", docs))]
    pub fn build_poll(self) -> Result<RenderContext, BuildContextError> {
        pollster::block_on(self.build())
    }

    /// Put this builder into a [`winitutils::DeferredContext`], which on web will
    /// automate running [`Self::with_compatible_surface`] when a window is created
    /// and build the [`RenderContext`] as soon as it can.
    #[cfg(any(all(feature = "winit", any(feature = "webgl", feature = "poll")), docs))]
    pub fn deferred(self) -> winitutils::DeferredContext {
        winitutils::DeferredContext::new(self)
    }
}


#[derive(Debug)]
struct LayoutMaps {
    bind_groups: RefCell<BTreeMap<TypeId, wgpu::BindGroupLayout>>,
    pipelines: RefCell<BTreeMap<TypeId, wgpu::PipelineLayout>>,
}

impl LayoutMaps {
    fn new() -> Self {
        Self {
            bind_groups: RefCell::new(BTreeMap::new()),
            pipelines: RefCell::new(BTreeMap::new()),
        }
    }
}


/// The heart of _mew_. Bundles all necessary _wgpu_ handles and takes care of
/// constructing buffers, bind groups, & pipelines with a single function call.
#[derive(Debug)]
pub struct RenderContext {
    pub instance: wgpu::Instance,
    pub adapter: wgpu::Adapter,
    pub device: wgpu::Device,
    pub queue: wgpu::Queue,
    // TODO: Potentially put in Rc & allow Clone
    layouts: LayoutMaps,
}

impl RenderContext {
    /// Build a context manually by providing the
    /// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html),
    /// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html),
    /// [`wgpu::Device`](https://docs.rs/wgpu/latest/wgpu/struct.Device.html),
    /// and
    /// [`wgpu::Queue`](https://docs.rs/wgpu/latest/wgpu/struct.Queue.html).
    ///
    /// You can build this directly , but a [`RenderContextBuilder`] takes care of
    /// the annoying stuff for you.
    pub fn new(instance: wgpu::Instance, adapter: wgpu::Adapter, device: wgpu::Device, queue: wgpu::Queue) -> Self {
        Self {
            instance,
            adapter,
            device,
            queue,
            layouts: LayoutMaps::new(),
        }
    }

    /// Build a new buffer with an internal capacity to fit its internal type.
    ///
    /// The type of buffer it makes is determined by its type parameter.
    ///
    /// ```
    /// buffer! { SomeBuffer <InternalType> as STORAGE | COPY_DST }
    /// let buffer: SomeBuffer = context.new_buffer(10);
    /// assert_eq!(buffer.size() as usize, size_of::<InternalType>() * 10);
    /// ```
    pub fn new_buffer<BUFFER: buffer::MewBuffer>(&self, inner_size: u64) -> BUFFER {
        let raw_buffer = self.device.create_buffer(&BUFFER::buffer_desc(inner_size));
        BUFFER::new(raw_buffer)
    }

    /// Build a new sampler.
    ///
    /// The type of sampler it makes is determined by its type parameter.
    ///
    /// ```
    /// sampler! { SomeSampler as Filtering }
    /// let sampler: SomeSampler = context.new_sampler();
    /// ```
    pub fn new_sampler<SAMPLER: sampler::MewSampler>(&self) -> SAMPLER {
        let raw_sampler = self.device.create_sampler(&SAMPLER::buffer_desc());
        SAMPLER::new(raw_sampler)
    }

    /// Build a new sampler with dimensions and a
    /// [`wgpu::TextureFormat`](https://docs.rs/wgpu/latest/wgpu/enum.TextureFormat.html).
    ///
    /// The type of texture it makes is determined by its type parameter.
    ///
    /// ```
    /// texture! { SomeTexture { ... } }
    /// let texture: SomeTexture = context.new_texture((64, 64, 1), wgpu::TextureFormat::Rgba8Unorm);
    /// ```
    pub fn new_texture<TEXTURE: texture::MewTexture>(&self, inner_size: (u32, u32, u32), format: wgpu::TextureFormat) -> TEXTURE {
        let raw_texture = self.device.create_texture(&TEXTURE::buffer_desc(inner_size, format));
        TEXTURE::new(raw_texture)
    }

    fn get_bind_group_layout_manual(&self, type_id: TypeId, desc: &wgpu::BindGroupLayoutDescriptor<'static>) -> wgpu::BindGroupLayout {
        let mut layouts = self.layouts.bind_groups.borrow_mut();
        layouts.entry(type_id).or_insert_with(|| self.device.create_bind_group_layout(desc)).clone()
    }

    fn get_bind_group_layout<BIND: bindgroup::MewBindGroup + 'static>(&self) -> bindgroup::MewBindGroupLayout<BIND> {
        let layout = self.get_bind_group_layout_manual(TypeId::of::<BIND>(), &BIND::layout_desc());
        bindgroup::MewBindGroupLayout::new(layout)
    }

    /// Build a new buffer with a tuple of its bind groups.
    ///
    /// The type of bind group it makes is determined by its type parameter.
    ///
    /// ```
    /// bind_group! { StuffBindGroup [
    ///     0 buffer_one @ VERTEX => SomeBuffer,
    ///     1 other_buffer @ FRAGMENT => SomeOtherBuffer,
    /// ] }
    /// let bind_group: SomeBindGroup = render_context.new_bind_group((buffer, other_buffer));
    /// ```
    pub fn new_bind_group<BIND: bindgroup::MewBindGroup + 'static>(&self, buffers: BIND::BufferSet) -> BIND {
        let raw_bind_group = {
            let layout = self.get_bind_group_layout::<BIND>();
            let entries = BIND::bind_group_entries(&buffers);
            let desc = BIND::bind_group_desc(&layout, &entries);
            self.device.create_bind_group(&desc)
        };
        BIND::new(raw_bind_group, buffers)
    }


    fn get_pipeline_layout<'a, PIPE: pipeline::MewPipeline + 'static>(&self) -> pipeline::MewPipelineLayout<PIPE> {
        let layout = {
            let mut layouts = self.layouts.pipelines.borrow_mut();
            layouts.entry(TypeId::of::<PIPE>()).or_insert_with(|| {
                let bind_group_descs = PIPE::bind_group_layout_types_array();
                let bind_group_layouts = PIPE::map_bind_group_array(&bind_group_descs, |(type_id, desc)| self.get_bind_group_layout_manual(*type_id, desc));
                //let bind_group_refs = PIPE::bind_group_ref_array(&bind_group_layouts);
                // &[_] -> [&_]
                let bind_group_refs = PIPE::map_bind_group_array(&bind_group_layouts, |layout| layout);
                let desc = PIPE::layout_desc(&bind_group_refs);
                self.device.create_pipeline_layout(&desc)
            }).clone()
        };
        pipeline::MewPipelineLayout::new(layout)
    }

    /// Build a new pipeline given a
    /// [`wgpu::TextureFormat`](https://docs.rs/wgpu/latest/wgpu/enum.TextureFormat.html),
    /// a
    /// [`wgpu::ShaderModule`](https://docs.rs/wgpu/latest/wgpu/enum.ShaderModule.html)
    /// (that you need to construct yourself), and the shader's entry points (or
    /// `None` if you only have one entry point).
    ///
    /// The type of pipeline it makes is determined by its type parameter.
    ///
    /// ```
    /// pipeline! { Pipeline { ... } }
    /// let pipeline: Pipeline = render_context.new_pipeline(wgpu::Rgba8Unorm, shader, Some("vs_main"), None);
    /// ```
    pub fn new_pipeline<PIPE: pipeline::MewPipeline + 'static>(
        &self,
        surface_fmt: wgpu::TextureFormat,
        shader: &wgpu::ShaderModule,
        vertex_entry: Option<&str>,
        fragment_entry: Option<&str>,
    ) -> PIPE {
        let raw_pipeline = {
            let layout = self.get_pipeline_layout::<PIPE>();
            let targets = PIPE::fragment_targets(surface_fmt);
            let desc = &PIPE::pipeline_desc(&layout, shader, vertex_entry, fragment_entry, &targets);
            self.device.create_render_pipeline(desc)
        };
        PIPE::new(raw_pipeline)
    }
}