From 72a98272f3d693a76f36e39e1ed2aa46e4286760 Mon Sep 17 00:00:00 2001 From: chyyran Date: Sat, 21 Sep 2024 01:41:18 -0400 Subject: [PATCH] doc(capi): document all C API members --- librashader-capi/src/ctypes.rs | 12 ++++++++- librashader-capi/src/error.rs | 43 +++++++++++++++++++++++++++++++++ librashader-capi/src/lib.rs | 1 + librashader-capi/src/version.rs | 1 + 4 files changed, 56 insertions(+), 1 deletion(-) diff --git a/librashader-capi/src/ctypes.rs b/librashader-capi/src/ctypes.rs index 2a1c4a7..ced4d1c 100644 --- a/librashader-capi/src/ctypes.rs +++ b/librashader-capi/src/ctypes.rs @@ -18,7 +18,9 @@ pub type libra_error_t = Option>; #[repr(u32)] #[derive(Debug, Copy, Clone)] pub enum LIBRA_PRESET_CTX_ORIENTATION { + /// Context parameter for vertical orientation. Vertical = 0, + /// Context parameter for horizontal orientation. Horizontal, } impl From for Orientation { @@ -30,15 +32,21 @@ impl From for Orientation { } } -// An enum representing graphics runtimes (video drivers) for use in preset contexts. +/// An enum representing graphics runtimes (video drivers) for use in preset contexts. #[repr(u32)] #[derive(Debug, Copy, Clone)] pub enum LIBRA_PRESET_CTX_RUNTIME { + /// No runtime. None = 0, + /// OpenGL 3.3+ GlCore, + /// Vulkan Vulkan, + /// Direct3D 11 D3D11, + /// Direct3D 12 D3D12, + /// Metal Metal, } @@ -120,6 +128,8 @@ pub type libra_vk_filter_chain_t = Option>; #[cfg(all(target_os = "macos", feature = "runtime-metal"))] use librashader::runtime::mtl::FilterChain as FilterChainMetal; + +/// A handle to a Vulkan filter chain. #[cfg_attr( feature = "docsrs", doc(cfg(all(target_vendor = "apple", feature = "runtime-metal"))) diff --git a/librashader-capi/src/error.rs b/librashader-capi/src/error.rs index 1fce88e..542eb46 100644 --- a/librashader-capi/src/error.rs +++ b/librashader-capi/src/error.rs @@ -9,26 +9,45 @@ use thiserror::Error; #[non_exhaustive] #[derive(Error, Debug)] pub enum LibrashaderError { + /// An unknown error or panic occurred. #[error("There was an unknown error.")] UnknownError(Box), + + /// An invalid parameter (likely null), was passed. #[error("The parameter was null or invalid.")] InvalidParameter(&'static str), + + /// The string provided was not valid UTF-8. #[error("The provided string was not valid UTF8.")] InvalidString(#[from] std::str::Utf8Error), + + /// An error occurred in the preset parser. #[error("There was an error parsing the preset.")] PresetError(#[from] librashader::presets::ParsePresetError), + + /// An error occurred in the shader preprocessor. #[error("There was an error preprocessing the shader source.")] PreprocessError(#[from] librashader::preprocess::PreprocessError), + + /// An error occurred in the shader compiler. #[error("There was an error compiling the shader source.")] ShaderCompileError(#[from] librashader::reflect::ShaderCompileError), + + /// An error occrred when validating and reflecting the shader. #[error("There was an error reflecting the shader source.")] ShaderReflectError(#[from] librashader::reflect::ShaderReflectError), + + /// An invalid shader parameter name was provided. #[error("The provided parameter name was invalid.")] UnknownShaderParameter(*const c_char), + + /// An error occurred with the OpenGL filter chain. #[cfg(feature = "runtime-opengl")] #[cfg_attr(feature = "docsrs", doc(cfg(feature = "runtime-opengl")))] #[error("There was an error in the OpenGL filter chain.")] OpenGlFilterError(#[from] librashader::runtime::gl::error::FilterChainError), + + /// An error occurred with the Direct3D 11 filter chain. #[cfg(all(target_os = "windows", feature = "runtime-d3d11"))] #[cfg_attr( feature = "docsrs", @@ -36,6 +55,8 @@ pub enum LibrashaderError { )] #[error("There was an error in the D3D11 filter chain.")] D3D11FilterError(#[from] librashader::runtime::d3d11::error::FilterChainError), + + /// An error occurred with the Direct3D 12 filter chain. #[cfg(all(target_os = "windows", feature = "runtime-d3d12"))] #[cfg_attr( feature = "docsrs", @@ -43,6 +64,8 @@ pub enum LibrashaderError { )] #[error("There was an error in the D3D12 filter chain.")] D3D12FilterError(#[from] librashader::runtime::d3d12::error::FilterChainError), + + /// An error occurred with the Direct3D 9 filter chain. #[cfg(all(target_os = "windows", feature = "runtime-d3d9"))] #[cfg_attr( feature = "docsrs", @@ -50,10 +73,15 @@ pub enum LibrashaderError { )] #[error("There was an error in the D3D9 filter chain.")] D3D9FilterError(#[from] librashader::runtime::d3d9::error::FilterChainError), + + /// An error occurred with the Vulkan filter chain. + #[cfg(feature = "runtime-vulkan")] #[cfg_attr(feature = "docsrs", doc(cfg(feature = "runtime-vulkan")))] #[error("There was an error in the Vulkan filter chain.")] VulkanFilterError(#[from] librashader::runtime::vk::error::FilterChainError), + + /// An error occurred with the Metal filter chain. #[cfg_attr( feature = "docsrs", doc(cfg(all(target_vendor = "apple", feature = "runtime-metal"))) @@ -66,13 +94,28 @@ pub enum LibrashaderError { /// Error codes for librashader error types. #[repr(i32)] pub enum LIBRA_ERRNO { + /// Error code for an unknown error. UNKNOWN_ERROR = 0, + + /// Error code for an invalid parameter. INVALID_PARAMETER = 1, + + /// Error code for an invalid (non-UTF8) string. INVALID_STRING = 2, + + /// Error code for a preset parser error. PRESET_ERROR = 3, + + /// Error code for a preprocessor error. PREPROCESS_ERROR = 4, + + /// Error code for a shader parameter error. SHADER_PARAMETER_ERROR = 5, + + /// Error code for a reflection error. REFLECT_ERROR = 6, + + /// Error code for a runtime error. RUNTIME_ERROR = 7, } diff --git a/librashader-capi/src/lib.rs b/librashader-capi/src/lib.rs index 9cc4b92..d2bcfee 100644 --- a/librashader-capi/src/lib.rs +++ b/librashader-capi/src/lib.rs @@ -1,3 +1,4 @@ +#![forbid(missing_docs)] //! The C API for [librashader](https://docs.rs/librashader/). //! //! The librashader C API is designed to be loaded dynamically via `librashader_ld.h`, but static usage is also diff --git a/librashader-capi/src/version.rs b/librashader-capi/src/version.rs index 6090be5..bcc0745 100644 --- a/librashader-capi/src/version.rs +++ b/librashader-capi/src/version.rs @@ -2,6 +2,7 @@ /// API version type alias. pub type LIBRASHADER_API_VERSION = usize; +/// ABI version type alias. pub type LIBRASHADER_ABI_VERSION = usize; /// The current version of the librashader API.