From 828e8160e92174d7f92b1e181b77831dc90f6f27 Mon Sep 17 00:00:00 2001 From: chyyran Date: Sat, 14 Jan 2023 17:21:01 -0500 Subject: [PATCH] doc: copy docs to ld --- include/librashader_ld.h | 311 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) diff --git a/include/librashader_ld.h b/include/librashader_ld.h index b1d8255..a4e6b37 100644 --- a/include/librashader_ld.h +++ b/include/librashader_ld.h @@ -231,54 +231,364 @@ libra_error_t __librashader__noop_vk_filter_chain_get_active_pass_count( #endif typedef struct libra_instance_t { + /// Load a preset. + /// + /// ## Safety + /// - `filename` must be either null or a valid, aligned pointer to a + /// string 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`. PFN_libra_preset_create preset_create; + + /// Free the preset. + /// + /// If `preset` is null, this function does nothing. The resulting value in + /// `preset` then becomes null. + /// + /// ## Safety + /// - `preset` must be a valid and aligned pointer to a shader preset. PFN_libra_preset_free preset_free; + + /// Set the value of the parameter in the 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. PFN_libra_preset_set_param preset_set_param; + + /// Get the value of the parameter as set in the 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. + /// - `value` may be a pointer to a uninitialized `float`. PFN_libra_preset_get_param preset_get_param; + + /// Pretty print the shader preset. + /// + /// ## Safety + /// - `preset` must be null or a valid and aligned pointer to a shader + /// preset. PFN_libra_preset_print preset_print; + + /// Get a list of runtime parameter names. + /// + /// ## 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`. + /// - The output struct should be treated as immutable. Mutating any struct + /// 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. PFN_libra_preset_get_runtime_params preset_get_runtime_params; + + /// 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. PFN_libra_preset_free_runtime_params preset_free_runtime_params; + + /// Get the error code corresponding to this error object. + /// + /// ## Safety + /// - `error` must be valid and initialized. PFN_libra_error_errno error_errno; + + /// Print the error message. + /// + /// 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`. PFN_libra_error_print error_print; + + /// Frees any internal state kept by the error. + /// + /// If `error` is null, this function does nothing and returns 1. Otherwise, + /// 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`. PFN_libra_error_free error_free; + + /// Writes the error message into `out` + /// + /// 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. PFN_libra_error_write error_write; + + /// 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`. + /// Attempting to free anything else, including strings or objects from + /// other librashader functions, is immediate Undefined Behaviour. PFN_libra_error_free_string error_free_string; #if defined(LIBRA_RUNTIME_OPENGL) + /// Initialize the OpenGL Context for librashader. + /// + /// ## Safety + /// Attempting to create a filter chain will fail. + /// + /// Reinitializing the OpenGL context with a different loader immediately + /// invalidates previous filter chain objects, and drawing with them causes + /// immediate undefined behaviour. PFN_libra_gl_init_context gl_init_context; + + /// Create the filter chain given the shader preset. + /// + /// The shader preset is immediately invalidated and must be recreated after + /// the filter chain is created. + /// + /// ## Safety: + /// - `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. PFN_libra_gl_filter_chain_create gl_filter_chain_create; + + /// 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 + /// function will return an error. + /// - `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` + /// struct. PFN_libra_gl_filter_chain_frame gl_filter_chain_frame; + + /// Free a 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`. PFN_libra_gl_filter_chain_free gl_filter_chain_free; + + /// 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`. PFN_libra_gl_filter_chain_get_active_pass_count gl_filter_chain_get_active_pass_count; + + /// 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`. PFN_libra_gl_filter_chain_set_active_pass_count gl_filter_chain_set_active_pass_count; + + /// Gets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_gl_filter_chain_get_param gl_filter_chain_get_param; + + /// Sets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_gl_filter_chain_set_param gl_filter_chain_set_param; #endif #if defined(LIBRA_RUNTIME_VULKAN) + /// Create the filter chain given the shader preset. + /// + /// The shader preset is immediately invalidated and must be recreated after + /// the filter chain is created. + /// + /// ## Safety: + /// - `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. PFN_libra_d3d11_filter_chain_create d3d11_filter_chain_create; + + /// 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 + /// function will return an error. + /// - `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` + /// struct. PFN_libra_d3d11_filter_chain_frame d3d11_filter_chain_frame; + + + /// Free a D3D11 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_d3d11_filter_chain_t`. PFN_libra_d3d11_filter_chain_free d3d11_filter_chain_free; + + /// 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`. PFN_libra_d3d11_filter_chain_get_active_pass_count d3d11_filter_chain_get_active_pass_count; + + /// 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`. PFN_libra_d3d11_filter_chain_set_active_pass_count d3d11_filter_chain_set_active_pass_count; + + /// Gets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_d3d11_filter_chain_get_param d3d11_filter_chain_get_param; + + /// Sets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_d3d11_filter_chain_set_param d3d11_filter_chain_set_param; #endif #if defined(LIBRA_RUNTIME_VULKAN) + /// Create the filter chain given the shader preset. + /// + /// The shader preset is immediately invalidated and must be recreated after + /// the filter chain is created. + /// + /// ## Safety: + /// - The handles provided in `vulkan` must be valid for the command buffers + /// 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. PFN_libra_vk_filter_chain_create vk_filter_chain_create; + + /// Records rendering commands for a frame with the given parameters for the + /// 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. + /// - `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` + /// 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` + /// struct. PFN_libra_vk_filter_chain_frame vk_filter_chain_frame; + + /// Free a Vulkan 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`. PFN_libra_vk_filter_chain_free vk_filter_chain_free; + + /// 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`. PFN_libra_vk_filter_chain_get_active_pass_count vk_filter_chain_get_active_pass_count; + + /// 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`. PFN_libra_vk_filter_chain_set_active_pass_count vk_filter_chain_set_active_pass_count; + + /// Gets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_vk_filter_chain_get_param vk_filter_chain_get_param; + + /// Sets a parameter for the filter 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`. + /// - `param_name` must be either null or a null terminated string. PFN_libra_vk_filter_chain_set_param vk_filter_chain_set_param; #endif } libra_instance_t; @@ -294,6 +604,7 @@ libra_instance_t __librashader_make_null_instance() { __librashader__noop_preset_get_runtime_params, .preset_free_runtime_params = __librashader__noop_preset_free_runtime_params, + .error_errno = __librashader__noop_error_errno, .error_print = __librashader__noop_error_print, .error_free = __librashader__noop_error_free,