capi: document rest of capi

librashader-capi/librashader.h

@@ -52,8 +52,10 @@ typedef struct _libra_error _libra_error;
 /// parameter metadata.
 typedef struct _shader_preset _shader_preset;
 
+/// A handle to a librashader error object.
 typedef struct _libra_error *libra_error_t;
 
+/// A handle to a shader preset object.
 typedef struct _shader_preset *libra_shader_preset_t;
 
 #if defined(LIBRA_RUNTIME_OPENGL)
@@ -72,6 +74,7 @@ typedef struct filter_chain_gl_opt_t {
 } filter_chain_gl_opt_t;
 
 #if defined(LIBRA_RUNTIME_OPENGL)
+/// A handle to a OpenGL filter chain.
 typedef struct _filter_chain_gl *libra_gl_filter_chain_t;
 #endif
 
@@ -89,7 +92,7 @@ typedef struct libra_source_image_gl_t {
 } libra_source_image_gl_t;
 #endif
 
-/// Parameters for the output viewport.
+/// Defines the output viewport for a rendered frame.
 typedef struct libra_viewport_t {
     float x;
     float y;
@@ -130,6 +133,7 @@ typedef struct filter_chain_d3d11_opt_t {
 } filter_chain_d3d11_opt_t;
 
 #if defined(LIBRA_RUNTIME_D3D11)
+/// A handle to a Direct3D11 filter chain.
 typedef struct _filter_chain_d3d11 *libra_d3d11_filter_chain_t;
 #endif
 
@@ -179,6 +183,7 @@ typedef struct filter_chain_vk_opt_t {
 } filter_chain_vk_opt_t;
 
 #if defined(LIBRA_RUNTIME_VULKAN)
+/// A handle to a Vulkan filter chain.
 typedef struct _filter_chain_vk *libra_vk_filter_chain_t;
 #endif
 
@@ -204,16 +209,24 @@ typedef struct FrameOptionsVulkan {
     int32_t frame_direction;
 } FrameOptionsVulkan;
 
+/// Function pointer definition for
+///libra_preset_free
 typedef libra_error_t (*PFN_libra_preset_free)(libra_shader_preset_t *preset);
 
+/// Function pointer definition for
+///libra_preset_set_param
 typedef libra_error_t (*PFN_libra_preset_set_param)(libra_shader_preset_t *preset,
                                                     const char *name,
                                                     float value);
 
+/// Function pointer definition for
+///libra_preset_get_param
 typedef libra_error_t (*PFN_libra_preset_get_param)(libra_shader_preset_t *preset,
                                                     const char *name,
                                                     float *value);
 
+/// Function pointer definition for
+///libra_preset_print
 typedef libra_error_t (*PFN_libra_preset_print)(libra_shader_preset_t *preset);
 
 typedef libra_error_t (*PFN_libra_preset_get_runtime_param_names)(libra_shader_preset_t *preset,
@@ -230,16 +243,22 @@ typedef int32_t(*PFN_libra_error_write)(libra_error_t error, char** out);
 typedef int32_t (*PFN_libra_error_free_string)(char **out);
 
 #if defined(LIBRA_RUNTIME_OPENGL)
+/// Function pointer definition for
+///libra_gl_init_context
 typedef libra_error_t (*PFN_libra_gl_init_context)(libra_gl_loader_t loader);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
+/// Function pointer definition for
+///libra_gl_filter_chain_create
 typedef libra_error_t (*PFN_libra_gl_filter_chain_create)(libra_shader_preset_t *preset,
                                                           const struct filter_chain_gl_opt_t *options,
                                                           libra_gl_filter_chain_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
+/// Function pointer definition for
+///libra_gl_filter_chain_frame
 typedef libra_error_t (*PFN_libra_gl_filter_chain_frame)(libra_gl_filter_chain_t *chain,
                                                          size_t frame_count,
                                                          struct libra_source_image_gl_t image,
@@ -250,10 +269,14 @@ typedef libra_error_t(*PFN_libra_gl_filter_chain_frame)(libra_gl_filter_chain_t*
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
+/// Function pointer definition for
+///libra_gl_filter_chain_free
 typedef libra_error_t (*PFN_libra_gl_filter_chain_free)(libra_gl_filter_chain_t *chain);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
+/// Function pointer definition for
+///libra_d3d11_filter_chain_create
 typedef libra_error_t (*PFN_libra_d3d11_filter_chain_create)(libra_shader_preset_t *preset,
                                                              const struct filter_chain_d3d11_opt_t *options,
                                                              const ID3D11Device *device,
@@ -261,6 +284,8 @@ typedef libra_error_t(*PFN_libra_d3d11_filter_chain_create)(libra_shader_preset_
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
+/// Function pointer definition for
+///libra_d3d11_filter_chain_frame
 typedef libra_error_t (*PFN_libra_d3d11_filter_chain_frame)(libra_d3d11_filter_chain_t *chain,
                                                             size_t frame_count,
                                                             struct libra_source_image_d3d11_t image,
@@ -271,6 +296,8 @@ typedef libra_error_t(*PFN_libra_d3d11_filter_chain_frame)(libra_d3d11_filter_ch
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
+/// Function pointer definition for
+///libra_d3d11_filter_chain_free
 typedef libra_error_t (*PFN_libra_d3d11_filter_chain_free)(libra_d3d11_filter_chain_t *chain);
 #endif
 

librashader-capi/src/ctypes.rs

@@ -3,25 +3,35 @@ use crate::error::LibrashaderError;
 use librashader::presets::ShaderPreset;
 use std::ptr::NonNull;
 
+/// A handle to a shader preset object.
 pub type libra_shader_preset_t = Option<NonNull<ShaderPreset>>;
+
+/// A handle to a librashader error object.
 pub type libra_error_t = Option<NonNull<LibrashaderError>>;
 
+/// A handle to a OpenGL filter chain.
 #[cfg(feature = "runtime-opengl")]
 pub type libra_gl_filter_chain_t = Option<NonNull<librashader::runtime::gl::capi::FilterChainGL>>;
 
+/// A handle to a Direct3D11 filter chain.
 #[cfg(feature = "runtime-d3d11")]
 pub type libra_d3d11_filter_chain_t =
     Option<NonNull<librashader::runtime::d3d11::capi::FilterChainD3D11>>;
 
+/// A handle to a Vulkan filter chain.
 #[cfg(feature = "runtime-vulkan")]
 pub type libra_vk_filter_chain_t =
 Option<NonNull<librashader::runtime::vk::capi::FilterChainVulkan>>;
 
-/// Parameters for the output viewport.
+/// Defines the output viewport for a rendered frame.
 #[repr(C)]
 pub struct libra_viewport_t {
+    /// The x offset in the viewport framebuffer to begin rendering from.
     pub x: f32,
+    /// The y offset in the viewport framebuffer to begin rendering from.
     pub y: f32,
+    /// The width of the viewport framebuffer.
     pub width: u32,
+    /// The height of the viewport framebuffer.
     pub height: u32,
 }

librashader-capi/src/error.rs

@@ -47,6 +47,7 @@ pub enum LIBRA_ERRNO {
 
 // Nothing here can use extern_fn because they are lower level than libra_error_t.
 
+/// Function pointer definition for libra_error_errno
 pub type PFN_libra_error_errno = extern "C" fn(error: libra_error_t) -> LIBRA_ERRNO;
 #[no_mangle]
 /// Get the error code corresponding to this error object.
@@ -61,6 +62,7 @@ pub extern "C" fn libra_error_errno(error: libra_error_t) -> LIBRA_ERRNO {
     unsafe { error.as_ref().get_code() }
 }
 
+/// Function pointer definition for libra_error_print
 pub type PFN_libra_error_print = extern "C" fn(error: libra_error_t) -> i32;
 #[no_mangle]
 /// Print the error message.
@@ -79,6 +81,7 @@ pub extern "C" fn libra_error_print(error: libra_error_t) -> i32 {
     return 0;
 }
 
+/// Function pointer definition for libra_error_free
 pub type PFN_libra_error_free = extern "C" fn(error: *mut libra_error_t) -> i32;
 #[no_mangle]
 /// Frees any internal state kept by the error.
@@ -102,6 +105,7 @@ pub extern "C" fn libra_error_free(error: *mut libra_error_t) -> i32 {
     return 0;
 }
 
+/// Function pointer definition for libra_error_write
 pub type PFN_libra_error_write =
     extern "C" fn(error: libra_error_t, out: *mut MaybeUninit<*mut c_char>) -> i32;
 #[no_mangle]
@@ -133,6 +137,7 @@ pub extern "C" fn libra_error_write(
     return 0;
 }
 
+/// Function pointer definition for libra_error_free_string
 pub type PFN_libra_error_free_string = extern "C" fn(out: *mut *mut c_char) -> i32;
 #[no_mangle]
 /// Frees an error string previously allocated by `libra_error_write`.

librashader-capi/src/ffi.rs

@@ -59,7 +59,9 @@ macro_rules! ffi_body {
 
 macro_rules! extern_fn {
     ($(#[$($attrss:tt)*])* fn $func_name:ident ($($arg_name:ident : $arg_ty:ty),*) $body:block) => {
-        paste::paste! {
+        ::paste::paste! {
+            /// Function pointer definition for
+            #[doc = ::std::stringify!($func_name)]
             pub type [<PFN_ $func_name>] = unsafe extern "C" fn($($arg_name: $arg_ty,)*) -> $crate::ctypes::libra_error_t;
         }
 
@@ -71,7 +73,9 @@ macro_rules! extern_fn {
     };
 
     ($(#[$($attrss:tt)*])* raw fn $func_name:ident ($($arg_name:ident : $arg_ty:ty),*) $body:block) => {
-        paste::paste! {
+        ::paste::paste! {
+            /// Function pointer definition for
+            #[doc = ::std::stringify!($func_name)]
             pub type [<PFN_ $func_name>] = unsafe extern "C" fn($($arg_name: $arg_ty,)*) -> $crate::ctypes::libra_error_t;
         }
 
@@ -83,7 +87,9 @@ macro_rules! extern_fn {
     };
 
     ($(#[$($attrss:tt)*])* fn $func_name:ident ($($arg_name:ident : $arg_ty:ty),*) |$($ref_capture:ident),*|; mut |$($mut_capture:ident),*| $body:block) => {
-        paste::paste! {
+        ::paste::paste! {
+            /// Function pointer definition for
+            #[doc = ::std::stringify!($func_name)]
             pub type [<PFN_ $func_name>] = unsafe extern "C" fn($($arg_name: $arg_ty,)*) -> $crate::ctypes::libra_error_t;
         }
 
@@ -95,7 +101,9 @@ macro_rules! extern_fn {
     };
 
     ($(#[$($attrss:tt)*])* fn $func_name:ident ($($arg_name:ident : $arg_ty:ty),*) mut |$($mut_capture:ident),*| $body:block) => {
-        paste::paste! {
+        ::paste::paste! {
+            /// Function pointer definition for
+            #[doc = ::std::stringify!($func_name)]
             pub type [<PFN_ $func_name>] = unsafe extern "C" fn($($arg_name: $arg_ty,)*) -> $crate::ctypes::libra_error_t;
         }
 
@@ -106,7 +114,9 @@ macro_rules! extern_fn {
         }
     };
     ($(#[$($attrss:tt)*])* fn $func_name:ident ($($arg_name:ident : $arg_ty:ty),*) |$($ref_capture:ident),*| $body:block) => {
-        paste::paste! {
+        ::paste::paste! {
+            /// Function pointer definition for
+             #[doc = ::std::stringify!($func_name)]
              pub type [<PFN_ $func_name>] = unsafe extern "C" fn($($arg_name: $arg_ty,)*) -> $crate::ctypes::libra_error_t;
         }
 

librashader-capi/src/presets.rs

@@ -113,6 +113,7 @@ extern_fn! {
 }
 
 // can't use extern_fn! for this because of the mut.
+/// Function pointer definition for libra_preset_get_runtime_param_names
 pub type PFN_libra_preset_get_runtime_param_names = unsafe extern "C" fn(
     preset: *mut libra_shader_preset_t,
     value: MaybeUninit<*mut *const c_char>,
@@ -121,7 +122,8 @@ pub type PFN_libra_preset_get_runtime_param_names = unsafe extern "C" fn(
 /// Get a list of runtime parameter names.
 ///
 /// The returned value can not currently be freed.
-/// This function should be considered in progress. Its use is discouraged.
+/// This function should be considered work in progress. Its use is discouraged.
+/// Removal of this function is exempted from semantic versioning.
 #[no_mangle]
 pub unsafe extern "C" fn libra_preset_get_runtime_param_names(
     preset: *mut libra_shader_preset_t,