diff --git a/librashader-runtime-d3d11/src/error.rs b/librashader-runtime-d3d11/src/error.rs index 86f6cf7..fe42a82 100644 --- a/librashader-runtime-d3d11/src/error.rs +++ b/librashader-runtime-d3d11/src/error.rs @@ -1,9 +1,12 @@ +//! Direct3D11 shader runtime errors. +//! use librashader_preprocess::PreprocessError; use librashader_presets::ParsePresetError; use librashader_reflect::error::{ShaderCompileError, ShaderReflectError}; use librashader_runtime::image::ImageError; use thiserror::Error; +/// Cumulative error type for Direct3D11 filter chains. #[derive(Error, Debug)] pub enum FilterChainError { #[error("unable to get direct3d context")] @@ -24,4 +27,5 @@ pub enum FilterChainError { LutLoadError(#[from] ImageError), } +/// Result type for Direct3D11 filter chains. pub type Result = std::result::Result; diff --git a/librashader-runtime-d3d11/src/filter_chain.rs b/librashader-runtime-d3d11/src/filter_chain.rs index 40e0bcc..616edd9 100644 --- a/librashader-runtime-d3d11/src/filter_chain.rs +++ b/librashader-runtime-d3d11/src/filter_chain.rs @@ -46,6 +46,7 @@ type ShaderPassMeta = ( >, ); +/// A Direct3D 11 filter chain. pub struct FilterChain { pub(crate) common: FilterCommon, pub(crate) passes: Vec, diff --git a/librashader-runtime-d3d11/src/options.rs b/librashader-runtime-d3d11/src/options.rs index 27028a9..aa0c7de 100644 --- a/librashader-runtime-d3d11/src/options.rs +++ b/librashader-runtime-d3d11/src/options.rs @@ -1,3 +1,5 @@ +//! Direct3D11 shader runtime options. + /// Options for each Direct3D11 shader frame. #[repr(C)] #[derive(Debug, Clone)] diff --git a/librashader-runtime-d3d11/src/texture.rs b/librashader-runtime-d3d11/src/texture.rs index e1c3625..09a21bd 100644 --- a/librashader-runtime-d3d11/src/texture.rs +++ b/librashader-runtime-d3d11/src/texture.rs @@ -13,12 +13,19 @@ use windows::Win32::Graphics::Dxgi::Common::DXGI_SAMPLE_DESC; use crate::error::Result; use crate::framebuffer::OwnedFramebuffer; + +/// An image view for use as a shader resource. +/// +/// Contains an `ID3D11ShaderResourceView`, and a size. #[derive(Debug, Clone)] pub struct D3D11InputView { pub handle: ID3D11ShaderResourceView, pub size: Size, } +/// An image view for use as a render target. +/// +/// Contains an `ID3D11RenderTargetView`, and a size. #[derive(Debug, Clone)] pub struct D3D11OutputView { pub handle: ID3D11RenderTargetView, diff --git a/librashader-runtime-gl/src/error.rs b/librashader-runtime-gl/src/error.rs index b181656..d92d3a4 100644 --- a/librashader-runtime-gl/src/error.rs +++ b/librashader-runtime-gl/src/error.rs @@ -1,3 +1,5 @@ +//! OpenGL shader runtime errors. + use gl::types::GLenum; use librashader_preprocess::PreprocessError; use librashader_presets::ParsePresetError; @@ -5,6 +7,7 @@ use librashader_reflect::error::{ShaderCompileError, ShaderReflectError}; use librashader_runtime::image::ImageError; use thiserror::Error; +/// Cumulative error type for OpenGL filter chains. #[derive(Error, Debug)] pub enum FilterChainError { #[error("fbo initialization error")] @@ -27,4 +30,5 @@ pub enum FilterChainError { GLLinkError, } +/// Result type for OpenGL filter chains. pub type Result = std::result::Result; diff --git a/librashader-runtime-gl/src/filter_chain/mod.rs b/librashader-runtime-gl/src/filter_chain/mod.rs index f96c930..0078d64 100644 --- a/librashader-runtime-gl/src/filter_chain/mod.rs +++ b/librashader-runtime-gl/src/filter_chain/mod.rs @@ -16,11 +16,13 @@ mod parameters; pub(crate) use filter_impl::FilterCommon; use librashader_common::{Size, Viewport}; +/// An OpenGL filter chain. pub struct FilterChain { pub(in crate::filter_chain) filter: FilterChainDispatch, } impl FilterChain { + /// Load a filter chain from a pre-parsed `ShaderPreset`. pub fn load_from_preset( preset: ShaderPreset, options: Option<&FilterChainOptions>, diff --git a/librashader-runtime-gl/src/framebuffer.rs b/librashader-runtime-gl/src/framebuffer.rs index eba007c..7ca65f9 100644 --- a/librashader-runtime-gl/src/framebuffer.rs +++ b/librashader-runtime-gl/src/framebuffer.rs @@ -1,10 +1,17 @@ use gl::types::{GLenum, GLuint}; use librashader_common::Size; +/// A handle to an OpenGL texture with format and size information. +/// +/// Generally for use as shader resource inputs. #[derive(Default, Debug, Copy, Clone)] pub struct GLImage { + /// A GLuint to the texture. pub handle: GLuint, + /// The format of the texture. pub format: GLenum, + /// The size of the texture. pub size: Size, + /// The padded size of the texture. Currently unused and can be ignored. pub padded_size: Size, } diff --git a/librashader-runtime-gl/src/gl/framebuffer.rs b/librashader-runtime-gl/src/gl/framebuffer.rs index 3f0759e..a5381e3 100644 --- a/librashader-runtime-gl/src/gl/framebuffer.rs +++ b/librashader-runtime-gl/src/gl/framebuffer.rs @@ -6,6 +6,10 @@ use gl::types::{GLenum, GLuint}; use librashader_common::{FilterMode, ImageFormat, Size, Viewport, WrapMode}; use librashader_presets::Scale2D; + +/// A handle to an OpenGL FBO and its backing texture with format and size information. +/// +/// Generally for use as render targets. #[derive(Debug)] pub struct Framebuffer { pub(crate) image: GLuint, @@ -23,6 +27,8 @@ impl Framebuffer { } /// Create a framebuffer from an already initialized texture and framebuffer. + /// + /// The framebuffer will not be deleted when this struct is dropped. pub fn new_from_raw( texture: GLuint, fbo: GLuint, diff --git a/librashader-runtime-gl/src/options.rs b/librashader-runtime-gl/src/options.rs index 83a3b18..1a06844 100644 --- a/librashader-runtime-gl/src/options.rs +++ b/librashader-runtime-gl/src/options.rs @@ -1,3 +1,5 @@ +//! OpenGL shader runtime options. + /// Options for each OpenGL shader frame. #[repr(C)] #[derive(Debug, Clone)] diff --git a/librashader-runtime-vk/src/error.rs b/librashader-runtime-vk/src/error.rs index aac8dd5..0672b6b 100644 --- a/librashader-runtime-vk/src/error.rs +++ b/librashader-runtime-vk/src/error.rs @@ -1,9 +1,11 @@ +//! Vulkan shader runtime errors. use librashader_preprocess::PreprocessError; use librashader_presets::ParsePresetError; use librashader_reflect::error::{ShaderCompileError, ShaderReflectError}; use librashader_runtime::image::ImageError; use thiserror::Error; +/// Cumulative error type for Vulkan filter chains. #[derive(Error, Debug)] pub enum FilterChainError { #[error("SPIRV reflection error")] @@ -22,4 +24,5 @@ pub enum FilterChainError { VulkanResult(#[from] ash::vk::Result), } +/// Result type for Vulkan filter chains. pub type Result = std::result::Result; diff --git a/librashader-runtime-vk/src/filter_chain.rs b/librashader-runtime-vk/src/filter_chain.rs index 3ac60d0..d78d246 100644 --- a/librashader-runtime-vk/src/filter_chain.rs +++ b/librashader-runtime-vk/src/filter_chain.rs @@ -28,7 +28,8 @@ use std::collections::VecDeque; use std::path::Path; use crate::options::{FilterChainOptions, FrameOptions}; -pub struct Vulkan { +/// A Vulkan device and metadata that is required by the shader runtime. +pub struct VulkanDevice { pub(crate) device: ash::Device, pub(crate) memory_properties: vk::PhysicalDeviceMemoryProperties, queue: vk::Queue, @@ -54,7 +55,7 @@ pub struct VulkanInstance { pub get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr, } -impl TryFrom for Vulkan { +impl TryFrom for VulkanDevice { type Error = FilterChainError; fn try_from(vulkan: VulkanInstance) -> Result { @@ -75,7 +76,7 @@ impl TryFrom for Vulkan { let memory_properties = instance.get_physical_device_memory_properties(vulkan.physical_device); - Ok(Vulkan { + Ok(VulkanDevice { device, queue, pipeline_cache, @@ -86,7 +87,7 @@ impl TryFrom for Vulkan { } } -impl TryFrom<(vk::PhysicalDevice, ash::Instance, ash::Device)> for Vulkan { +impl TryFrom<(vk::PhysicalDevice, ash::Instance, ash::Device)> for VulkanDevice { type Error = FilterChainError; fn try_from(value: (vk::PhysicalDevice, ash::Instance, ash::Device)) -> error::Result { @@ -99,7 +100,7 @@ impl TryFrom<(vk::PhysicalDevice, ash::Instance, ash::Device)> for Vulkan { let memory_properties = value.1.get_physical_device_memory_properties(value.0); - Ok(Vulkan { + Ok(VulkanDevice { device, queue, pipeline_cache, @@ -110,10 +111,11 @@ impl TryFrom<(vk::PhysicalDevice, ash::Instance, ash::Device)> for Vulkan { } } -pub struct FilterChainVulkan { +/// A Vulkan filter chain. +pub struct FilterChain { pub(crate) common: FilterCommon, passes: Box<[FilterPass]>, - vulkan: Vulkan, + vulkan: VulkanDevice, output_framebuffers: Box<[OwnedImage]>, feedback_framebuffers: Box<[OwnedImage]>, history_framebuffers: VecDeque, @@ -136,6 +138,11 @@ pub(crate) struct FilterCommon { pub device: ash::Device, } +/// Contains residual intermediate `VkImageView` and `VkImage` objects created +/// for intermediate shader passes. +/// +/// These Vulkan objects must stay alive until the command buffer is submitted +/// to the rendering queue, and the GPU is done with the objects. #[must_use] pub struct FrameIntermediates { device: ash::Device, @@ -173,34 +180,35 @@ impl FrameIntermediates { } } -impl FilterChainVulkan { +impl FilterChain { /// Load the shader preset at the given path into a filter chain. pub fn load_from_path( - vulkan: impl TryInto, + vulkan: impl TryInto, path: impl AsRef, options: Option<&FilterChainOptions>, - ) -> error::Result { + ) -> error::Result { // load passes from preset let preset = ShaderPreset::try_parse(path)?; Self::load_from_preset(vulkan, preset, options) } + /// Load a filter chain from a pre-parsed `ShaderPreset`. pub fn load_from_preset( - vulkan: impl TryInto, + vulkan: impl TryInto, preset: ShaderPreset, options: Option<&FilterChainOptions>, - ) -> error::Result { - let (passes, semantics) = FilterChainVulkan::load_preset(preset.shaders, &preset.textures)?; + ) -> error::Result { + let (passes, semantics) = FilterChain::load_preset(preset.shaders, &preset.textures)?; let device = vulkan.try_into()?; // initialize passes let filters = Self::init_passes(&device, passes, &semantics, 3)?; - let luts = FilterChainVulkan::load_luts(&device, &preset.textures)?; + let luts = FilterChain::load_luts(&device, &preset.textures)?; let samplers = SamplerSet::new(&device.device)?; let (history_framebuffers, history_textures) = - FilterChainVulkan::init_history(&device, &filters)?; + FilterChain::init_history(&device, &filters)?; let mut output_framebuffers = Vec::new(); output_framebuffers.resize_with(filters.len(), || { @@ -222,7 +230,7 @@ impl FilterChainVulkan { let mut feedback_textures = Vec::new(); feedback_textures.resize_with(filters.len(), || None); - Ok(FilterChainVulkan { + Ok(FilterChain { common: FilterCommon { luts, samplers, @@ -303,7 +311,7 @@ impl FilterChainVulkan { } fn init_passes( - vulkan: &Vulkan, + vulkan: &VulkanDevice, passes: Vec, semantics: &ShaderSemantics, frames_in_flight: u32, @@ -377,7 +385,7 @@ impl FilterChainVulkan { } fn load_luts( - vulkan: &Vulkan, + vulkan: &VulkanDevice, textures: &[TextureConfig], ) -> error::Result> { let mut luts = FxHashMap::default(); @@ -437,7 +445,7 @@ impl FilterChainVulkan { } fn init_history( - vulkan: &Vulkan, + vulkan: &VulkanDevice, filters: &[FilterPass], ) -> error::Result<(VecDeque, Box<[Option]>)> { let mut required_images = 0; diff --git a/librashader-runtime-vk/src/framebuffer.rs b/librashader-runtime-vk/src/framebuffer.rs index a2a958a..5246b02 100644 --- a/librashader-runtime-vk/src/framebuffer.rs +++ b/librashader-runtime-vk/src/framebuffer.rs @@ -1,4 +1,4 @@ -use crate::filter_chain::Vulkan; +use crate::filter_chain::VulkanDevice; use crate::texture::VulkanImage; use crate::{error, util}; use ash::vk; @@ -13,7 +13,7 @@ pub(crate) struct OutputImage { } impl OutputImage { - pub fn new(vulkan: &Vulkan, image: VulkanImage) -> error::Result { + pub fn new(vulkan: &VulkanDevice, image: VulkanImage) -> error::Result { let image_subresource = vk::ImageSubresourceRange::builder() .base_mip_level(0) .base_array_layer(0) diff --git a/librashader-runtime-vk/src/hello_triangle/mod.rs b/librashader-runtime-vk/src/hello_triangle/mod.rs index e24b680..60ba1c1 100644 --- a/librashader-runtime-vk/src/hello_triangle/mod.rs +++ b/librashader-runtime-vk/src/hello_triangle/mod.rs @@ -8,7 +8,7 @@ mod swapchain; mod syncobjects; pub mod vulkan_base; -use crate::filter_chain::{FilterChainVulkan, Vulkan}; +use crate::filter_chain::{FilterChain, VulkanDevice}; use crate::hello_triangle::command::VulkanCommandPool; use crate::hello_triangle::framebuffer::VulkanFramebuffer; use crate::hello_triangle::pipeline::VulkanPipeline; @@ -48,7 +48,7 @@ impl VulkanWindow { event_loop: EventLoop<()>, window: winit::window::Window, vulkan: VulkanDraw, - mut filter_chain: FilterChainVulkan, + mut filter_chain: FilterChain, ) { let mut counter = 0; event_loop.run(move |event, _, control_flow| match event { @@ -136,7 +136,7 @@ impl VulkanWindow { vulkan.base.device.cmd_end_render_pass(cmd); } - fn draw_frame(frame: usize, vulkan: &VulkanDraw, filter: &mut FilterChainVulkan) { + fn draw_frame(frame: usize, vulkan: &VulkanDraw, filter: &mut FilterChain) { let index = frame % MAX_FRAMES_IN_FLIGHT; let in_flight = [vulkan.sync.in_flight[index]]; let image_available = [vulkan.sync.image_available[index]]; @@ -370,7 +370,7 @@ pub struct VulkanDraw { pub sync: SyncObjects, } -pub fn main(vulkan: VulkanBase, filter_chain: FilterChainVulkan) { +pub fn main(vulkan: VulkanBase, filter_chain: FilterChain) { let event_loop = EventLoopBuilder::new() .with_any_thread(true) .with_dpi_aware(true) diff --git a/librashader-runtime-vk/src/hello_triangle/vulkan_base.rs b/librashader-runtime-vk/src/hello_triangle/vulkan_base.rs index 7f1fe6d..9e74a6a 100644 --- a/librashader-runtime-vk/src/hello_triangle/vulkan_base.rs +++ b/librashader-runtime-vk/src/hello_triangle/vulkan_base.rs @@ -3,7 +3,7 @@ use std::borrow::Cow; use std::error::Error; use crate::error::FilterChainError; -use crate::filter_chain::Vulkan; +use crate::filter_chain::VulkanDevice; use crate::hello_triangle::debug::VulkanDebug; use crate::hello_triangle::physicaldevice::{find_queue_family, pick_physical_device}; use crate::hello_triangle::surface::VulkanSurface; @@ -158,11 +158,11 @@ impl Drop for VulkanBase { } } -impl TryFrom<&VulkanBase> for Vulkan { +impl TryFrom<&VulkanBase> for VulkanDevice { type Error = FilterChainError; fn try_from(value: &VulkanBase) -> Result { - Vulkan::try_from(( + VulkanDevice::try_from(( value.physical_device, value.instance.clone(), value.device.clone(), diff --git a/librashader-runtime-vk/src/lib.rs b/librashader-runtime-vk/src/lib.rs index 598bb64..2d1e484 100644 --- a/librashader-runtime-vk/src/lib.rs +++ b/librashader-runtime-vk/src/lib.rs @@ -20,8 +20,8 @@ mod vulkan_primitives; mod vulkan_state; pub use filter_chain::FrameIntermediates; -pub use filter_chain::FilterChainVulkan; -pub use filter_chain::Vulkan; +pub use filter_chain::FilterChain; +pub use filter_chain::VulkanDevice; pub use filter_chain::VulkanInstance; pub use texture::VulkanImage; @@ -31,7 +31,7 @@ pub mod options; #[cfg(test)] mod tests { use super::*; - use crate::filter_chain::FilterChainVulkan; + use crate::filter_chain::FilterChain; use crate::hello_triangle::vulkan_base::VulkanBase; #[test] @@ -39,7 +39,7 @@ mod tests { let entry = unsafe { ash::Entry::load().unwrap() }; let base = VulkanBase::new(entry).unwrap(); dbg!("finished"); - let mut filter = FilterChainVulkan::load_from_path( + let mut filter = FilterChain::load_from_path( &base, // "../test/slang-shaders/border/gameboy-player/gameboy-player-crt-royale.slangp", "../test/slang-shaders/bezel/Mega_Bezel/Presets/MBZ__0__SMOOTH-ADV.slangp", diff --git a/librashader-runtime-vk/src/luts.rs b/librashader-runtime-vk/src/luts.rs index 97d9c8b..f774923 100644 --- a/librashader-runtime-vk/src/luts.rs +++ b/librashader-runtime-vk/src/luts.rs @@ -1,4 +1,4 @@ -use crate::filter_chain::Vulkan; +use crate::filter_chain::VulkanDevice; use crate::texture::{InputImage, VulkanImage}; use crate::vulkan_primitives::{VulkanBuffer, VulkanImageMemory}; use crate::{error, util}; @@ -15,7 +15,7 @@ pub struct LutTexture { impl LutTexture { pub fn new( - vulkan: &Vulkan, + vulkan: &VulkanDevice, cmd: vk::CommandBuffer, image: Image, config: &TextureConfig, diff --git a/librashader-runtime-vk/src/options.rs b/librashader-runtime-vk/src/options.rs index 9c9113c..2aa83b0 100644 --- a/librashader-runtime-vk/src/options.rs +++ b/librashader-runtime-vk/src/options.rs @@ -1,3 +1,5 @@ +//! Vulkan shader runtime options. + /// Options for each Vulkan shader frame. #[repr(C)] #[derive(Debug, Clone)] diff --git a/librashader-runtime-vk/src/parameters.rs b/librashader-runtime-vk/src/parameters.rs index 8f36634..9211f6c 100644 --- a/librashader-runtime-vk/src/parameters.rs +++ b/librashader-runtime-vk/src/parameters.rs @@ -1,8 +1,8 @@ -use crate::FilterChainVulkan; +use crate::FilterChain; use librashader_runtime::parameters::FilterChainParameters; use std::collections::hash_map::Iter; -impl FilterChainParameters for FilterChainVulkan { +impl FilterChainParameters for FilterChain { fn get_enabled_pass_count(&self) -> usize { self.common.config.passes_enabled } diff --git a/librashader-runtime-vk/src/texture.rs b/librashader-runtime-vk/src/texture.rs index e09405c..6d4982a 100644 --- a/librashader-runtime-vk/src/texture.rs +++ b/librashader-runtime-vk/src/texture.rs @@ -1,4 +1,4 @@ -use crate::filter_chain::Vulkan; +use crate::filter_chain::VulkanDevice; use crate::util::find_vulkan_memory_type; use crate::vulkan_primitives::VulkanImageMemory; use crate::{error, util}; @@ -114,7 +114,7 @@ impl OwnedImage { } pub fn new( - vulkan: &Vulkan, + vulkan: &VulkanDevice, size: Size, format: ImageFormat, max_miplevels: u32, @@ -505,6 +505,7 @@ impl Drop for OwnedImage { } } +/// A handle to a `VkImage` with size and format information. #[derive(Clone)] pub struct VulkanImage { pub size: Size,