capi: fix outdated header definition

Cargo.lock

@@ -1303,9 +1303,9 @@ dependencies = [
 
 [[package]]
 name = "shaderc"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77a410ea26a220ceaef964dd71054ccd63cc97fd54393014c09046e795127824"
+checksum = "31cef52787a0db5108788ea20bed13d6bf4b96287c5c5201e55725f7070f3443"
 dependencies = [
  "libc",
  "shaderc-sys",
@@ -1313,9 +1313,9 @@ dependencies = [
 
 [[package]]
 name = "shaderc-sys"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a281c39df7d8a0a97e9430409abb466ff4bd046875c4d97591935042bbffc898"
+checksum = "1e8f8439fffcffd6efcd74197204addf935dbab5752696bd990a6cd36d54cf64"
 dependencies = [
  "cmake",
  "libc",

include/librashader.h

@@ -36,7 +36,9 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11)
 #include <d3d11.h>
 #else
-typedef void ID3D11Device;typedef void ID3D11RenderTargetView;typedef void ID3D1ShaderResourceView;
+typedef void ID3D11Device;
+typedef void ID3D11RenderTargetView;
+typedef void ID3D11ShaderResourceView;
 #endif
 #if defined(LIBRA_RUNTIME_VULKAN)
 #include <vulkan\vulkan.h>
@@ -73,10 +75,11 @@ typedef struct _filter_chain_vk _filter_chain_vk;
 /// The error type for librashader.
 typedef struct _libra_error _libra_error;
 
-/// A shader preset including all specified parameters, textures, and paths to specified shaders.
+/// A shader preset including all specified parameters, textures, and paths to
+/// specified shaders.
 ///
-/// A shader preset can be used to create a filter chain runtime instance, or reflected to get
+/// A shader preset can be used to create a filter chain runtime instance, or
-/// parameter metadata.
+/// reflected to get parameter metadata.
 typedef struct _shader_preset _shader_preset;
 
 /// A handle to a librashader error object.
@@ -102,28 +105,31 @@ typedef struct libra_preset_param_t {
 } libra_preset_param_t;
 
 /// A list of preset parameters.
-typedef struct libra_preset_parameter_list_t {
+typedef struct libra_preset_param_list_t {
     /// A pointer to the parameter
     const struct libra_preset_param_t *parameters;
-    /// The number of parameters in the list
+    /// The number of parameters in the list.
     uint64_t length;
     /// For internal use only.
-    /// Changing this causes immediate undefined behaviour on freeing this parameter list.
+    /// Changing this causes immediate undefined behaviour on freeing this
+    /// parameter list.
     uint64_t _internal_alloc;
-} libra_preset_parameter_list_t;
+} libra_preset_param_list_t;
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// A GL function loader that librashader needs to be initialized with.
-typedef const void *(*libra_gl_loader_t)(const char*);
+typedef const void *(*libra_gl_loader_t)(const char *);
 #endif
 
 /// Options for filter chain creation.
 typedef struct filter_chain_gl_opt_t {
     /// The GLSL version. Should be at least `330`.
     uint16_t gl_version;
-    /// Whether or not to use the Direct State Access APIs. Only available on OpenGL 4.5+.
+    /// Whether or not to use the Direct State Access APIs. Only available on
+    /// OpenGL 4.5+.
     bool use_dsa;
-    /// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
+    /// Whether or not to explicitly disable mipmap generation regardless of
+    /// shader preset settings.
     bool force_no_mipmaps;
 } filter_chain_gl_opt_t;
 
@@ -236,7 +242,8 @@ typedef struct libra_device_vk_t {
 typedef struct filter_chain_vk_opt_t {
     /// The number of frames in flight to keep. If zero, defaults to three.
     uint32_t frames_in_flight;
-    /// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
+    /// Whether or not to explicitly disable mipmap generation regardless of
+    /// shader preset settings.
     bool force_no_mipmaps;
 } filter_chain_vk_opt_t;
 
@@ -268,33 +275,37 @@ typedef struct FrameOptionsVulkan {
 } FrameOptionsVulkan;
 
 /// Function pointer definition for
-///libra_preset_create
+/// libra_preset_create
-typedef libra_error_t (*PFN_libra_preset_create)(const char *filename, libra_shader_preset_t *out);
+typedef libra_error_t (*PFN_libra_preset_create)(const char *filename,
+                                                 libra_shader_preset_t *out);
 
 /// Function pointer definition for
-///libra_preset_free
+/// libra_preset_free
 typedef libra_error_t (*PFN_libra_preset_free)(libra_shader_preset_t *preset);
 
 /// Function pointer definition for
-///libra_preset_set_param
+/// libra_preset_set_param
-typedef libra_error_t (*PFN_libra_preset_set_param)(libra_shader_preset_t *preset,
+typedef libra_error_t (*PFN_libra_preset_set_param)(
-                                                    const char *name,
+    libra_shader_preset_t *preset, const char *name, float value);
-                                                    float value);
 
 /// Function pointer definition for
-///libra_preset_get_param
+/// libra_preset_get_param
-typedef libra_error_t (*PFN_libra_preset_get_param)(libra_shader_preset_t *preset,
+typedef libra_error_t (*PFN_libra_preset_get_param)(
-                                                    const char *name,
+    libra_shader_preset_t *preset, const char *name, float *value);
-                                                    float *value);
 
 /// Function pointer definition for
-///libra_preset_print
+/// libra_preset_print
 typedef libra_error_t (*PFN_libra_preset_print)(libra_shader_preset_t *preset);
 
 /// Function pointer definition for
-///libra_preset_get_runtime_parameters
+/// libra_preset_get_runtime_params
-typedef libra_error_t (*PFN_libra_preset_get_runtime_parameters)(libra_shader_preset_t *preset,
+typedef libra_error_t (*PFN_libra_preset_get_runtime_params)(
-                                                                 struct libra_preset_parameter_list_t *out);
+    libra_shader_preset_t *preset, struct libra_preset_param_list_t *out);
+
+/// Function pointer definition for
+/// libra_preset_free_runtime_params
+typedef libra_error_t (*PFN_libra_preset_free_runtime_params)(
+    struct libra_preset_param_list_t preset);
 
 /// Function pointer definition for libra_error_errno
 typedef LIBRA_ERRNO (*PFN_libra_error_errno)(libra_error_t error);
@@ -313,179 +324,168 @@ typedef int32_t (*PFN_libra_error_free_string)(char **out);
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_init_context
+/// 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
+/// libra_gl_filter_chain_create
-typedef libra_error_t (*PFN_libra_gl_filter_chain_create)(libra_shader_preset_t *preset,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_create)(
-                                                          const struct filter_chain_gl_opt_t *options,
+    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
+/// libra_gl_filter_chain_frame
-typedef libra_error_t (*PFN_libra_gl_filter_chain_frame)(libra_gl_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_frame)(
-                                                         size_t frame_count,
+    libra_gl_filter_chain_t *chain, size_t frame_count,
-                                                         struct libra_source_image_gl_t image,
+    struct libra_source_image_gl_t image, struct libra_viewport_t viewport,
-                                                         struct libra_viewport_t viewport,
+    struct libra_draw_framebuffer_gl_t out, const float *mvp,
-                                                         struct libra_draw_framebuffer_gl_t out,
-                                                         const float *mvp,
     const struct frame_gl_opt_t *opt);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_filter_chain_set_param
+/// libra_gl_filter_chain_set_param
-typedef libra_error_t (*PFN_libra_gl_filter_chain_set_param)(libra_gl_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_set_param)(
-                                                             const char *param_name,
+    libra_gl_filter_chain_t *chain, const char *param_name, float value);
-                                                             float value);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_filter_chain_get_param
+/// libra_gl_filter_chain_get_param
-typedef libra_error_t (*PFN_libra_gl_filter_chain_get_param)(libra_gl_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_get_param)(
-                                                             const char *param_name,
+    libra_gl_filter_chain_t *chain, const char *param_name, float *out);
-                                                             float *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_filter_chain_set_active_pass_count
+/// libra_gl_filter_chain_set_active_pass_count
-typedef libra_error_t (*PFN_libra_gl_filter_chain_set_active_pass_count)(libra_gl_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_set_active_pass_count)(
-                                                                         uint32_t value);
+    libra_gl_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_filter_chain_get_active_pass_count
+/// libra_gl_filter_chain_get_active_pass_count
-typedef libra_error_t (*PFN_libra_gl_filter_chain_get_active_pass_count)(libra_gl_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_gl_filter_chain_get_active_pass_count)(
-                                                                         uint32_t *out);
+    libra_gl_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Function pointer definition for
-///libra_gl_filter_chain_free
+/// libra_gl_filter_chain_free
-typedef libra_error_t (*PFN_libra_gl_filter_chain_free)(libra_gl_filter_chain_t *chain);
+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
+/// libra_d3d11_filter_chain_create
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_create)(libra_shader_preset_t *preset,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_create)(
-                                                             const struct filter_chain_d3d11_opt_t *options,
+    libra_shader_preset_t *preset,
-                                                             const ID3D11Device *device,
+    const struct filter_chain_d3d11_opt_t *options, const ID3D11Device *device,
     libra_d3d11_filter_chain_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_frame
+/// libra_d3d11_filter_chain_frame
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_frame)(libra_d3d11_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_frame)(
-                                                            size_t frame_count,
+    libra_d3d11_filter_chain_t *chain, size_t frame_count,
-                                                            struct libra_source_image_d3d11_t image,
+    struct libra_source_image_d3d11_t image, struct libra_viewport_t viewport,
-                                                            struct libra_viewport_t viewport,
+    const ID3D11RenderTargetView *out, const float *mvp,
-                                                            const ID3D11RenderTargetView *out,
-                                                            const float *mvp,
     const struct frame_vk_opt_t *opt);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_set_param
+/// libra_d3d11_filter_chain_set_param
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_param)(libra_d3d11_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_param)(
-                                                                const char *param_name,
+    libra_d3d11_filter_chain_t *chain, const char *param_name, float value);
-                                                                float value);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_get_param
+/// libra_d3d11_filter_chain_get_param
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_param)(libra_d3d11_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_param)(
-                                                                const char *param_name,
+    libra_d3d11_filter_chain_t *chain, const char *param_name, float *out);
-                                                                float *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_set_active_pass_count
+/// libra_d3d11_filter_chain_set_active_pass_count
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_active_pass_count)(libra_d3d11_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_active_pass_count)(
-                                                                            uint32_t value);
+    libra_d3d11_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_get_active_pass_count
+/// libra_d3d11_filter_chain_get_active_pass_count
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_active_pass_count)(libra_d3d11_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_active_pass_count)(
-                                                                            uint32_t *out);
+    libra_d3d11_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Function pointer definition for
-///libra_d3d11_filter_chain_free
+/// libra_d3d11_filter_chain_free
-typedef libra_error_t (*PFN_libra_d3d11_filter_chain_free)(libra_d3d11_filter_chain_t *chain);
+typedef libra_error_t (*PFN_libra_d3d11_filter_chain_free)(
+    libra_d3d11_filter_chain_t *chain);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_create
+/// libra_vk_filter_chain_create
-typedef libra_error_t (*PFN_libra_vk_filter_chain_create)(struct libra_device_vk_t vulkan,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_create)(
-                                                          libra_shader_preset_t *preset,
+    struct libra_device_vk_t vulkan, libra_shader_preset_t *preset,
-                                                          const struct filter_chain_vk_opt_t *options,
+    const struct filter_chain_vk_opt_t *options, libra_vk_filter_chain_t *out);
-                                                          libra_vk_filter_chain_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_frame
+/// libra_vk_filter_chain_frame
-typedef libra_error_t (*PFN_libra_vk_filter_chain_frame)(libra_vk_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_frame)(
-                                                         VkCommandBuffer command_buffer,
+    libra_vk_filter_chain_t *chain, VkCommandBuffer command_buffer,
-                                                         size_t frame_count,
+    size_t frame_count, struct libra_image_vk_t image,
-                                                         struct libra_image_vk_t image,
+    struct libra_viewport_t viewport, struct libra_image_vk_t out,
-                                                         struct libra_viewport_t viewport,
+    const float *mvp, const struct FrameOptionsVulkan *opt);
-                                                         struct libra_image_vk_t out,
-                                                         const float *mvp,
-                                                         const struct FrameOptionsVulkan *opt);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_set_param
+/// libra_vk_filter_chain_set_param
-typedef libra_error_t (*PFN_libra_vk_filter_chain_set_param)(libra_vk_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_set_param)(
-                                                             const char *param_name,
+    libra_vk_filter_chain_t *chain, const char *param_name, float value);
-                                                             float value);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_get_param
+/// libra_vk_filter_chain_get_param
-typedef libra_error_t (*PFN_libra_vk_filter_chain_get_param)(libra_vk_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_get_param)(
-                                                             const char *param_name,
+    libra_vk_filter_chain_t *chain, const char *param_name, float *out);
-                                                             float *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_set_active_pass_count
+/// libra_vk_filter_chain_set_active_pass_count
-typedef libra_error_t (*PFN_libra_vk_filter_chain_set_active_pass_count)(libra_vk_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_set_active_pass_count)(
-                                                                         uint32_t value);
+    libra_vk_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_get_active_pass_count
+/// libra_vk_filter_chain_get_active_pass_count
-typedef libra_error_t (*PFN_libra_vk_filter_chain_get_active_pass_count)(libra_vk_filter_chain_t *chain,
+typedef libra_error_t (*PFN_libra_vk_filter_chain_get_active_pass_count)(
-                                                                         uint32_t *out);
+    libra_vk_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Function pointer definition for
-///libra_vk_filter_chain_free
+/// libra_vk_filter_chain_free
-typedef libra_error_t (*PFN_libra_vk_filter_chain_free)(libra_vk_filter_chain_t *chain);
+typedef libra_error_t (*PFN_libra_vk_filter_chain_free)(
+    libra_vk_filter_chain_t *chain);
 #endif
 
 #ifdef __cplusplus
@@ -500,51 +500,58 @@ LIBRA_ERRNO libra_error_errno(libra_error_t error);
 
 /// Print the error message.
 ///
-/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
+/// If `error` is null, this function does nothing and returns 1. Otherwise,
+/// this function returns 0.
 /// ## Safety
 ///   - `error` must be a valid and initialized instance of `libra_error_t`.
 int32_t libra_error_print(libra_error_t error);
 
 /// Frees any internal state kept by the error.
 ///
-/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
+/// If `error` is null, this function does nothing and returns 1. Otherwise,
-/// The resulting error object becomes null.
+/// this function returns 0. The resulting error object becomes null.
 /// ## Safety
-///   - `error` must be null or a pointer to a valid and initialized instance of `libra_error_t`.
+///   - `error` must be null or a pointer to a valid and initialized instance of
+///   `libra_error_t`.
 int32_t libra_error_free(libra_error_t *error);
 
 /// Writes the error message into `out`
 ///
-/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
+/// If `error` is null, this function does nothing and returns 1. Otherwise,
+/// this function returns 0.
 /// ## Safety
 ///   - `error` must be a valid and initialized instance of `libra_error_t`.
-///   - `out` must be a non-null pointer. The resulting string must not be modified.
+///   - `out` must be a non-null pointer. The resulting string must not be
-int32_t libra_error_write(libra_error_t error,
+///   modified.
-                          char **out);
+int32_t libra_error_write(libra_error_t error, char **out);
 
 /// Frees an error string previously allocated by `libra_error_write`.
 ///
 /// After freeing, the pointer will be set to null.
 /// ## Safety
-///   - If `libra_error_write` is not null, it must point to a string previously returned by `libra_error_write`.
+///   - If `libra_error_write` is not null, it must point to a string previously
-///     Attempting to free anything else, including strings or objects from other librashader functions, is immediate
+///   returned by `libra_error_write`.
-///     Undefined Behaviour.
+///     Attempting to free anything else, including strings or objects from
+///     other librashader functions, is immediate Undefined Behaviour.
 int32_t libra_error_free_string(char **out);
 
 /// Load a preset.
 ///
 /// ## Safety
-///  - `filename` must be either null or a valid, aligned pointer to a string path to the shader preset.
+///  - `filename` must be either null or a valid, aligned pointer to a string
-///  - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_shader_preset_t`.
+///  path to the shader preset.
+///  - `out` must be either null, or an aligned pointer to an uninitialized or
+///  invalid `libra_shader_preset_t`.
 /// ## Returns
-///  - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`.
+///  - If any parameters are null, `out` is unchanged, and this function returns
+///  `LIBRA_ERR_INVALID_PARAMETER`.
 libra_error_t libra_preset_create(const char *filename,
                                   libra_shader_preset_t *out);
 
 /// Free the preset.
 ///
-/// If `preset` is null, this function does nothing. The resulting value in `preset` then becomes
+/// If `preset` is null, this function does nothing. The resulting value in
-/// null.
+/// `preset` then becomes null.
 ///
 /// ## Safety
 /// - `preset` must be a valid and aligned pointer to a shader preset.
@@ -555,7 +562,8 @@ libra_error_t libra_preset_free(libra_shader_preset_t *preset);
 /// ## Safety
 /// - `preset` must be null or a valid and aligned pointer to a shader preset.
 /// - `name` must be null or a valid and aligned pointer to a string.
-libra_error_t libra_preset_set_param(libra_shader_preset_t *preset, const char *name, float value);
+libra_error_t libra_preset_set_param(libra_shader_preset_t *preset,
+                                     const char *name, float value);
 
 /// Get the value of the parameter as set in the preset.
 ///
@@ -563,7 +571,8 @@ libra_error_t libra_preset_set_param(libra_shader_preset_t *preset, const char *
 /// - `preset` must be null or a valid and aligned pointer to a shader preset.
 /// - `name` must be null or a valid and aligned pointer to a string.
 /// - `value` may be a pointer to a uninitialized `float`.
-libra_error_t libra_preset_get_param(libra_shader_preset_t *preset, const char *name, float *value);
+libra_error_t libra_preset_get_param(libra_shader_preset_t *preset,
+                                     const char *name, float *value);
 
 /// Pretty print the shader preset.
 ///
@@ -571,22 +580,60 @@ libra_error_t libra_preset_get_param(libra_shader_preset_t *preset, const char *
 /// - `preset` must be null or a valid and aligned pointer to a shader preset.
 libra_error_t libra_preset_print(libra_shader_preset_t *preset);
 
-/// Get a list of runtime parameter names.
+/// Get a list of runtime parameters.
 ///
 /// ## Safety
 /// - `preset` must be null or a valid and aligned pointer to a shader preset.
 /// - `out` must be an aligned pointer to a `libra_preset_parameter_list_t`.
-libra_error_t libra_preset_get_runtime_parameters(libra_shader_preset_t *preset,
+/// - The output struct should be treated as immutable. Mutating any struct
-                                                  struct libra_preset_parameter_list_t *out);
+/// fields
+///   in the returned struct may at best cause memory leaks, and at worse
+///   cause undefined behaviour when later freed.
+/// - It is safe to call `libra_preset_get_runtime_params` multiple times,
+/// however
+///   the output struct must only be freed once per call.
+libra_error_t libra_preset_get_runtime_params(
+    libra_shader_preset_t *preset, struct libra_preset_param_list_t *out);
+
+/// Free the runtime parameters.
+///
+/// Unlike the other `free` functions provided by librashader,
+/// `libra_preset_free_runtime_params` takes the struct directly.
+/// The caller must take care to maintain the lifetime of any pointers
+/// contained within the input `libra_preset_param_list_t`.
+///
+/// ## Safety
+/// - Any pointers rooted at `parameters` becomes invalid after this function
+/// returns,
+///   including any strings accessible via the input
+///   `libra_preset_param_list_t`. The caller must ensure that there are no live
+///   pointers, aliased or unaliased, to data accessible via the input
+///   `libra_preset_param_list_t`.
+///
+/// - Accessing any data pointed to via the input `libra_preset_param_list_t`
+/// after it
+///   has been freed is a use-after-free and is immediate undefined behaviour.
+///
+/// - If any struct fields of the input `libra_preset_param_list_t` was modified
+/// from
+///   their values given after `libra_preset_get_runtime_params`, this may
+///   result in undefined behaviour.
+libra_error_t libra_preset_free_runtime_params(
+    struct libra_preset_param_list_t preset);
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Initialize the OpenGL Context for librashader.
 ///
-/// ## Safety
+/// This only has to be done once throughout the lifetime of the application,
-/// Attempting to create a filter chain will fail.
+/// unless for whatever reason you switch OpenGL loaders mid-flight.
 ///
-/// Reinitializing the OpenGL context with a different loader immediately invalidates previous filter
+/// ## Safety
-/// chain objects, and drawing with them causes immediate undefined behaviour.
+/// Attempting to create a filter chain will fail if the GL context is not
+/// initialized.
+///
+/// Reinitializing the OpenGL context with a different loader immediately
+/// invalidates previous filter chain objects, and drawing with them causes
+/// immediate undefined behaviour.
 libra_error_t libra_gl_init_context(libra_gl_loader_t loader);
 #endif
 
@@ -600,8 +647,8 @@ libra_error_t libra_gl_init_context(libra_gl_loader_t loader);
 /// - `preset` must be either null, or valid and aligned.
 /// - `options` must be either null, or valid and aligned.
 /// - `out` must be aligned, but may be null, invalid, or uninitialized.
-libra_error_t libra_gl_filter_chain_create(libra_shader_preset_t *preset,
+libra_error_t libra_gl_filter_chain_create(
-                                           const struct filter_chain_gl_opt_t *options,
+    libra_shader_preset_t *preset, const struct filter_chain_gl_opt_t *options,
     libra_gl_filter_chain_t *out);
 #endif
 
@@ -609,18 +656,19 @@ libra_error_t libra_gl_filter_chain_create(libra_shader_preset_t *preset,
 /// Draw a frame with the given parameters for the given filter chain.
 ///
 /// ## Safety
-/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
+/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or
+/// invalid, this
 ///    function will return an error.
-/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
+/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16
+/// consecutive `float`
 ///    values for the model view projection matrix.
-/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
+/// - `opt` may be null, or if it is not null, must be an aligned pointer to a
+/// valid `frame_gl_opt_t`
 ///    struct.
-libra_error_t libra_gl_filter_chain_frame(libra_gl_filter_chain_t *chain,
+libra_error_t libra_gl_filter_chain_frame(
-                                          size_t frame_count,
+    libra_gl_filter_chain_t *chain, size_t frame_count,
-                                          struct libra_source_image_gl_t image,
+    struct libra_source_image_gl_t image, struct libra_viewport_t viewport,
-                                          struct libra_viewport_t viewport,
+    struct libra_draw_framebuffer_gl_t out, const float *mvp,
-                                          struct libra_draw_framebuffer_gl_t out,
-                                          const float *mvp,
     const struct frame_gl_opt_t *opt);
 #endif
 
@@ -629,7 +677,8 @@ libra_error_t libra_gl_filter_chain_frame(libra_gl_filter_chain_t *chain,
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_gl_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
 libra_error_t libra_gl_filter_chain_set_param(libra_gl_filter_chain_t *chain,
                                               const char *param_name,
@@ -641,7 +690,8 @@ libra_error_t libra_gl_filter_chain_set_param(libra_gl_filter_chain_t *chain,
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_gl_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
 libra_error_t libra_gl_filter_chain_get_param(libra_gl_filter_chain_t *chain,
                                               const char *param_name,
@@ -652,18 +702,20 @@ libra_error_t libra_gl_filter_chain_get_param(libra_gl_filter_chain_t *chain,
 /// Sets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_gl_filter_chain_set_active_pass_count(libra_gl_filter_chain_t *chain,
+/// initialized `libra_gl_filter_chain_t`.
-                                                          uint32_t value);
+libra_error_t libra_gl_filter_chain_set_active_pass_count(
+    libra_gl_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
 /// Gets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_gl_filter_chain_get_active_pass_count(libra_gl_filter_chain_t *chain,
+/// initialized `libra_gl_filter_chain_t`.
-                                                          uint32_t *out);
+libra_error_t libra_gl_filter_chain_get_active_pass_count(
+    libra_gl_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_OPENGL)
@@ -671,7 +723,8 @@ libra_error_t libra_gl_filter_chain_get_active_pass_count(libra_gl_filter_chain_
 ///
 /// The resulting value in `chain` then becomes null.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_gl_filter_chain_t`.
 libra_error_t libra_gl_filter_chain_free(libra_gl_filter_chain_t *chain);
 #endif
 
@@ -685,9 +738,9 @@ libra_error_t libra_gl_filter_chain_free(libra_gl_filter_chain_t *chain);
 /// - `preset` must be either null, or valid and aligned.
 /// - `options` must be either null, or valid and aligned.
 /// - `out` must be aligned, but may be null, invalid, or uninitialized.
-libra_error_t libra_d3d11_filter_chain_create(libra_shader_preset_t *preset,
+libra_error_t libra_d3d11_filter_chain_create(
-                                              const struct filter_chain_d3d11_opt_t *options,
+    libra_shader_preset_t *preset,
-                                              const ID3D11Device *device,
+    const struct filter_chain_d3d11_opt_t *options, const ID3D11Device *device,
     libra_d3d11_filter_chain_t *out);
 #endif
 
@@ -695,18 +748,19 @@ libra_error_t libra_d3d11_filter_chain_create(libra_shader_preset_t *preset,
 /// Draw a frame with the given parameters for the given filter chain.
 ///
 /// ## Safety
-/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
+/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or
+/// invalid, this
 ///    function will return an error.
-/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
+/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16
+/// consecutive `float`
 ///    values for the model view projection matrix.
-/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
+/// - `opt` may be null, or if it is not null, must be an aligned pointer to a
+/// valid `frame_gl_opt_t`
 ///    struct.
-libra_error_t libra_d3d11_filter_chain_frame(libra_d3d11_filter_chain_t *chain,
+libra_error_t libra_d3d11_filter_chain_frame(
-                                             size_t frame_count,
+    libra_d3d11_filter_chain_t *chain, size_t frame_count,
-                                             struct libra_source_image_d3d11_t image,
+    struct libra_source_image_d3d11_t image, struct libra_viewport_t viewport,
-                                             struct libra_viewport_t viewport,
+    const ID3D11RenderTargetView *out, const float *mvp,
-                                             const ID3D11RenderTargetView *out,
-                                             const float *mvp,
     const struct frame_vk_opt_t *opt);
 #endif
 
@@ -715,11 +769,11 @@ libra_error_t libra_d3d11_filter_chain_frame(libra_d3d11_filter_chain_t *chain,
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_d3d11_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
-libra_error_t libra_d3d11_filter_chain_set_param(libra_d3d11_filter_chain_t *chain,
+libra_error_t libra_d3d11_filter_chain_set_param(
-                                                 const char *param_name,
+    libra_d3d11_filter_chain_t *chain, const char *param_name, float value);
-                                                 float value);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
@@ -727,29 +781,31 @@ libra_error_t libra_d3d11_filter_chain_set_param(libra_d3d11_filter_chain_t *cha
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_d3d11_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
-libra_error_t libra_d3d11_filter_chain_get_param(libra_d3d11_filter_chain_t *chain,
+libra_error_t libra_d3d11_filter_chain_get_param(
-                                                 const char *param_name,
+    libra_d3d11_filter_chain_t *chain, const char *param_name, float *out);
-                                                 float *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Sets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_d3d11_filter_chain_set_active_pass_count(libra_d3d11_filter_chain_t *chain,
+/// initialized `libra_d3d11_filter_chain_t`.
-                                                             uint32_t value);
+libra_error_t libra_d3d11_filter_chain_set_active_pass_count(
+    libra_d3d11_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
 /// Gets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_d3d11_filter_chain_get_active_pass_count(libra_d3d11_filter_chain_t *chain,
+/// initialized `libra_d3d11_filter_chain_t`.
-                                                             uint32_t *out);
+libra_error_t libra_d3d11_filter_chain_get_active_pass_count(
+    libra_d3d11_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_D3D11)
@@ -757,7 +813,8 @@ libra_error_t libra_d3d11_filter_chain_get_active_pass_count(libra_d3d11_filter_
 ///
 /// The resulting value in `chain` then becomes null.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_d3d11_filter_chain_t`.
 libra_error_t libra_d3d11_filter_chain_free(libra_d3d11_filter_chain_t *chain);
 #endif
 
@@ -768,41 +825,43 @@ libra_error_t libra_d3d11_filter_chain_free(libra_d3d11_filter_chain_t *chain);
 /// the filter chain is created.
 ///
 /// ## Safety:
-/// - The handles provided in `vulkan` must be valid for the command buffers that
+/// - The handles provided in `vulkan` must be valid for the command buffers
-///   `libra_vk_filter_chain_frame` will write to. Namely, the VkDevice must have been
+/// that
+///   `libra_vk_filter_chain_frame` will write to. Namely, the VkDevice must
+///   have been
 ///    created with the `VK_KHR_dynamic_rendering` extension.
 /// - `preset` must be either null, or valid and aligned.
 /// - `options` must be either null, or valid and aligned.
 /// - `out` must be aligned, but may be null, invalid, or uninitialized.
-libra_error_t libra_vk_filter_chain_create(struct libra_device_vk_t vulkan,
+libra_error_t libra_vk_filter_chain_create(
-                                           libra_shader_preset_t *preset,
+    struct libra_device_vk_t vulkan, libra_shader_preset_t *preset,
-                                           const struct filter_chain_vk_opt_t *options,
+    const struct filter_chain_vk_opt_t *options, libra_vk_filter_chain_t *out);
-                                           libra_vk_filter_chain_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
-/// Records rendering commands for a frame with the given parameters for the given filter chain
+/// Records rendering commands for a frame with the given parameters for the
-/// to the input command buffer.
+/// given filter chain to the input command buffer.
 ///
 /// librashader will not do any queue submissions.
 ///
 /// ## Safety
 /// - `libra_vk_filter_chain_frame` **must not be called within a RenderPass**.
-/// - `command_buffer` must be a valid handle to a `VkCommandBuffer` that is ready for recording.
+/// - `command_buffer` must be a valid handle to a `VkCommandBuffer` that is
-/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
+/// ready for recording.
+/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or
+/// invalid, this
 ///    function will return an error.
-/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
+/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16
+/// consecutive `float`
 ///    values for the model view projection matrix.
-/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_vk_opt_t`
+/// - `opt` may be null, or if it is not null, must be an aligned pointer to a
+/// valid `frame_vk_opt_t`
 ///    struct.
-libra_error_t libra_vk_filter_chain_frame(libra_vk_filter_chain_t *chain,
+libra_error_t libra_vk_filter_chain_frame(
-                                          VkCommandBuffer command_buffer,
+    libra_vk_filter_chain_t *chain, VkCommandBuffer command_buffer,
-                                          size_t frame_count,
+    size_t frame_count, struct libra_image_vk_t image,
-                                          struct libra_image_vk_t image,
+    struct libra_viewport_t viewport, struct libra_image_vk_t out,
-                                          struct libra_viewport_t viewport,
+    const float *mvp, const struct FrameOptionsVulkan *opt);
-                                          struct libra_image_vk_t out,
-                                          const float *mvp,
-                                          const struct FrameOptionsVulkan *opt);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
@@ -810,7 +869,8 @@ libra_error_t libra_vk_filter_chain_frame(libra_vk_filter_chain_t *chain,
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_vk_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
 libra_error_t libra_vk_filter_chain_set_param(libra_vk_filter_chain_t *chain,
                                               const char *param_name,
@@ -822,7 +882,8 @@ libra_error_t libra_vk_filter_chain_set_param(libra_vk_filter_chain_t *chain,
 ///
 /// If the parameter does not exist, returns an error.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_vk_filter_chain_t`.
 /// - `param_name` must be either null or a null terminated string.
 libra_error_t libra_vk_filter_chain_get_param(libra_vk_filter_chain_t *chain,
                                               const char *param_name,
@@ -833,18 +894,20 @@ libra_error_t libra_vk_filter_chain_get_param(libra_vk_filter_chain_t *chain,
 /// Sets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_vk_filter_chain_set_active_pass_count(libra_vk_filter_chain_t *chain,
+/// initialized `libra_vk_filter_chain_t`.
-                                                          uint32_t value);
+libra_error_t libra_vk_filter_chain_set_active_pass_count(
+    libra_vk_filter_chain_t *chain, uint32_t value);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
 /// Gets the number of active passes for this chain.
 ///
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
-libra_error_t libra_vk_filter_chain_get_active_pass_count(libra_vk_filter_chain_t *chain,
+/// initialized `libra_vk_filter_chain_t`.
-                                                          uint32_t *out);
+libra_error_t libra_vk_filter_chain_get_active_pass_count(
+    libra_vk_filter_chain_t *chain, uint32_t *out);
 #endif
 
 #if defined(LIBRA_RUNTIME_VULKAN)
@@ -852,7 +915,8 @@ libra_error_t libra_vk_filter_chain_get_active_pass_count(libra_vk_filter_chain_
 ///
 /// The resulting value in `chain` then becomes null.
 /// ## Safety
-/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
+/// - `chain` must be either null or a valid and aligned pointer to an
+/// initialized `libra_vk_filter_chain_t`.
 libra_error_t libra_vk_filter_chain_free(libra_vk_filter_chain_t *chain);
 #endif
 

librashader-reflect/Cargo.toml

@@ -12,7 +12,7 @@ keywords = ["shader", "retroarch", "SPIR-V"]
 description = "RetroArch shaders for all."
 
 [dependencies]
-shaderc = { version = "0.8.1", features = [] }
+shaderc = { version = "0.8.2", features = [] }
 spirv_cross = { version = "0.23.1", features = [ "glsl", "hlsl" ] }
 
 thiserror = "1.0.37"