diff --git a/Cargo.lock b/Cargo.lock index 20d255e..79a5644 100644 --- a/Cargo.lock +++ b/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", diff --git a/include/librashader.h b/include/librashader.h index bcffc66..59bb7b6 100644 --- a/include/librashader.h +++ b/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 #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 @@ -46,7 +48,7 @@ typedef void ID3D11Device;typedef void ID3D11RenderTargetView;typedef void ID3D1 enum LIBRA_ERRNO #ifdef __cplusplus : int32_t -#endif // __cplusplus +#endif // __cplusplus { LIBRA_ERRNO_UNKNOWN_ERROR = 0, LIBRA_ERRNO_INVALID_PARAMETER = 1, @@ -59,7 +61,7 @@ enum LIBRA_ERRNO }; #ifndef __cplusplus typedef int32_t LIBRA_ERRNO; -#endif // __cplusplus +#endif // __cplusplus /// A Direct3D 11 filter chain. typedef struct _filter_chain_d3d11 _filter_chain_d3d11; @@ -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 -/// parameter metadata. +/// A shader preset can be used to create a filter chain runtime instance, or +/// 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; @@ -135,14 +141,14 @@ typedef struct _filter_chain_gl *libra_gl_filter_chain_t; #if defined(LIBRA_RUNTIME_OPENGL) /// OpenGL parameters for the source image. typedef struct libra_source_image_gl_t { - /// A texture GLuint to the source image. - uint32_t handle; - /// The format of the source image. - uint32_t format; - /// The width of the source image. - uint32_t width; - /// The height of the source image. - uint32_t height; + /// A texture GLuint to the source image. + uint32_t handle; + /// The format of the source image. + uint32_t format; + /// The width of the source image. + uint32_t width; + /// The height of the source image. + uint32_t height; } libra_source_image_gl_t; #endif @@ -161,12 +167,12 @@ typedef struct libra_viewport_t { #if defined(LIBRA_RUNTIME_OPENGL) /// OpenGL parameters for the output framebuffer. typedef struct libra_draw_framebuffer_gl_t { - /// A framebuffer GLuint to the output framebuffer. - uint32_t handle; - /// A texture GLuint to the logical buffer of the output framebuffer. - uint32_t texture; - /// The format of the output framebuffer. - uint32_t format; + /// A framebuffer GLuint to the output framebuffer. + uint32_t handle; + /// A texture GLuint to the logical buffer of the output framebuffer. + uint32_t texture; + /// The format of the output framebuffer. + uint32_t format; } libra_draw_framebuffer_gl_t; #endif @@ -198,12 +204,12 @@ typedef struct _filter_chain_d3d11 *libra_d3d11_filter_chain_t; #if defined(LIBRA_RUNTIME_D3D11) /// OpenGL parameters for the source image. typedef struct libra_source_image_d3d11_t { - /// A shader resource view into the source image - const ID3D11ShaderResourceView *handle; - /// The width of the source image. - uint32_t width; - /// The height of the source image. - uint32_t height; + /// A shader resource view into the source image + const ID3D11ShaderResourceView *handle; + /// The width of the source image. + uint32_t width; + /// The height of the source image. + uint32_t height; } libra_source_image_d3d11_t; #endif @@ -218,17 +224,17 @@ typedef struct frame_vk_opt_t { #if defined(LIBRA_RUNTIME_VULKAN) /// Handles required to instantiate vulkan typedef struct libra_device_vk_t { - /// A raw `VkPhysicalDevice` handle - /// for the physical device that will perform rendering. - VkPhysicalDevice physical_device; - /// A raw `VkInstance` handle - /// for the Vulkan instance that will perform rendering. - VkInstance instance; - /// A raw `VkDevice` handle - /// for the device attached to the instance that will perform rendering. - VkDevice device; - /// The entry loader for the Vulkan library. - PFN_vkGetInstanceProcAddr entry; + /// A raw `VkPhysicalDevice` handle + /// for the physical device that will perform rendering. + VkPhysicalDevice physical_device; + /// A raw `VkInstance` handle + /// for the Vulkan instance that will perform rendering. + VkInstance instance; + /// A raw `VkDevice` handle + /// for the device attached to the instance that will perform rendering. + VkDevice device; + /// The entry loader for the Vulkan library. + PFN_vkGetInstanceProcAddr entry; } libra_device_vk_t; #endif @@ -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; @@ -248,14 +255,14 @@ typedef struct _filter_chain_vk *libra_vk_filter_chain_t; #if defined(LIBRA_RUNTIME_VULKAN) /// Vulkan parameters for the source image. typedef struct libra_image_vk_t { - /// A raw `VkImage` handle to the source image. - VkImage handle; - /// The `VkFormat` of the source image. - VkFormat format; - /// The width of the source image. - uint32_t width; - /// The height of the source image. - uint32_t height; + /// A raw `VkImage` handle to the source image. + VkImage handle; + /// The `VkFormat` of the source image. + VkFormat format; + /// The width of the source image. + uint32_t width; + /// The height of the source image. + uint32_t height; } libra_image_vk_t; #endif @@ -268,33 +275,37 @@ typedef struct FrameOptionsVulkan { } FrameOptionsVulkan; /// Function pointer definition for -///libra_preset_create -typedef libra_error_t (*PFN_libra_preset_create)(const char *filename, libra_shader_preset_t *out); +/// libra_preset_create +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 -typedef libra_error_t (*PFN_libra_preset_set_param)(libra_shader_preset_t *preset, - const char *name, - float value); +/// 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); +/// 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 +/// 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 -typedef libra_error_t (*PFN_libra_preset_get_runtime_parameters)(libra_shader_preset_t *preset, - struct libra_preset_parameter_list_t *out); +/// libra_preset_get_runtime_params +typedef libra_error_t (*PFN_libra_preset_get_runtime_params)( + 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,184 +324,173 @@ 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 -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); +/// 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, - struct libra_viewport_t viewport, - struct libra_draw_framebuffer_gl_t out, - const float *mvp, - const struct frame_gl_opt_t *opt); +/// 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, struct libra_viewport_t viewport, + 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 -typedef libra_error_t (*PFN_libra_gl_filter_chain_set_param)(libra_gl_filter_chain_t *chain, - const char *param_name, - float value); +/// libra_gl_filter_chain_set_param +typedef libra_error_t (*PFN_libra_gl_filter_chain_set_param)( + libra_gl_filter_chain_t *chain, const char *param_name, float value); #endif #if defined(LIBRA_RUNTIME_OPENGL) /// Function pointer definition for -///libra_gl_filter_chain_get_param -typedef libra_error_t (*PFN_libra_gl_filter_chain_get_param)(libra_gl_filter_chain_t *chain, - const char *param_name, - float *out); +/// libra_gl_filter_chain_get_param +typedef libra_error_t (*PFN_libra_gl_filter_chain_get_param)( + libra_gl_filter_chain_t *chain, const char *param_name, float *out); #endif #if defined(LIBRA_RUNTIME_OPENGL) /// Function pointer definition for -///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, - uint32_t value); +/// 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, uint32_t value); #endif #if defined(LIBRA_RUNTIME_OPENGL) /// Function pointer definition for -///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, - uint32_t *out); +/// 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, uint32_t *out); #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); +/// 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, - libra_d3d11_filter_chain_t *out); +/// 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, + libra_d3d11_filter_chain_t *out); #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, - struct libra_viewport_t viewport, - const ID3D11RenderTargetView *out, - const float *mvp, - const struct frame_vk_opt_t *opt); +/// 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, struct libra_viewport_t viewport, + 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 -typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_param)(libra_d3d11_filter_chain_t *chain, - const char *param_name, - float value); +/// libra_d3d11_filter_chain_set_param +typedef libra_error_t (*PFN_libra_d3d11_filter_chain_set_param)( + libra_d3d11_filter_chain_t *chain, const char *param_name, float value); #endif #if defined(LIBRA_RUNTIME_D3D11) /// Function pointer definition for -///libra_d3d11_filter_chain_get_param -typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_param)(libra_d3d11_filter_chain_t *chain, - const char *param_name, - float *out); +/// libra_d3d11_filter_chain_get_param +typedef libra_error_t (*PFN_libra_d3d11_filter_chain_get_param)( + libra_d3d11_filter_chain_t *chain, const char *param_name, float *out); #endif #if defined(LIBRA_RUNTIME_D3D11) /// Function pointer definition for -///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, - uint32_t value); +/// 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, uint32_t value); #endif #if defined(LIBRA_RUNTIME_D3D11) /// Function pointer definition for -///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, - uint32_t *out); +/// 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, uint32_t *out); #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); +/// libra_d3d11_filter_chain_free +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 -typedef libra_error_t (*PFN_libra_vk_filter_chain_create)(struct libra_device_vk_t vulkan, - libra_shader_preset_t *preset, - const struct filter_chain_vk_opt_t *options, - libra_vk_filter_chain_t *out); +/// libra_vk_filter_chain_create +typedef libra_error_t (*PFN_libra_vk_filter_chain_create)( + struct libra_device_vk_t vulkan, libra_shader_preset_t *preset, + const struct filter_chain_vk_opt_t *options, libra_vk_filter_chain_t *out); #endif #if defined(LIBRA_RUNTIME_VULKAN) /// Function pointer definition for -///libra_vk_filter_chain_frame -typedef libra_error_t (*PFN_libra_vk_filter_chain_frame)(libra_vk_filter_chain_t *chain, - VkCommandBuffer command_buffer, - size_t frame_count, - struct libra_image_vk_t image, - struct libra_viewport_t viewport, - struct libra_image_vk_t out, - const float *mvp, - const struct FrameOptionsVulkan *opt); +/// libra_vk_filter_chain_frame +typedef libra_error_t (*PFN_libra_vk_filter_chain_frame)( + libra_vk_filter_chain_t *chain, VkCommandBuffer command_buffer, + size_t frame_count, struct libra_image_vk_t image, + struct libra_viewport_t viewport, 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 -typedef libra_error_t (*PFN_libra_vk_filter_chain_set_param)(libra_vk_filter_chain_t *chain, - const char *param_name, - float value); +/// libra_vk_filter_chain_set_param +typedef libra_error_t (*PFN_libra_vk_filter_chain_set_param)( + libra_vk_filter_chain_t *chain, const char *param_name, float value); #endif #if defined(LIBRA_RUNTIME_VULKAN) /// Function pointer definition for -///libra_vk_filter_chain_get_param -typedef libra_error_t (*PFN_libra_vk_filter_chain_get_param)(libra_vk_filter_chain_t *chain, - const char *param_name, - float *out); +/// libra_vk_filter_chain_get_param +typedef libra_error_t (*PFN_libra_vk_filter_chain_get_param)( + libra_vk_filter_chain_t *chain, const char *param_name, float *out); #endif #if defined(LIBRA_RUNTIME_VULKAN) /// Function pointer definition for -///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, - uint32_t value); +/// 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, uint32_t value); #endif #if defined(LIBRA_RUNTIME_VULKAN) /// Function pointer definition for -///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, - uint32_t *out); +/// 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, uint32_t *out); #endif #if defined(LIBRA_RUNTIME_VULKAN) /// Function pointer definition for -///libra_vk_filter_chain_free -typedef libra_error_t (*PFN_libra_vk_filter_chain_free)(libra_vk_filter_chain_t *chain); +/// libra_vk_filter_chain_free +typedef libra_error_t (*PFN_libra_vk_filter_chain_free)( + libra_vk_filter_chain_t *chain); #endif #ifdef __cplusplus extern "C" { -#endif // __cplusplus +#endif // __cplusplus /// Get the error code corresponding to this error object. /// @@ -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. -/// The resulting error object becomes null. +/// 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`. +/// - `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. -int32_t libra_error_write(libra_error_t error, - char **out); +/// - `out` must be a non-null pointer. The resulting string must not be +/// modified. +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`. -/// Attempting to free anything else, including strings or objects from other librashader functions, is immediate -/// Undefined Behaviour. +/// - 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. 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. -/// - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_shader_preset_t`. +/// - `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`. +/// - 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 -/// null. +/// 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. @@ -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, - struct libra_preset_parameter_list_t *out); +/// - 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. +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 -/// Attempting to create a filter chain will fail. +/// This only has to be done once throughout the lifetime of the application, +/// unless for whatever reason you switch OpenGL loaders mid-flight. /// -/// Reinitializing the OpenGL context with a different loader immediately invalidates previous filter -/// chain objects, and drawing with them causes immediate undefined behaviour. +/// ## Safety +/// 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,28 +647,29 @@ 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, - const struct filter_chain_gl_opt_t *options, - libra_gl_filter_chain_t *out); +libra_error_t 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) /// 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, - size_t frame_count, - struct libra_source_image_gl_t image, - struct libra_viewport_t viewport, - struct libra_draw_framebuffer_gl_t out, - const float *mvp, - const struct frame_gl_opt_t *opt); +libra_error_t libra_gl_filter_chain_frame( + libra_gl_filter_chain_t *chain, size_t frame_count, + struct libra_source_image_gl_t image, struct libra_viewport_t viewport, + struct libra_draw_framebuffer_gl_t out, const float *mvp, + const struct frame_gl_opt_t *opt); #endif #if defined(LIBRA_RUNTIME_OPENGL) @@ -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`. -libra_error_t libra_gl_filter_chain_set_active_pass_count(libra_gl_filter_chain_t *chain, - uint32_t value); +/// - `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_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`. -libra_error_t libra_gl_filter_chain_get_active_pass_count(libra_gl_filter_chain_t *chain, - uint32_t *out); +/// - `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_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,29 +738,30 @@ 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, - const struct filter_chain_d3d11_opt_t *options, - const ID3D11Device *device, - libra_d3d11_filter_chain_t *out); +libra_error_t libra_d3d11_filter_chain_create( + libra_shader_preset_t *preset, + const struct filter_chain_d3d11_opt_t *options, const ID3D11Device *device, + libra_d3d11_filter_chain_t *out); #endif #if defined(LIBRA_RUNTIME_D3D11) /// 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, - size_t frame_count, - struct libra_source_image_d3d11_t image, - struct libra_viewport_t viewport, - const ID3D11RenderTargetView *out, - const float *mvp, - const struct frame_vk_opt_t *opt); +libra_error_t libra_d3d11_filter_chain_frame( + libra_d3d11_filter_chain_t *chain, size_t frame_count, + struct libra_source_image_d3d11_t image, struct libra_viewport_t viewport, + const ID3D11RenderTargetView *out, const float *mvp, + const struct frame_vk_opt_t *opt); #endif #if defined(LIBRA_RUNTIME_D3D11) @@ -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, - const char *param_name, - float value); +libra_error_t libra_d3d11_filter_chain_set_param( + libra_d3d11_filter_chain_t *chain, const char *param_name, 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, - const char *param_name, - float *out); +libra_error_t libra_d3d11_filter_chain_get_param( + libra_d3d11_filter_chain_t *chain, const char *param_name, 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`. -libra_error_t libra_d3d11_filter_chain_set_active_pass_count(libra_d3d11_filter_chain_t *chain, - uint32_t value); +/// - `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_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`. -libra_error_t libra_d3d11_filter_chain_get_active_pass_count(libra_d3d11_filter_chain_t *chain, - uint32_t *out); +/// - `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_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 -/// `libra_vk_filter_chain_frame` will write to. Namely, the VkDevice must have been +/// - 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. -libra_error_t libra_vk_filter_chain_create(struct libra_device_vk_t vulkan, - libra_shader_preset_t *preset, - const struct filter_chain_vk_opt_t *options, - libra_vk_filter_chain_t *out); +libra_error_t libra_vk_filter_chain_create( + struct libra_device_vk_t vulkan, libra_shader_preset_t *preset, + const struct filter_chain_vk_opt_t *options, 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 -/// to the input command buffer. +/// 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 +/// - `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` +/// - `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, - VkCommandBuffer command_buffer, - size_t frame_count, - struct libra_image_vk_t image, - struct libra_viewport_t viewport, - struct libra_image_vk_t out, - const float *mvp, - const struct FrameOptionsVulkan *opt); +libra_error_t libra_vk_filter_chain_frame( + libra_vk_filter_chain_t *chain, VkCommandBuffer command_buffer, + size_t frame_count, struct libra_image_vk_t image, + struct libra_viewport_t viewport, 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`. -libra_error_t libra_vk_filter_chain_set_active_pass_count(libra_vk_filter_chain_t *chain, - uint32_t value); +/// - `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_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`. -libra_error_t libra_vk_filter_chain_get_active_pass_count(libra_vk_filter_chain_t *chain, - uint32_t *out); +/// - `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_get_active_pass_count( + libra_vk_filter_chain_t *chain, uint32_t *out); #endif #if defined(LIBRA_RUNTIME_VULKAN) @@ -852,12 +915,13 @@ 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 #ifdef __cplusplus -} // extern "C" -#endif // __cplusplus +} // extern "C" +#endif // __cplusplus #endif /* __LIBRASHADER_H__ */ diff --git a/librashader-reflect/Cargo.toml b/librashader-reflect/Cargo.toml index 8a22701..2d765f3 100644 --- a/librashader-reflect/Cargo.toml +++ b/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"