From 4247e64336960828e08989628772507816c9e1d7 Mon Sep 17 00:00:00 2001
From: chyyran <ronny@ronnychan.ca>
Date: Wed, 14 Feb 2024 18:10:52 -0500
Subject: [PATCH] docs: update capi docs
---
README.md | 2 +-
include/librashader.h | 5 +++--
librashader-capi/Cargo.toml | 8 +++++++-
librashader-capi/src/lib.rs | 12 ++++++------
librashader-capi/src/runtime/mtl/filter_chain.rs | 7 +++++--
librashader-reflect/src/front/glslang.rs | 2 --
librashader/Cargo.toml | 8 +++++++-
librashader/src/lib.rs | 4 ++--
8 files changed, 31 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
index dfc7202..e5c4e74 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,7 @@ linkage parameters are correct in order to successfully link with `librashader.l
The [corrosion](https://github.com/corrosion-rs/) CMake package is highly recommended.
### Thread safety
-Except for the Metsl runtime, in general, it is **safe** to create a filter chain instance from a different thread, but drawing frames requires
+Except for the Metal runtime, in general, it is **safe** to create a filter chain instance from a different thread, but drawing frames requires
**external synchronization** of the filter chain object.
Filter chains can be created from any thread, but requires external synchronization of the graphics device queue where applicable
diff --git a/include/librashader.h b/include/librashader.h
index d3e9edc..3e5b405 100644
--- a/include/librashader.h
+++ b/include/librashader.h
@@ -463,7 +463,7 @@ typedef struct _filter_chain_mtl *libra_mtl_filter_chain_t;
#endif
#if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
-/// Options for each Vulkan shader frame.
+/// Options for each Metal shader frame.
typedef struct frame_mtl_opt_t {
/// The librashader API version.
LIBRASHADER_API_VERSION version;
@@ -1746,7 +1746,7 @@ libra_error_t libra_mtl_filter_chain_get_active_pass_count(
#endif
#if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
-/// Free a Vulkan filter chain.
+/// Free a Metal filter chain.
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
@@ -1835,6 +1835,7 @@ libra_error_t libra_preset_ctx_set_param(libra_preset_ctx_t *context,
/// - GLCore
/// - Direct3D11
/// - Direct3D12
+/// - Metal
///
/// This will also set the appropriate video driver extensions.
///
diff --git a/librashader-capi/Cargo.toml b/librashader-capi/Cargo.toml
index 60666c4..29edc45 100644
--- a/librashader-capi/Cargo.toml
+++ b/librashader-capi/Cargo.toml
@@ -52,5 +52,11 @@ icrate = { version = "0.1.0" , features = [ "Metal", "Metal_all" ], optional = t
objc2 = { version = "0.5.0", features = ["apple"] , optional = true }
[package.metadata.docs.rs]
-targets = ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "aarch64-apple-darwin", "aarch64-apple-ios"]
+targets = [ "x86_64-pc-windows-msvc",
+ "x86_64-unknown-linux-gnu",
+ "x86_64-apple-darwin",
+ "aarch64-apple-darwin",
+ "aarch64-apple-ios",
+ "i686-pc-windows-msvc",
+ "i686-unknown-linux-gnu", ]
features = ["librashader/docsrs"]
diff --git a/librashader-capi/src/lib.rs b/librashader-capi/src/lib.rs
index e01c2d4..55c8b96 100644
--- a/librashader-capi/src/lib.rs
+++ b/librashader-capi/src/lib.rs
@@ -5,7 +5,7 @@
//! possible by linking against `librashader.h` as well as any static libraries used by `librashader`.
//!
//! ## Usage
-//! ⚠ Rust consumers use [librashader](https://docs.rs/librashader/) directly instead. ⚠
+//! ⚠ Rust consumers should use [librashader](https://docs.rs/librashader/) directly instead. ⚠
//!
//! The librashader C API is designed to be easy to use and safe. Most objects are only accessible behind an opaque pointer.
//! Every allocated object can be freed with a corresponding `free` function **for that specific object type**.
@@ -54,11 +54,11 @@
//!
//! ## Thread safety
//!
-//! In general, it is **safe** to create a filter chain instance from a different thread, but drawing filter passes must be
-//! synchronized externally. The exception to filter chain creation are in OpenGL, where creating the filter chain instance
-//! is safe **if and only if** the thread local OpenGL context is initialized to the same context as the drawing thread, and
-//! in Direct3D 11, where filter chain creation is unsafe if the `ID3D11Device` was created with
-//! `D3D11_CREATE_DEVICE_SINGLETHREADED`.
+//! Except for the metal runtime, it is in general, **safe** to create a filter chain instance from a different thread,
+//! but drawing filter passes must be synchronized externally. The exception to filter chain creation are in OpenGL,
+//! where creating the filter chain instance is safe **if and only if** the thread local OpenGL context is initialized
+//! to the same context as the drawing thread, and in Direct3D 11, where filter chain creation is unsafe
+//! if the `ID3D11Device` was created with `D3D11_CREATE_DEVICE_SINGLETHREADED`. Metal is entirely thread unsafe.
//!
//! You must ensure that only thread has access to a created filter pass **before** you call `*_frame`. `*_frame` may only be
//! called from one thread at a time.
diff --git a/librashader-capi/src/runtime/mtl/filter_chain.rs b/librashader-capi/src/runtime/mtl/filter_chain.rs
index 6718165..01725c0 100644
--- a/librashader-capi/src/runtime/mtl/filter_chain.rs
+++ b/librashader-capi/src/runtime/mtl/filter_chain.rs
@@ -20,14 +20,17 @@ use objc2::runtime::ProtocolObject;
use crate::LIBRASHADER_API_VERSION;
+/// An alias to a `id<MTLCommandQueue>` protocol object pointer.
pub type PMTLCommandQueue = *const ProtocolObject<dyn MTLCommandQueue>;
+/// An alias to a `id<MTLCommandBuffer>` protocol object pointer.
pub type PMTLCommandBuffer = *const ProtocolObject<dyn MTLCommandBuffer>;
+/// An alias to a `id<MTLTexture>` protocol object pointer.
pub type PMTLTexture = *const ProtocolObject<dyn MTLTexture>;
-/// Options for each Vulkan shader frame.
+/// Options for each Metal shader frame.
#[repr(C)]
#[derive(Default, Debug, Clone)]
pub struct frame_mtl_opt_t {
@@ -301,7 +304,7 @@ extern_fn! {
}
extern_fn! {
- /// Free a Vulkan filter chain.
+ /// Free a Metal filter chain.
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
diff --git a/librashader-reflect/src/front/glslang.rs b/librashader-reflect/src/front/glslang.rs
index 86f3e40..e552484 100644
--- a/librashader-reflect/src/front/glslang.rs
+++ b/librashader-reflect/src/front/glslang.rs
@@ -3,8 +3,6 @@ use glslang::{CompilerOptions, ShaderInput};
use librashader_preprocess::ShaderSource;
use crate::front::{ShaderInputCompiler, SpirvCompilation};
-#[cfg(feature = "serialize")]
-use serde::{Deserialize, Serialize};
/// glslang compiler
pub struct Glslang;
diff --git a/librashader/Cargo.toml b/librashader/Cargo.toml
index 1e7680b..2451b7e 100644
--- a/librashader/Cargo.toml
+++ b/librashader/Cargo.toml
@@ -74,6 +74,12 @@ full = ["runtime-all", "reflect-all", "preprocess", "presets"]
docsrs = ["librashader-cache/docsrs", "objc2/unstable-docsrs"]
[package.metadata.docs.rs]
-targets = ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "aarch64-apple-darwin", "aarch64-apple-ios"]
+targets = [ "x86_64-pc-windows-msvc",
+ "x86_64-unknown-linux-gnu",
+ "x86_64-apple-darwin",
+ "aarch64-apple-darwin",
+ "aarch64-apple-ios",
+ "i686-pc-windows-msvc",
+ "i686-unknown-linux-gnu", ]
features = ["docsrs"]
rustc-args = ["--cfg", "docsrs"]
diff --git a/librashader/src/lib.rs b/librashader/src/lib.rs
index 205c176..e409cbd 100644
--- a/librashader/src/lib.rs
+++ b/librashader/src/lib.rs
@@ -283,7 +283,7 @@ pub mod runtime {
#[cfg(all(target_vendor = "apple", feature = "runtime-metal"))]
#[doc(cfg(all(target_vendor = "apple", feature = "runtime-metal")))]
- /// Shader runtime for Metal
+ /// Shader runtime for Metal.
pub mod mtl {
pub use librashader_runtime_mtl::{
error,
@@ -296,7 +296,7 @@ pub mod runtime {
#[cfg(feature = "runtime-wgpu")]
#[doc(cfg(feature = "runtime-wgpu"))]
- /// Shader runtime for wgpu
+ /// Shader runtime for wgpu.
#[cfg_attr(all(feature = "runtime-wgpu", all(target_vendor = "apple", feature = "docsrs")),
doc = "\n\nThe wgpu runtime is available on macOS and iOS, but technical reasons prevent them from rendering on docs.rs.
\n\n This is because wgpu on macOS and iOS link to [metal-rs](https://github.com/gfx-rs/metal-rs), which can not build on docs.rs.