2023-01-14 17:38:59 +11:00
/*
librashader . h
SPDX - License - Identifier : MIT
This file is part of the librashader C headers .
Copyright 2022 chyyran
Permission is hereby granted , free of charge , to any person obtaining a copy of
this software and associated documentation files ( the " Software " ) , to deal in
the Software without restriction , including without limitation the rights to
use , copy , modify , merge , publish , distribute , sublicense , and / or sell copies of
the Software , and to permit persons to whom the Software is furnished to do so ,
subject to the following conditions :
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software .
THE SOFTWARE IS PROVIDED " AS IS " , WITHOUT WARRANTY OF ANY KIND , EXPRESS OR
IMPLIED , INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY , FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT . IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM , DAMAGES OR OTHER LIABILITY , WHETHER
IN AN ACTION OF CONTRACT , TORT OR OTHERWISE , ARISING FROM , OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE .
*/
2024-03-08 11:37:39 +11:00
2022-12-04 10:32:10 +11:00
# ifndef __LIBRASHADER_H__
# define __LIBRASHADER_H__
# pragma once
# include <stdarg.h>
# include <stdbool.h>
# include <stddef.h>
# include <stdint.h>
# include <stdlib.h>
2023-01-14 09:59:22 +11:00
# if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11)
2022-12-05 16:06:37 +11:00
# include <d3d11.h>
2023-01-14 09:59:22 +11:00
# endif
2023-02-06 18:17:30 +11:00
# if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12)
# include <d3d12.h>
2024-02-13 19:03:45 +11:00
# endif
2024-03-08 11:37:39 +11:00
# if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9)
# include <D3D9.h>
# endif
2024-02-13 19:03:45 +11:00
# if defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__)
# import <Metal / Metal.h>
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
2024-07-27 19:00:00 +10:00
# include <vulkan/vulkan.h>
2023-02-06 18:17:30 +11:00
# endif
2022-12-04 10:32:10 +11:00
2024-03-08 11:37:39 +11:00
2024-09-30 16:27:16 +10:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// The type of image passed to the image.
typedef enum LIBRA_D3D12_IMAGE_TYPE {
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// The image handle is a pointer to a `ID3D12Resource`.
LIBRA_D3D12_IMAGE_TYPE_IMAGE_TYPE_RESOURCE = 0 ,
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// The image handle is a `libra_source_image_d3d12_t`
LIBRA_D3D12_IMAGE_TYPE_IMAGE_TYPE_SOURCE_IMAGE = 1 ,
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// The image handle is a `libra_output_image_d3d12_t`
LIBRA_D3D12_IMAGE_TYPE_IMAGE_TYPE_OUTPUT_IMAGE = 2 ,
# endif
} LIBRA_D3D12_IMAGE_TYPE ;
# endif
2022-12-05 14:37:03 +11:00
/// Error codes for librashader error types.
enum LIBRA_ERRNO
# ifdef __cplusplus
2024-03-08 11:37:39 +11:00
: int32_t
# endif // __cplusplus
{
2024-09-30 16:27:16 +10:00
/// Error code for an unknown error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_UNKNOWN_ERROR = 0 ,
2024-09-30 16:27:16 +10:00
/// Error code for an invalid parameter.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_INVALID_PARAMETER = 1 ,
2024-09-30 16:27:16 +10:00
/// Error code for an invalid (non-UTF8) string.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_INVALID_STRING = 2 ,
2024-09-30 16:27:16 +10:00
/// Error code for a preset parser error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_PRESET_ERROR = 3 ,
2024-09-30 16:27:16 +10:00
/// Error code for a preprocessor error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_PREPROCESS_ERROR = 4 ,
2024-09-30 16:27:16 +10:00
/// Error code for a shader parameter error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_SHADER_PARAMETER_ERROR = 5 ,
2024-09-30 16:27:16 +10:00
/// Error code for a reflection error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_REFLECT_ERROR = 6 ,
2024-09-30 16:27:16 +10:00
/// Error code for a runtime error.
2024-03-08 11:37:39 +11:00
LIBRA_ERRNO_RUNTIME_ERROR = 7 ,
2022-12-05 14:37:03 +11:00
} ;
# ifndef __cplusplus
typedef int32_t LIBRA_ERRNO ;
2024-03-08 11:37:39 +11:00
# endif // __cplusplus
2024-02-09 18:07:02 +11:00
/// An enum representing orientation for use in preset contexts.
enum LIBRA_PRESET_CTX_ORIENTATION
# ifdef __cplusplus
2024-03-08 11:37:39 +11:00
: uint32_t
# endif // __cplusplus
{
2024-09-30 16:27:16 +10:00
/// Context parameter for vertical orientation.
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_ORIENTATION_VERTICAL = 0 ,
2024-09-30 16:27:16 +10:00
/// Context parameter for horizontal orientation.
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_ORIENTATION_HORIZONTAL ,
2024-02-09 18:07:02 +11:00
} ;
# ifndef __cplusplus
typedef uint32_t LIBRA_PRESET_CTX_ORIENTATION ;
2024-03-08 11:37:39 +11:00
# endif // __cplusplus
2024-02-09 18:07:02 +11:00
2024-09-30 16:27:16 +10:00
/// An enum representing graphics runtimes (video drivers) for use in preset contexts.
2024-02-09 18:07:02 +11:00
enum LIBRA_PRESET_CTX_RUNTIME
# ifdef __cplusplus
2024-03-08 11:37:39 +11:00
: uint32_t
# endif // __cplusplus
{
2024-09-30 16:27:16 +10:00
/// No runtime.
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_NONE = 0 ,
2024-09-30 16:27:16 +10:00
/// OpenGL 3.3+
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_GL_CORE ,
2024-09-30 16:27:16 +10:00
/// Vulkan
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_VULKAN ,
2024-09-30 16:27:16 +10:00
/// Direct3D 11
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_D3D11 ,
2024-09-30 16:27:16 +10:00
/// Direct3D 12
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_D3D12 ,
2024-09-30 16:27:16 +10:00
/// Metal
2024-03-08 11:37:39 +11:00
LIBRA_PRESET_CTX_RUNTIME_METAL ,
2024-02-09 18:07:02 +11:00
} ;
# ifndef __cplusplus
typedef uint32_t LIBRA_PRESET_CTX_RUNTIME ;
2024-03-08 11:37:39 +11:00
# endif // __cplusplus
2022-12-05 14:37:03 +11:00
2024-02-10 09:48:20 +11:00
/// Opaque struct for a Direct3D 11 filter chain.
2023-01-14 09:59:22 +11:00
typedef struct _filter_chain_d3d11 _filter_chain_d3d11 ;
2024-02-10 09:48:20 +11:00
/// Opaque struct for a Direct3D 12 filter chain.
2023-02-06 18:17:30 +11:00
typedef struct _filter_chain_d3d12 _filter_chain_d3d12 ;
2024-03-08 11:37:39 +11:00
/// Opaque struct for a Direct3D 9 filter chain.
typedef struct _filter_chain_d3d9 _filter_chain_d3d9 ;
2024-02-10 09:48:20 +11:00
/// Opaque struct for an OpenGL filter chain.
2023-01-14 09:59:22 +11:00
typedef struct _filter_chain_gl _filter_chain_gl ;
2024-02-13 19:03:45 +11:00
/// Opaque struct for a Metal filter chain.
typedef struct _filter_chain_mtl _filter_chain_mtl ;
2024-02-10 09:48:20 +11:00
/// Opaque struct for a Vulkan filter chain.
2023-01-14 09:59:22 +11:00
typedef struct _filter_chain_vk _filter_chain_vk ;
2022-12-04 10:32:10 +11:00
2024-02-10 09:48:20 +11:00
/// The error type for librashader C API.
2022-12-04 10:32:10 +11:00
typedef struct _libra_error _libra_error ;
2024-02-10 09:48:20 +11:00
/// Opaque struct for a shader preset.
2022-12-04 10:32:10 +11:00
typedef struct _shader_preset _shader_preset ;
2024-02-10 09:48:20 +11:00
/// Opaque struct for a preset context.
2024-02-09 18:07:02 +11:00
typedef struct _preset_ctx _preset_ctx ;
2023-01-14 10:10:09 +11:00
/// A handle to a librashader error object.
typedef struct _libra_error * libra_error_t ;
2022-12-04 10:32:10 +11:00
2023-01-14 10:10:09 +11:00
/// A handle to a shader preset object.
typedef struct _shader_preset * libra_shader_preset_t ;
2022-12-04 10:32:10 +11:00
2024-02-09 18:07:02 +11:00
/// A handle to a preset wildcard context object.
typedef struct _preset_ctx * libra_preset_ctx_t ;
2023-01-15 07:52:58 +11:00
/// A preset parameter.
typedef struct libra_preset_param_t {
2024-03-08 11:37:39 +11:00
/// The name of the parameter
const char * name ;
/// The description of the parameter.
const char * description ;
/// The initial value the parameter is set to.
float initial ;
/// The minimum value that the parameter can be set to.
float minimum ;
/// The maximum value that the parameter can be set to.
float maximum ;
/// The step by which this parameter can be incremented or decremented.
float step ;
2023-01-15 07:52:58 +11:00
} libra_preset_param_t ;
/// A list of preset parameters.
2023-01-21 15:43:45 +11:00
typedef struct libra_preset_param_list_t {
2024-03-08 11:37:39 +11:00
/// A pointer to the parameter
const struct libra_preset_param_t * parameters ;
2024-08-20 15:44:49 +10:00
/// The number of parameters in the list. This field
/// is readonly, and changing it will lead to undefined
/// behaviour on free.
2024-03-08 11:37:39 +11:00
uint64_t length ;
2023-01-21 15:43:45 +11:00
} libra_preset_param_list_t ;
2023-01-15 07:52:58 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2022-12-05 14:37:03 +11:00
/// A GL function loader that librashader needs to be initialized with.
2024-03-08 11:37:39 +11:00
typedef const void * ( * libra_gl_loader_t ) ( const char * ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:56:57 +11:00
2023-02-12 07:37:21 +11:00
/// API version type alias.
2023-02-10 15:36:09 +11:00
typedef size_t LIBRASHADER_API_VERSION ;
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 09:59:22 +11:00
/// Options for filter chain creation.
typedef struct filter_chain_gl_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// The GLSL version. Should be at least `330`.
uint16_t glsl_version ;
/// Whether or not to use the Direct State Access APIs. Only available on OpenGL 4.5+.
/// Using the shader cache requires this option, so this option will implicitly
/// disables the shader cache if false.
bool use_dsa ;
/// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
bool force_no_mipmaps ;
/// Disable the shader object cache. Shaders will be
/// recompiled rather than loaded from the cache.
bool disable_cache ;
2023-01-14 09:59:22 +11:00
} filter_chain_gl_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-01-14 08:05:13 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// A handle to a OpenGL filter chain.
typedef struct _filter_chain_gl * libra_gl_filter_chain_t ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:56:57 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2024-09-08 15:03:43 +10:00
/// OpenGL parameters for an image.
typedef struct libra_image_gl_t {
/// A texture GLuint to the texture.
2024-03-08 11:37:39 +11:00
uint32_t handle ;
2024-09-08 15:03:43 +10:00
/// The format of the texture.
2024-03-08 11:37:39 +11:00
uint32_t format ;
2024-09-08 15:03:43 +10:00
/// The width of the texture.
2024-03-08 11:37:39 +11:00
uint32_t width ;
2024-09-08 15:03:43 +10:00
/// The height of the texture.
2024-03-08 11:37:39 +11:00
uint32_t height ;
2024-09-08 15:03:43 +10:00
} libra_image_gl_t ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2024-08-21 14:14:42 +10:00
/// Defines the output origin for a rendered frame.
typedef struct libra_viewport_t {
/// The x offset in the viewport framebuffer to begin rendering from.
float x ;
/// The y offset in the viewport framebuffer to begin rendering from.
float y ;
/// The width extent of the viewport framebuffer to end rendering, relative to
/// the origin specified by x.
uint32_t width ;
/// The height extent of the viewport framebuffer to end rendering, relative to
/// the origin specified by y.
uint32_t height ;
} libra_viewport_t ;
2023-02-10 15:36:09 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 09:59:22 +11:00
/// Options for each OpenGL shader frame.
typedef struct frame_gl_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
2023-01-14 09:59:22 +11:00
} frame_gl_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-01-14 09:59:22 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
/// Handles required to instantiate vulkan
typedef struct libra_device_vk_t {
2024-03-08 11:37:39 +11:00
/// 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 ;
2024-08-25 15:50:47 +10:00
/// The queue to use, if this is `NULL`, then
2024-09-08 15:03:43 +10:00
/// a suitable queue will be chosen. This must be a graphics queue.
2024-08-25 15:50:47 +10:00
VkQueue queue ;
2024-03-08 11:37:39 +11:00
/// The entry loader for the Vulkan library.
PFN_vkGetInstanceProcAddr entry ;
2023-01-14 09:59:22 +11:00
} libra_device_vk_t ;
# endif
2023-02-10 15:36:09 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
2023-01-14 09:59:22 +11:00
/// Options for filter chain creation.
typedef struct filter_chain_vk_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// 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.
bool force_no_mipmaps ;
/// Use dynamic rendering over explicit render pass objects.
/// It is recommended if possible to use dynamic rendering,
/// because render-pass mode will create new framebuffers per pass.
bool use_dynamic_rendering ;
/// Disable the shader object cache. Shaders will be
/// recompiled rather than loaded from the cache.
bool disable_cache ;
2023-01-14 09:59:22 +11:00
} filter_chain_vk_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-01-14 09:59:22 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
2023-01-14 10:10:09 +11:00
/// A handle to a Vulkan filter chain.
typedef struct _filter_chain_vk * libra_vk_filter_chain_t ;
2023-01-14 09:59:22 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
2024-08-21 14:14:42 +10:00
/// Vulkan parameters for an image.
typedef struct libra_image_vk_t {
/// A raw `VkImage` handle.
2024-03-08 11:37:39 +11:00
VkImage handle ;
2024-08-21 14:14:42 +10:00
/// The `VkFormat` of the `VkImage`.
2024-03-08 11:37:39 +11:00
VkFormat format ;
2024-08-21 14:14:42 +10:00
/// The width of the `VkImage`.
2024-03-08 11:37:39 +11:00
uint32_t width ;
2024-08-21 14:14:42 +10:00
/// The height of the `VkImage`.
2024-03-08 11:37:39 +11:00
uint32_t height ;
2024-08-21 14:14:42 +10:00
} libra_image_vk_t ;
2023-01-14 09:59:22 +11:00
# endif
2023-02-10 15:36:09 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
2024-02-09 18:07:02 +11:00
/// Options for each Vulkan shader frame.
2023-01-21 16:15:09 +11:00
typedef struct frame_vk_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
2023-01-21 16:15:09 +11:00
} frame_vk_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-01-14 09:59:22 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-02-10 15:36:09 +11:00
/// Options for Direct3D 11 filter chain creation.
2023-02-06 18:17:30 +11:00
typedef struct filter_chain_d3d11_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to explicitly disable mipmap
/// generation regardless of shader preset settings.
bool force_no_mipmaps ;
/// Disable the shader object cache. Shaders will be
/// recompiled rather than loaded from the cache.
bool disable_cache ;
2023-02-06 18:17:30 +11:00
} filter_chain_d3d11_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-02-06 18:17:30 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-02-06 18:17:30 +11:00
/// A handle to a Direct3D 11 filter chain.
typedef struct _filter_chain_d3d11 * libra_d3d11_filter_chain_t ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-02-10 15:36:09 +11:00
/// Options for each Direct3D 11 shader frame.
2023-02-06 18:17:30 +11:00
typedef struct frame_d3d11_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
2023-02-06 18:17:30 +11:00
} frame_d3d11_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-02-06 18:17:30 +11:00
2024-03-08 11:37:39 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Options for Direct3D 11 filter chain creation.
typedef struct filter_chain_d3d9_opt_t {
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to explicitly disable mipmap
/// generation regardless of shader preset settings.
bool force_no_mipmaps ;
/// Disable the shader object cache. Shaders will be
/// recompiled rather than loaded from the cache.
bool disable_cache ;
} filter_chain_d3d9_opt_t ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// A handle to a Direct3D 11 filter chain.
typedef struct _filter_chain_d3d9 * libra_d3d9_filter_chain_t ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Options for each Direct3D 11 shader frame.
typedef struct frame_d3d9_opt_t {
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
} frame_d3d9_opt_t ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-06 18:17:30 +11:00
/// Options for Direct3D11 filter chain creation.
typedef struct filter_chain_d3d12_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Force the HLSL shader pipeline. This may reduce shader compatibility.
bool force_hlsl_pipeline ;
/// Whether or not to explicitly disable mipmap
/// generation for intermediate passes regardless
/// of shader preset settings.
bool force_no_mipmaps ;
/// Disable the shader object cache. Shaders will be
/// recompiled rather than loaded from the cache.
bool disable_cache ;
2023-02-06 18:17:30 +11:00
} filter_chain_d3d12_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-02-06 18:17:30 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-06 18:17:30 +11:00
/// A handle to a Direct3D 12 filter chain.
typedef struct _filter_chain_d3d12 * libra_d3d12_filter_chain_t ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-09 13:21:40 +11:00
/// Direct3D 12 parameters for the source image.
2023-02-06 18:17:30 +11:00
typedef struct libra_source_image_d3d12_t {
2024-03-08 11:37:39 +11:00
/// A CPU descriptor handle to a shader resource view of the image.
D3D12_CPU_DESCRIPTOR_HANDLE descriptor ;
2024-09-30 16:27:16 +10:00
/// The resource containing the image.
ID3D12Resource * resource ;
2023-02-06 18:17:30 +11:00
} libra_source_image_d3d12_t ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-09 13:21:40 +11:00
/// Direct3D 12 parameters for the output image.
typedef struct libra_output_image_d3d12_t {
2024-03-08 11:37:39 +11:00
/// A CPU descriptor handle to a shader resource view of the image.
D3D12_CPU_DESCRIPTOR_HANDLE descriptor ;
/// The format of the image.
DXGI_FORMAT format ;
2024-08-20 15:44:49 +10:00
/// The width of the output image.
uint32_t width ;
/// The height of the output image.
uint32_t height ;
2023-02-09 13:21:40 +11:00
} libra_output_image_d3d12_t ;
# endif
2024-09-30 16:27:16 +10:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// A handle to a Direct3D 12 image.
///
/// This must be either a pointer to a `ID3D12Resource`,
/// or a valid source or output image type.
typedef union libra_image_d3d12_handle_t {
/// A pointer to an `ID3D12Resource`, with descriptors managed by the filter chain.
ID3D12Resource * resource ;
/// A source image with externally managed descriptors.
struct libra_source_image_d3d12_t source ;
/// An output image with externally managed descriptors.
struct libra_output_image_d3d12_t output ;
} libra_image_d3d12_handle_t ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
/// Tagged union for a Direct3D 12 image
typedef struct libra_image_d3d12_t {
/// The type of the image.
enum LIBRA_D3D12_IMAGE_TYPE image_type ;
/// The handle to the image.
union libra_image_d3d12_handle_t image ;
} libra_image_d3d12_t ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-10 15:36:09 +11:00
/// Options for each Direct3D 12 shader frame.
2023-02-06 18:17:30 +11:00
typedef struct frame_d3d12_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
2023-02-06 18:17:30 +11:00
} frame_d3d12_opt_t ;
2023-02-10 15:36:09 +11:00
# endif
2023-02-06 18:17:30 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Options for filter chain creation.
typedef struct filter_chain_mtl_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to explicitly disable mipmap generation regardless of shader preset settings.
bool force_no_mipmaps ;
2024-02-13 19:03:45 +11:00
} filter_chain_mtl_opt_t ;
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
2024-09-30 16:27:16 +10:00
/// A handle to a Vulkan filter chain.
2024-02-13 19:03:45 +11:00
typedef struct _filter_chain_mtl * libra_mtl_filter_chain_t ;
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
2024-02-15 10:10:52 +11:00
/// Options for each Metal shader frame.
2024-02-13 19:03:45 +11:00
typedef struct frame_mtl_opt_t {
2024-03-08 11:37:39 +11:00
/// The librashader API version.
LIBRASHADER_API_VERSION version ;
/// Whether or not to clear the history buffers.
bool clear_history ;
/// The direction of rendering.
/// -1 indicates that the frames are played in reverse order.
int32_t frame_direction ;
2024-09-18 09:06:57 +10:00
/// The rotation of the output. 0 = 0deg, 1 = 90deg, 2 = 180deg, 3 = 270deg.
2024-03-08 11:37:39 +11:00
uint32_t rotation ;
/// The total number of subframes ran. Default is 1.
uint32_t total_subframes ;
/// The current sub frame. Default is 1.
uint32_t current_subframe ;
2024-02-13 19:03:45 +11:00
} frame_mtl_opt_t ;
# endif
2024-09-30 16:27:16 +10:00
/// ABI version type alias.
2023-02-12 07:37:21 +11:00
typedef size_t LIBRASHADER_ABI_VERSION ;
/// Function pointer definition for libra_abi_version
typedef LIBRASHADER_ABI_VERSION ( * PFN_libra_instance_abi_version ) ( void ) ;
/// Function pointer definition for libra_abi_version
typedef LIBRASHADER_API_VERSION ( * PFN_libra_instance_api_version ) ( void ) ;
2023-01-14 11:17:57 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_create
typedef libra_error_t ( * PFN_libra_preset_create ) ( const char * filename , libra_shader_preset_t * out ) ;
2023-01-14 11:17:57 +11:00
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_free
2023-01-14 10:10:09 +11:00
typedef libra_error_t ( * PFN_libra_preset_free ) ( libra_shader_preset_t * preset ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_set_param
typedef libra_error_t ( * PFN_libra_preset_set_param ) ( libra_shader_preset_t * preset ,
const char * name ,
float value ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_get_param
2024-09-14 07:22:51 +10:00
typedef libra_error_t ( * PFN_libra_preset_get_param ) ( const libra_shader_preset_t * preset ,
2024-03-08 11:37:39 +11:00
const char * name ,
float * value ) ;
2022-12-04 10:32:10 +11:00
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_print
2023-01-14 10:10:09 +11:00
typedef libra_error_t ( * PFN_libra_preset_print ) ( libra_shader_preset_t * preset ) ;
2022-12-04 10:32:10 +11:00
2023-01-15 09:14:37 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_get_runtime_params
2024-09-14 07:22:51 +10:00
typedef libra_error_t ( * PFN_libra_preset_get_runtime_params ) ( const libra_shader_preset_t * preset ,
2024-03-08 11:37:39 +11:00
struct libra_preset_param_list_t * out ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_free_runtime_params
typedef libra_error_t ( * PFN_libra_preset_free_runtime_params ) ( struct libra_preset_param_list_t preset ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_create_with_context
typedef libra_error_t ( * PFN_libra_preset_create_with_context ) ( const char * filename ,
libra_preset_ctx_t * context ,
libra_shader_preset_t * out ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_create
2024-02-09 18:07:02 +11:00
typedef libra_error_t ( * PFN_libra_preset_ctx_create ) ( libra_preset_ctx_t * out ) ;
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_free
2024-02-09 18:07:02 +11:00
typedef libra_error_t ( * PFN_libra_preset_ctx_free ) ( libra_preset_ctx_t * context ) ;
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_core_name
typedef libra_error_t ( * PFN_libra_preset_ctx_set_core_name ) ( libra_preset_ctx_t * context ,
const char * name ) ;
2023-01-21 15:43:45 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_content_dir
typedef libra_error_t ( * PFN_libra_preset_ctx_set_content_dir ) ( libra_preset_ctx_t * context ,
const char * name ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_param
typedef libra_error_t ( * PFN_libra_preset_ctx_set_param ) ( libra_preset_ctx_t * context ,
const char * name ,
const char * value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_core_rotation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_core_rotation ) ( libra_preset_ctx_t * context ,
uint32_t value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_user_rotation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_user_rotation ) ( libra_preset_ctx_t * context ,
uint32_t value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_screen_orientation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_screen_orientation ) ( libra_preset_ctx_t * context ,
uint32_t value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_allow_rotation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_allow_rotation ) ( libra_preset_ctx_t * context ,
bool value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_view_aspect_orientation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_view_aspect_orientation ) ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_ORIENTATION value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_core_aspect_orientation
typedef libra_error_t ( * PFN_libra_preset_ctx_set_core_aspect_orientation ) ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_ORIENTATION value ) ;
2024-02-09 18:07:02 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_preset_ctx_set_runtime
typedef libra_error_t ( * PFN_libra_preset_ctx_set_runtime ) ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_RUNTIME value ) ;
2023-01-15 09:14:37 +11:00
2023-01-14 11:17:57 +11:00
/// Function pointer definition for libra_error_errno
2023-01-14 10:10:09 +11:00
typedef LIBRA_ERRNO ( * PFN_libra_error_errno ) ( libra_error_t error ) ;
2022-12-04 10:32:10 +11:00
2023-01-14 11:17:57 +11:00
/// Function pointer definition for libra_error_print
2023-01-14 10:10:09 +11:00
typedef int32_t ( * PFN_libra_error_print ) ( libra_error_t error ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 11:17:57 +11:00
/// Function pointer definition for libra_error_free
2023-01-14 10:10:09 +11:00
typedef int32_t ( * PFN_libra_error_free ) ( libra_error_t * error ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 11:17:57 +11:00
/// Function pointer definition for libra_error_write
2023-01-14 10:10:09 +11:00
typedef int32_t ( * PFN_libra_error_write ) ( libra_error_t error , char * * out ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 11:17:57 +11:00
/// Function pointer definition for libra_error_free_string
2023-01-14 10:10:09 +11:00
typedef int32_t ( * PFN_libra_error_free_string ) ( char * * out ) ;
2022-12-05 16:06:37 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_gl_filter_chain_create
typedef libra_error_t ( * PFN_libra_gl_filter_chain_create ) ( libra_shader_preset_t * preset ,
2024-08-09 17:15:52 +10:00
libra_gl_loader_t loader ,
2024-03-08 11:37:39 +11:00
const struct filter_chain_gl_opt_t * options ,
libra_gl_filter_chain_t * out ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 16:06:37 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ,
2024-09-08 15:03:43 +10:00
struct libra_image_gl_t image ,
struct libra_image_gl_t out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_gl_opt_t * opt ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 16:06:37 +11:00
2023-01-15 07:52:58 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-01-15 07:52:58 +11:00
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_gl_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_gl_filter_chain_get_param ) ( const libra_gl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-01-15 07:52:58 +11:00
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-01-15 07:52:58 +11:00
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_gl_filter_chain_get_active_pass_count
2024-09-14 07:22:51 +10:00
typedef libra_error_t ( * PFN_libra_gl_filter_chain_get_active_pass_count ) ( const libra_gl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_gl_filter_chain_free
typedef libra_error_t ( * PFN_libra_gl_filter_chain_free ) ( libra_gl_filter_chain_t * chain ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 16:06:37 +11:00
2023-02-06 18:17:30 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_vk_filter_chain_create
typedef libra_error_t ( * PFN_libra_vk_filter_chain_create ) ( libra_shader_preset_t * preset ,
struct libra_device_vk_t vulkan ,
const struct filter_chain_vk_opt_t * options ,
libra_vk_filter_chain_t * out ) ;
2023-02-06 18:17:30 +11:00
# endif
2023-02-11 19:46:42 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_vk_filter_chain_create_deferred
typedef libra_error_t ( * PFN_libra_vk_filter_chain_create_deferred ) ( libra_shader_preset_t * preset ,
struct libra_device_vk_t vulkan ,
VkCommandBuffer command_buffer ,
const struct filter_chain_vk_opt_t * options ,
libra_vk_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2023-02-06 18:17:30 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ,
2024-08-21 14:14:42 +10:00
struct libra_image_vk_t image ,
struct libra_image_vk_t out ,
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_vk_opt_t * opt ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_vk_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_vk_filter_chain_get_param ) ( const libra_vk_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_vk_filter_chain_get_active_pass_count
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_vk_filter_chain_get_active_pass_count ) ( const libra_vk_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_vk_filter_chain_free
typedef libra_error_t ( * PFN_libra_vk_filter_chain_free ) ( libra_vk_filter_chain_t * chain ) ;
2023-02-06 18:17:30 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_create
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_create ) ( libra_shader_preset_t * preset ,
ID3D11Device * device ,
const struct filter_chain_d3d11_opt_t * options ,
libra_d3d11_filter_chain_t * out ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 16:06:37 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-02-11 19:46:42 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_create_deferred
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_create_deferred ) ( libra_shader_preset_t * preset ,
ID3D11Device * device ,
ID3D11DeviceContext * device_context ,
const struct filter_chain_d3d11_opt_t * options ,
libra_d3d11_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_frame
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_frame ) ( libra_d3d11_filter_chain_t * chain ,
ID3D11DeviceContext * device_context ,
size_t frame_count ,
2024-08-20 15:44:49 +10:00
ID3D11ShaderResourceView * image ,
2024-03-08 11:37:39 +11:00
ID3D11RenderTargetView * out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d11_opt_t * options ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 16:06:37 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_get_param ) ( const libra_d3d11_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///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 ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_get_active_pass_count
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_get_active_pass_count ) ( const libra_d3d11_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d11_filter_chain_free
typedef libra_error_t ( * PFN_libra_d3d11_filter_chain_free ) ( libra_d3d11_filter_chain_t * chain ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_create
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_create ) ( libra_shader_preset_t * preset ,
IDirect3DDevice9 * device ,
const struct filter_chain_d3d9_opt_t * options ,
libra_d3d9_filter_chain_t * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_frame
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_frame ) ( libra_d3d9_filter_chain_t * chain ,
size_t frame_count ,
IDirect3DTexture9 * image ,
IDirect3DSurface9 * out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d9_opt_t * options ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_set_param
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_set_param ) ( libra_d3d9_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_get_param ) ( const libra_d3d9_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_set_active_pass_count
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_set_active_pass_count ) ( libra_d3d9_filter_chain_t * chain ,
uint32_t value ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_get_active_pass_count
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_get_active_pass_count ) ( const libra_d3d9_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Function pointer definition for
///libra_d3d9_filter_chain_free
typedef libra_error_t ( * PFN_libra_d3d9_filter_chain_free ) ( libra_d3d9_filter_chain_t * chain ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-14 11:17:57 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_create
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_create ) ( libra_shader_preset_t * preset ,
ID3D12Device * device ,
const struct filter_chain_d3d12_opt_t * options ,
libra_d3d12_filter_chain_t * out ) ;
2023-01-14 11:17:57 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-11 19:46:42 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_create_deferred
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_create_deferred ) ( libra_shader_preset_t * preset ,
ID3D12Device * device ,
ID3D12GraphicsCommandList * command_list ,
const struct filter_chain_d3d12_opt_t * options ,
libra_d3d12_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-14 11:17:57 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_frame
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_frame ) ( libra_d3d12_filter_chain_t * chain ,
ID3D12GraphicsCommandList * command_list ,
size_t frame_count ,
2024-09-30 16:27:16 +10:00
struct libra_image_d3d12_t image ,
struct libra_image_d3d12_t out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d12_opt_t * options ) ;
2023-01-14 11:17:57 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_set_param
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_set_param ) ( libra_d3d12_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_get_param ) ( const libra_d3d12_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_set_active_pass_count
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_set_active_pass_count ) ( libra_d3d12_filter_chain_t * chain ,
uint32_t value ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_get_active_pass_count
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_get_active_pass_count ) ( const libra_d3d12_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-14 11:17:57 +11:00
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_d3d12_filter_chain_free
typedef libra_error_t ( * PFN_libra_d3d12_filter_chain_free ) ( libra_d3d12_filter_chain_t * chain ) ;
2023-01-14 11:17:57 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_create
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_create ) ( libra_shader_preset_t * preset ,
id < MTLCommandQueue > queue ,
const struct filter_chain_mtl_opt_t * options ,
libra_mtl_filter_chain_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_create_deferred
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_create_deferred ) ( libra_shader_preset_t * preset ,
id < MTLCommandQueue > queue ,
id < MTLCommandBuffer > command_buffer ,
const struct filter_chain_mtl_opt_t * options ,
libra_mtl_filter_chain_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_frame
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_frame ) ( libra_mtl_filter_chain_t * chain ,
id < MTLCommandBuffer > command_buffer ,
size_t frame_count ,
id < MTLTexture > image ,
id < MTLTexture > output ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_mtl_opt_t * opt ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_set_param
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_set_param ) ( libra_mtl_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_get_param
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_get_param ) ( const libra_mtl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_set_active_pass_count
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_set_active_pass_count ) ( libra_mtl_filter_chain_t * chain ,
uint32_t value ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_get_active_pass_count
2024-09-08 15:03:43 +10:00
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_get_active_pass_count ) ( const libra_mtl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Function pointer definition for
2024-03-08 11:37:39 +11:00
///libra_mtl_filter_chain_free
typedef libra_error_t ( * PFN_libra_mtl_filter_chain_free ) ( libra_mtl_filter_chain_t * chain ) ;
2024-02-13 19:03:45 +11:00
# endif
2023-02-12 07:37:21 +11:00
/// The current version of the librashader API.
2023-02-10 15:36:09 +11:00
/// Pass this into `version` for config structs.
2023-02-12 07:37:21 +11:00
///
/// API versions are backwards compatible. It is valid to load
/// a librashader C API instance for all API versions less than
/// or equal to LIBRASHADER_CURRENT_VERSION, and subsequent API
/// versions must remain backwards compatible.
/// ## API Versions
/// - API version 0: 0.1.0
2024-02-13 19:03:45 +11:00
/// - API version 1: 0.2.0
/// - Added rotation, total_subframes, current_subframes to frame options
/// - Added preset context API
/// - Added Metal runtime API
# define LIBRASHADER_CURRENT_VERSION 1
2023-02-10 15:36:09 +11:00
2023-02-12 07:37:21 +11:00
/// The current version of the librashader ABI.
/// Used by the loader to check ABI compatibility.
///
/// ABI version 0 is reserved as a sentinel value.
///
/// ABI versions are not backwards compatible. It is not
/// valid to load a librashader C API instance for any ABI
/// version not equal to LIBRASHADER_CURRENT_ABI.
2024-09-08 15:03:43 +10:00
///
2023-02-12 07:37:21 +11:00
/// ## ABI Versions
2023-02-15 19:13:13 +11:00
/// - ABI version 0: null instance (unloaded)
2023-02-12 07:37:21 +11:00
/// - ABI version 1: 0.1.0
2024-09-07 14:02:25 +10:00
/// - ABI version 2: 0.5.0
/// - Reduced texture size information needed for some runtimes.
/// - Removed wrapper structs for Direct3D 11 SRV and RTV handles.
/// - Removed `gl_context_init`.
/// - Make viewport handling consistent across runtimes, which are now
/// span the output render target if omitted.
2024-08-20 15:44:49 +10:00
# define LIBRASHADER_CURRENT_ABI 2
2023-02-12 07:37:21 +11:00
2022-12-04 10:32:10 +11:00
# ifdef __cplusplus
extern " C " {
2024-03-08 11:37:39 +11:00
# endif // __cplusplus
2022-12-04 10:32:10 +11:00
2023-01-14 10:10:09 +11:00
/// Get the error code corresponding to this error object.
///
/// ## Safety
/// - `error` must be valid and initialized.
LIBRA_ERRNO libra_error_errno ( libra_error_t error ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// Print the error message.
///
2024-03-08 11:37:39 +11:00
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
2023-01-14 10:10:09 +11:00
/// ## Safety
/// - `error` must be a valid and initialized instance of `libra_error_t`.
int32_t libra_error_print ( libra_error_t error ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// Frees any internal state kept by the error.
///
2024-03-08 11:37:39 +11:00
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
/// The resulting error object becomes null.
2023-01-14 10:10:09 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `error` must be null or a pointer to a valid and initialized instance of `libra_error_t`.
2023-01-14 10:10:09 +11:00
int32_t libra_error_free ( libra_error_t * error ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// Writes the error message into `out`
///
2024-03-08 11:37:39 +11:00
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
2023-01-14 10:10:09 +11:00
/// ## Safety
/// - `error` must be a valid and initialized instance of `libra_error_t`.
2024-03-08 11:37:39 +11:00
/// - `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 ) ;
2023-01-14 10:10:09 +11:00
/// Frees an error string previously allocated by `libra_error_write`.
///
/// After freeing, the pointer will be set to null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - 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.
2023-01-14 10:10:09 +11:00
int32_t libra_error_free_string ( char * * out ) ;
/// Load a preset.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `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`.
2023-01-14 10:10:09 +11:00
/// ## Returns
2024-03-08 11:37:39 +11:00
/// - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`.
2023-01-14 10:10:09 +11:00
libra_error_t libra_preset_create ( const char * filename ,
libra_shader_preset_t * out ) ;
2024-02-09 18:07:02 +11:00
/// Load a preset with the given wildcard context.
///
/// The wildcard context is immediately invalidated and must be recreated after
/// the preset is created.
///
2024-03-08 11:37:39 +11:00
/// Path information variables `PRESET_DIR` and `PRESET` will automatically be filled in.
2024-02-09 18:07:02 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `filename` must be either null or a valid, aligned pointer to a string path to the shader preset.
/// - `context` must be either null or a valid, aligned pointer to a initialized `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// - `context` is invalidated after this function returns.
2024-03-08 11:37:39 +11:00
/// - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_shader_preset_t`.
2024-02-09 18:07:02 +11:00
/// ## Returns
2024-03-08 11:37:39 +11:00
/// - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`.
2024-02-09 18:07:02 +11:00
libra_error_t libra_preset_create_with_context ( const char * filename ,
libra_preset_ctx_t * context ,
libra_shader_preset_t * out ) ;
2023-01-14 10:10:09 +11:00
/// Free the preset.
///
2024-03-08 11:37:39 +11:00
/// If `preset` is null, this function does nothing. The resulting value in `preset` then becomes
/// null.
2023-01-14 10:10:09 +11:00
///
/// ## Safety
2024-02-09 18:07:02 +11:00
/// - `preset` must be a valid and aligned pointer to a `libra_shader_preset_t`.
2023-01-14 10:10:09 +11:00
libra_error_t libra_preset_free ( libra_shader_preset_t * preset ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// Set the value of the parameter in the preset.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `preset` must be null or a valid and aligned pointer to a `libra_shader_preset_t`.
2023-01-14 10:10:09 +11:00
/// - `name` must be null or a valid and aligned pointer to a string.
2024-03-08 11:37:39 +11:00
libra_error_t libra_preset_set_param ( libra_shader_preset_t * preset , const char * name , float value ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// 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`.
2024-09-14 07:22:51 +10:00
libra_error_t libra_preset_get_param ( const libra_shader_preset_t * preset ,
const char * name ,
float * value ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 10:10:09 +11:00
/// Pretty print the shader preset.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `preset` must be null or a valid and aligned pointer to a `libra_shader_preset_t`.
2023-01-14 10:10:09 +11:00
libra_error_t libra_preset_print ( libra_shader_preset_t * preset ) ;
2023-01-14 08:05:13 +11:00
2023-01-21 15:43:45 +11:00
/// Get a list of runtime parameters.
2023-01-14 10:10:09 +11:00
///
2023-01-15 07:52:58 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `preset` must be null or a valid and aligned pointer to a `libra_shader_preset_t`.
2023-01-15 07:52:58 +11:00
/// - `out` must be an aligned pointer to a `libra_preset_parameter_list_t`.
2024-03-08 11:37:39 +11:00
/// - The output struct should be treated as immutable. Mutating any struct fields
2023-01-21 15:43:45 +11:00
/// in the returned struct may at best cause memory leaks, and at worse
/// cause undefined behaviour when later freed.
2024-03-08 11:37:39 +11:00
/// - It is safe to call `libra_preset_get_runtime_params` multiple times, however
2023-01-21 15:43:45 +11:00
/// the output struct must only be freed once per call.
2024-09-14 07:22:51 +10:00
libra_error_t libra_preset_get_runtime_params ( const libra_shader_preset_t * preset ,
2024-03-08 11:37:39 +11:00
struct libra_preset_param_list_t * out ) ;
2023-01-21 15:43:45 +11:00
/// 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
2024-03-08 11:37:39 +11:00
/// - 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
2023-01-21 15:43:45 +11:00
/// has been freed is a use-after-free and is immediate undefined behaviour.
///
2024-03-08 11:37:39 +11:00
/// - 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 ) ;
2023-01-14 08:05:13 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// 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.
2024-03-08 11:37:39 +11:00
libra_error_t libra_gl_filter_chain_create ( libra_shader_preset_t * preset ,
2024-08-09 17:15:52 +10:00
libra_gl_loader_t loader ,
2024-03-08 11:37:39 +11:00
const struct filter_chain_gl_opt_t * options ,
libra_gl_filter_chain_t * out ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// Draw a frame with the given parameters for the given filter chain.
///
2024-08-21 14:14:42 +10:00
/// ## Parameters
///
/// - `chain` is a handle to the filter chain.
/// - `frame_count` is the number of frames passed to the shader
2024-09-08 15:03:43 +10:00
/// - `image` is a `libra_image_gl_t`, containing the name of a Texture, format, and size information to
2024-08-21 14:14:42 +10:00
/// to an image that will serve as the source image for the frame.
/// - `out` is a `libra_output_framebuffer_gl_t`, containing the name of a Framebuffer, the name of a Texture, format,
/// and size information for the render target of the frame.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
///
2023-01-14 10:10:09 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
2023-01-14 10:10:09 +11:00
/// function will return an error.
2024-03-08 11:37:39 +11:00
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
2023-01-14 10:10:09 +11:00
/// values for the model view projection matrix.
2024-03-08 11:37:39 +11:00
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
2023-01-14 10:10:09 +11:00
/// struct.
2024-03-08 11:37:39 +11:00
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
/// thread at a time may call this function. The thread `libra_gl_filter_chain_frame` is called from
/// must have its thread-local OpenGL context initialized with the same context used to create
/// the filter chain.
libra_error_t libra_gl_filter_chain_frame ( libra_gl_filter_chain_t * chain ,
size_t frame_count ,
2024-09-08 15:03:43 +10:00
struct libra_image_gl_t image ,
struct libra_image_gl_t out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_gl_opt_t * opt ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2023-01-15 07:52:58 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
/// Sets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `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 ,
float value ) ;
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Gets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_gl_filter_chain_get_param ( const libra_gl_filter_chain_t * chain ,
2023-01-15 07:52:58 +11:00
const char * param_name ,
float * out ) ;
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Sets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `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 ) ;
2023-01-15 07:52:58 +11:00
# endif
# if defined(LIBRA_RUNTIME_OPENGL)
/// Gets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
2024-09-14 07:22:51 +10:00
libra_error_t libra_gl_filter_chain_get_active_pass_count ( const libra_gl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2023-01-14 08:10:54 +11:00
# if defined(LIBRA_RUNTIME_OPENGL)
2023-01-14 10:10:09 +11:00
/// Free a GL filter chain.
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
2024-08-20 15:44:49 +10:00
/// - The context that the filter chain was initialized with **must be current** before freeing the filter chain.
2023-01-14 10:10:09 +11:00
libra_error_t libra_gl_filter_chain_free ( libra_gl_filter_chain_t * chain ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2023-02-06 18:17:30 +11:00
# 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:
2024-03-08 11:37:39 +11:00
/// - The handles provided in `vulkan` must be valid for the command buffers that
2024-02-13 19:03:45 +11:00
/// `libra_vk_filter_chain_frame` will write to.
2023-02-06 18:17:30 +11:00
/// 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.
2024-03-08 11:37:39 +11:00
libra_error_t libra_vk_filter_chain_create ( libra_shader_preset_t * preset ,
struct libra_device_vk_t vulkan ,
const struct filter_chain_vk_opt_t * options ,
libra_vk_filter_chain_t * out ) ;
2023-02-06 18:17:30 +11:00
# endif
2023-02-11 19:46:42 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
2024-03-08 11:37:39 +11:00
/// Create the filter chain given the shader preset deferring and GPU-side initialization
/// to the caller. This function therefore requires no external synchronization of the device queue.
2023-02-11 19:46:42 +11:00
///
/// The shader preset is immediately invalidated and must be recreated after
/// the filter chain is created.
///
/// ## Safety:
2024-03-08 11:37:39 +11:00
/// - The handles provided in `vulkan` must be valid for the command buffers that
2024-02-13 19:03:45 +11:00
/// `libra_vk_filter_chain_frame` will write to.
2023-02-11 19:46:42 +11:00
/// - `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.
///
2024-03-08 11:37:39 +11:00
/// The provided command buffer must be ready for recording and contain no prior commands.
/// The caller is responsible for ending the command buffer and immediately submitting it to a
/// graphics queue. The command buffer must be completely executed before calling `libra_vk_filter_chain_frame`.
libra_error_t libra_vk_filter_chain_create_deferred ( libra_shader_preset_t * preset ,
struct libra_device_vk_t vulkan ,
VkCommandBuffer command_buffer ,
const struct filter_chain_vk_opt_t * options ,
libra_vk_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2023-02-06 18:17:30 +11:00
# if defined(LIBRA_RUNTIME_VULKAN)
2024-03-08 11:37:39 +11:00
/// Records rendering commands for a frame with the given parameters for the given filter chain
/// to the input command buffer.
2023-02-06 18:17:30 +11:00
///
2024-09-30 16:34:41 +10:00
/// A pipeline barrier **will not** be created for the final pass. The output image must be
2024-08-21 14:14:42 +10:00
/// in `VK_COLOR_ATTACHMENT_OPTIMAL`, and will remain so after all shader passes. The caller must transition
2024-03-08 11:37:39 +11:00
/// the output image to the final layout.
2023-02-06 18:17:30 +11:00
///
2024-08-21 14:14:42 +10:00
/// ## Parameters
///
/// - `chain` is a handle to the filter chain.
/// - `command_buffer` is a `VkCommandBuffer` handle to record draw commands to.
/// The provided command buffer must be ready for recording and contain no prior commands
/// - `frame_count` is the number of frames passed to the shader
/// - `image` is a `libra_image_vk_t`, containing a `VkImage` handle, it's format and size information,
/// to an image that will serve as the source image for the frame. The input image must be in
/// the `VK_SHADER_READ_ONLY_OPTIMAL` layout.
/// - `out` is a `libra_image_vk_t`, containing a `VkImage` handle, it's format and size information,
/// for the render target of the frame. The output image must be in `VK_COLOR_ATTACHMENT_OPTIMAL` layout.
/// The output image will remain in `VK_COLOR_ATTACHMENT_OPTIMAL` after all shader passes.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
///
2023-02-06 18:17:30 +11:00
/// ## Safety
/// - `libra_vk_filter_chain_frame` **must not be called within a RenderPass**.
2024-03-08 11:37:39 +11:00
/// - `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
2023-02-06 18:17:30 +11:00
/// function will return an error.
2024-03-08 11:37:39 +11:00
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
2023-02-06 18:17:30 +11:00
/// values for the model view projection matrix.
2024-03-08 11:37:39 +11:00
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_vk_opt_t`
2023-02-06 18:17:30 +11:00
/// struct.
2024-03-08 11:37:39 +11:00
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
2023-02-10 17:29:49 +11:00
/// thread at a time may call this function.
2024-03-08 11:37:39 +11:00
libra_error_t libra_vk_filter_chain_frame ( libra_vk_filter_chain_t * chain ,
VkCommandBuffer command_buffer ,
size_t frame_count ,
2024-08-21 14:14:42 +10:00
struct libra_image_vk_t image ,
struct libra_image_vk_t out ,
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_vk_opt_t * opt ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Sets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
2023-02-06 18:17:30 +11:00
/// - `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 ,
float value ) ;
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Gets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
2023-02-06 18:17:30 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_vk_filter_chain_get_param ( const libra_vk_filter_chain_t * chain ,
2023-02-06 18:17:30 +11:00
const char * param_name ,
float * out ) ;
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Sets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `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 ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Gets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
2024-09-08 15:03:43 +10:00
libra_error_t libra_vk_filter_chain_get_active_pass_count ( const libra_vk_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-02-06 18:17:30 +11:00
# endif
# if defined(LIBRA_RUNTIME_VULKAN)
/// Free a Vulkan filter chain.
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_vk_filter_chain_t`.
2023-02-06 18:17:30 +11:00
libra_error_t libra_vk_filter_chain_free ( libra_vk_filter_chain_t * chain ) ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// 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.
2023-01-27 11:05:48 +11:00
/// - `device` must not be null.
2023-01-14 10:10:09 +11:00
/// - `out` must be aligned, but may be null, invalid, or uninitialized.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d11_filter_chain_create ( libra_shader_preset_t * preset ,
ID3D11Device * device ,
const struct filter_chain_d3d11_opt_t * options ,
libra_d3d11_filter_chain_t * out ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 10:32:10 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2024-03-08 11:37:39 +11:00
/// Create the filter chain given the shader preset, deferring and GPU-side initialization
/// to the caller. This function is therefore requires no external synchronization of the
/// immediate context, as long as the immediate context is not used as the input context,
/// nor of the device, as long as the device is not single-threaded only.
2023-02-11 19:46:42 +11:00
///
/// 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.
/// - `device` must not be null.
/// - `device_context` not be null.
/// - `out` must be aligned, but may be null, invalid, or uninitialized.
///
2024-03-08 11:37:39 +11:00
/// The provided context must either be immediate, or immediately submitted after this function
/// returns, **before drawing frames**, or lookup textures will fail to load and the filter chain
/// will be in an invalid state.
2023-02-11 19:46:42 +11:00
///
2024-03-08 11:37:39 +11:00
/// If the context is deferred, it must be ready for command recording, and have no prior commands
/// recorded. No commands shall be recorded after, the caller must immediately call [`FinishCommandList`](https://learn.microsoft.com/en-us/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-finishcommandlist)
/// and execute the command list on the immediate context after this function returns.
2023-02-11 19:46:42 +11:00
///
2024-03-08 11:37:39 +11:00
/// If the context is immediate, then access to the immediate context requires external synchronization.
libra_error_t libra_d3d11_filter_chain_create_deferred ( libra_shader_preset_t * preset ,
ID3D11Device * device ,
ID3D11DeviceContext * device_context ,
const struct filter_chain_d3d11_opt_t * options ,
libra_d3d11_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// Draw a frame with the given parameters for the given filter chain.
///
2024-08-21 14:14:42 +10:00
/// ## Parameters
///
/// - `chain` is a handle to the filter chain.
/// - `device_context` is the ID3D11DeviceContext used to record draw commands to.
/// If `device_context` is null, then commands are recorded onto the immediate context. Otherwise,
/// it will record commands onto the provided context. If the context is deferred, librashader
/// will not finalize command lists. The context must otherwise be associated with the `ID3D11Device`
/// the filter chain was created with.
///
/// - `frame_count` is the number of frames passed to the shader
/// - `image` is a pointer to a `ID3D11ShaderResourceView` that will serve as the source image for the frame.
/// - `out` is a pointer to a `ID3D11RenderTargetView` that will serve as the render target for the frame.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
2023-02-11 10:08:11 +11:00
///
2023-01-14 10:10:09 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
2023-01-14 10:10:09 +11:00
/// function will return an error.
2024-03-08 11:37:39 +11:00
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
2023-01-14 10:10:09 +11:00
/// values for the model view projection matrix.
2024-03-08 11:37:39 +11:00
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_d3d11_opt_t`
2023-01-14 10:10:09 +11:00
/// struct.
2023-01-27 11:05:48 +11:00
/// - `out` must not be null.
/// - `image.handle` must not be null.
2024-03-08 11:37:39 +11:00
/// - If `device_context` is null, commands will be recorded onto the immediate context of the `ID3D11Device`
/// this filter chain was created with. The context must otherwise be associated with the `ID3D11Device`
/// the filter chain was created with.
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
2023-02-10 17:29:49 +11:00
/// thread at a time may call this function.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d11_filter_chain_frame ( libra_d3d11_filter_chain_t * chain ,
ID3D11DeviceContext * device_context ,
size_t frame_count ,
2024-08-20 15:44:49 +10:00
ID3D11ShaderResourceView * image ,
2024-03-08 11:37:39 +11:00
ID3D11RenderTargetView * out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d11_opt_t * options ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-04 11:55:27 +11:00
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Sets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d11_filter_chain_set_param ( libra_d3d11_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Gets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d11_filter_chain_get_param ( const libra_d3d11_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Sets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `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 ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-15 07:52:58 +11:00
/// Gets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d11_filter_chain_get_active_pass_count ( const libra_d3d11_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11))
2023-01-14 10:10:09 +11:00
/// Free a D3D11 filter chain.
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
2023-01-14 10:10:09 +11:00
libra_error_t libra_d3d11_filter_chain_free ( libra_d3d11_filter_chain_t * chain ) ;
2023-01-14 08:05:13 +11:00
# endif
2022-12-05 15:54:47 +11:00
2024-03-08 11:37:39 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// 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.
/// - `device` must not be null.
/// - `out` must be aligned, but may be null, invalid, or uninitialized.
libra_error_t libra_d3d9_filter_chain_create ( libra_shader_preset_t * preset ,
IDirect3DDevice9 * device ,
const struct filter_chain_d3d9_opt_t * options ,
libra_d3d9_filter_chain_t * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Draw a frame with the given parameters for the given filter chain.
///
2024-08-21 14:14:42 +10:00
/// ## Parameters
/// - `chain` is a handle to the filter chain.
/// - `frame_count` is the number of frames passed to the shader
/// - `image` is a pointer to a `IDirect3DTexture9` that will serve as the source image for the frame.
/// - `out` is a pointer to a `IDirect3DSurface9` that will serve as the render target for the frame.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
2024-03-08 11:37:39 +11:00
///
/// ## Safety
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
/// function will return an error.
2024-08-21 14:14:42 +10:00
/// - `viewport` may be null, or if it is not null, must be an aligned pointer to an instance of `libra_viewport_t`.
2024-03-08 11:37:39 +11:00
/// - `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_d3d9_opt_t`
/// struct.
/// - `out` must not be null.
2024-09-14 07:17:18 +10:00
/// - `image` must not be null.
2024-03-08 11:37:39 +11:00
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
/// thread at a time may call this function.
libra_error_t libra_d3d9_filter_chain_frame ( libra_d3d9_filter_chain_t * chain ,
size_t frame_count ,
IDirect3DTexture9 * image ,
IDirect3DSurface9 * out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d9_opt_t * options ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// 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_d3d9_filter_chain_t`.
/// - `param_name` must be either null or a null terminated string.
libra_error_t libra_d3d9_filter_chain_set_param ( libra_d3d9_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// 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_d3d9_filter_chain_t`.
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d9_filter_chain_get_param ( const libra_d3d9_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// 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_d3d9_filter_chain_t`.
libra_error_t libra_d3d9_filter_chain_set_active_pass_count ( libra_d3d9_filter_chain_t * chain ,
uint32_t value ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// 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_d3d9_filter_chain_t`.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d9_filter_chain_get_active_pass_count ( const libra_d3d9_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
# endif
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D9))
/// Free a d3d9 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_d3d9_filter_chain_t`.
libra_error_t libra_d3d9_filter_chain_free ( libra_d3d9_filter_chain_t * chain ) ;
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-14 10:10:09 +11:00
/// 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.
2023-02-06 18:17:30 +11:00
/// - `device` must not be null.
2023-01-14 10:10:09 +11:00
/// - `out` must be aligned, but may be null, invalid, or uninitialized.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d12_filter_chain_create ( libra_shader_preset_t * preset ,
ID3D12Device * device ,
const struct filter_chain_d3d12_opt_t * options ,
libra_d3d12_filter_chain_t * out ) ;
2023-01-14 09:59:22 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2024-03-08 11:37:39 +11:00
/// Create the filter chain given the shader preset deferring and GPU-side initialization
/// to the caller. This function therefore requires no external synchronization of the device queue.
2023-02-11 19:46:42 +11:00
///
/// 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.
/// - `device` must not be null.
/// - `out` must be aligned, but may be null, invalid, or uninitialized.
/// - `cmd` must not be null.
///
2024-03-08 11:37:39 +11:00
/// The provided command list must be ready for recording and contain no prior commands.
/// The caller is responsible for ending the command list and immediately submitting it to a
/// graphics queue. The command list must be completely executed before calling `libra_d3d12_filter_chain_frame`.
libra_error_t libra_d3d12_filter_chain_create_deferred ( libra_shader_preset_t * preset ,
ID3D12Device * device ,
ID3D12GraphicsCommandList * command_list ,
const struct filter_chain_d3d12_opt_t * options ,
libra_d3d12_filter_chain_t * out ) ;
2023-02-11 19:46:42 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2024-03-08 11:37:39 +11:00
/// Records rendering commands for a frame with the given parameters for the given filter chain
/// to the input command list.
2023-01-14 10:10:09 +11:00
///
2024-09-30 16:34:41 +10:00
/// A resource barrier **will not** be created for the final pass. The output image will
2024-03-08 11:37:39 +11:00
/// remain in `D3D12_RESOURCE_STATE_RENDER_TARGET` after all shader passes. The caller must transition
/// the output image to the final resource state.
2023-02-11 10:08:11 +11:00
///
2024-08-21 14:14:42 +10:00
/// ## Parameters
///
/// - `chain` is a handle to the filter chain.
/// - `command_list` is a `ID3D12GraphicsCommandList` to record draw commands to.
/// The provided command list must be open and associated with the `ID3D12Device` this filter chain was created with.
/// - `frame_count` is the number of frames passed to the shader
/// - `image` is a `libra_source_image_d3d12_t`, containing a `ID3D12Resource` pointer and CPU descriptor
/// to an image that will serve as the source image for the frame. The input image must be in the
/// `D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE` resource state or equivalent barrier layout.
/// - `out` is a `libra_output_image_d3d12_t`, containing a CPU descriptor handle, format, and size information
/// for the render target of the frame. The output image must be in
/// `D3D12_RESOURCE_STATE_RENDER_TARGET` resource state or equivalent barrier layout.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
///
2023-01-14 10:10:09 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
2023-01-14 10:10:09 +11:00
/// function will return an error.
2024-03-08 11:37:39 +11:00
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
2023-01-14 10:10:09 +11:00
/// values for the model view projection matrix.
2024-03-08 11:37:39 +11:00
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_d3d12_opt_t`
2023-01-14 10:10:09 +11:00
/// struct.
2023-02-06 18:17:30 +11:00
/// - `out` must be a descriptor handle to a render target view.
/// - `image.resource` must not be null.
2024-03-08 11:37:39 +11:00
/// - `command_list` must be a non-null pointer to a `ID3D12GraphicsCommandList` that is open,
/// and must be associated with the `ID3D12Device` this filter chain was created with.
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
2023-02-10 17:29:49 +11:00
/// thread at a time may call this function.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d12_filter_chain_frame ( libra_d3d12_filter_chain_t * chain ,
ID3D12GraphicsCommandList * command_list ,
size_t frame_count ,
2024-09-30 16:27:16 +10:00
struct libra_image_d3d12_t image ,
struct libra_image_d3d12_t out ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_d3d12_opt_t * options ) ;
2023-01-14 09:59:22 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Sets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d12_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-03-08 11:37:39 +11:00
libra_error_t libra_d3d12_filter_chain_set_param ( libra_d3d12_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Gets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d12_filter_chain_t`.
2023-01-15 07:52:58 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d12_filter_chain_get_param ( const libra_d3d12_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
const char * param_name ,
float * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Sets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d12_filter_chain_t`.
libra_error_t libra_d3d12_filter_chain_set_active_pass_count ( libra_d3d12_filter_chain_t * chain ,
uint32_t value ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-01-15 07:52:58 +11:00
/// Gets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d12_filter_chain_t`.
2024-09-08 15:03:43 +10:00
libra_error_t libra_d3d12_filter_chain_get_active_pass_count ( const libra_d3d12_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2023-01-15 07:52:58 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12))
2023-02-06 18:17:30 +11:00
/// Free a D3D12 filter chain.
2023-01-14 10:10:09 +11:00
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d12_filter_chain_t`.
2023-02-06 18:17:30 +11:00
libra_error_t libra_d3d12_filter_chain_free ( libra_d3d12_filter_chain_t * chain ) ;
2023-01-14 09:59:22 +11:00
# endif
2024-02-13 19:03:45 +11:00
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// 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:
/// - `queue` must be valid for the command buffers
/// that `libra_mtl_filter_chain_frame` will write to.
/// - `queue` must be a reference to a `id<MTLCommandQueue>`.
/// - `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.
2024-03-08 11:37:39 +11:00
libra_error_t libra_mtl_filter_chain_create ( libra_shader_preset_t * preset ,
id < MTLCommandQueue > queue ,
const struct filter_chain_mtl_opt_t * options ,
libra_mtl_filter_chain_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
2024-03-08 11:37:39 +11:00
/// Create the filter chain given the shader preset deferring and GPU-side initialization
/// to the caller. This function therefore requires no external synchronization of the device queue.
2024-02-13 19:03:45 +11:00
///
/// The shader preset is immediately invalidated and must be recreated after
/// the filter chain is created.
///
/// ## Safety:
/// - `queue` must be valid for the command buffers
/// that `libra_mtl_filter_chain_frame` will write to.
/// - `queue` must be a reference to a `id<MTLCommandQueue>`.
2024-03-08 11:37:39 +11:00
/// - `command_buffer` must be a valid reference to a `MTLCommandBuffer` that is not already encoding.
2024-02-13 19:03:45 +11:00
/// - `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.
///
2024-03-08 11:37:39 +11:00
/// The provided command buffer must be ready for recording and contain no prior commands.
/// The caller is responsible for ending the command buffer and immediately submitting it to a
/// graphics queue. The command buffer must be completely executed before calling `libra_mtl_filter_chain_frame`.
libra_error_t libra_mtl_filter_chain_create_deferred ( libra_shader_preset_t * preset ,
id < MTLCommandQueue > queue ,
id < MTLCommandBuffer > command_buffer ,
const struct filter_chain_mtl_opt_t * options ,
libra_mtl_filter_chain_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
2024-03-08 11:37:39 +11:00
/// Records rendering commands for a frame with the given parameters for the given filter chain
/// to the input command buffer.
2024-08-21 14:14:42 +10:00
/// ## Parameters
///
/// - `chain` is a handle to the filter chain.
/// - `command_buffer` is a `MTLCommandBuffer` handle to record draw commands to.
/// The provided command buffer must be ready for encoding and contain no prior commands
/// - `frame_count` is the number of frames passed to the shader
/// - `image` is a `id<MTLTexture>` that will serve as the source image for the frame.
/// - `out` is a `id<MTLTexture>` that is the render target of the frame.
///
/// - `viewport` is a pointer to a `libra_viewport_t` that specifies the area onto which scissor and viewport
/// will be applied to the render target. It may be null, in which case a default viewport spanning the
/// entire render target will be used.
/// - `mvp` is a pointer to an array of 16 `float` values to specify the model view projection matrix to
/// be passed to the shader.
/// - `options` is a pointer to options for the frame. Valid options are dependent on the `LIBRASHADER_API_VERSION`
/// passed in. It may be null, in which case default options for the filter chain are used.
2024-02-13 19:03:45 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `command_buffer` must be a valid reference to a `MTLCommandBuffer` that is not already encoding.
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
2024-02-13 19:03:45 +11:00
/// function will return an error.
2024-03-08 11:37:39 +11:00
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
2024-02-13 19:03:45 +11:00
/// values for the model view projection matrix.
2024-03-08 11:37:39 +11:00
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_mtl_opt_t`
2024-02-13 19:03:45 +11:00
/// struct.
2024-03-08 11:37:39 +11:00
/// - You must ensure that only one thread has access to `chain` before you call this function. Only one
2024-02-13 19:03:45 +11:00
/// thread at a time may call this function.
2024-03-08 11:37:39 +11:00
libra_error_t libra_mtl_filter_chain_frame ( libra_mtl_filter_chain_t * chain ,
id < MTLCommandBuffer > command_buffer ,
size_t frame_count ,
id < MTLTexture > image ,
id < MTLTexture > output ,
2024-08-21 14:14:42 +10:00
const struct libra_viewport_t * viewport ,
2024-03-08 11:37:39 +11:00
const float * mvp ,
const struct frame_mtl_opt_t * opt ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Sets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_mtl_filter_chain_t`.
2024-02-13 19:03:45 +11:00
/// - `param_name` must be either null or a null terminated string.
libra_error_t libra_mtl_filter_chain_set_param ( libra_mtl_filter_chain_t * chain ,
const char * param_name ,
float value ) ;
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Gets a parameter for the filter chain.
///
/// If the parameter does not exist, returns an error.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_mtl_filter_chain_t`.
2024-02-13 19:03:45 +11:00
/// - `param_name` must be either null or a null terminated string.
2024-09-08 15:03:43 +10:00
libra_error_t libra_mtl_filter_chain_get_param ( const libra_mtl_filter_chain_t * chain ,
2024-02-13 19:03:45 +11:00
const char * param_name ,
float * out ) ;
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Sets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_mtl_filter_chain_t`.
libra_error_t libra_mtl_filter_chain_set_active_pass_count ( libra_mtl_filter_chain_t * chain ,
uint32_t value ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
/// Gets the number of active passes for this chain.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_mtl_filter_chain_t`.
2024-09-08 15:03:43 +10:00
libra_error_t libra_mtl_filter_chain_get_active_pass_count ( const libra_mtl_filter_chain_t * chain ,
2024-03-08 11:37:39 +11:00
uint32_t * out ) ;
2024-02-13 19:03:45 +11:00
# endif
# if (defined(__APPLE__) && defined(LIBRA_RUNTIME_METAL) && defined(__OBJC__))
2024-02-15 10:10:52 +11:00
/// Free a Metal filter chain.
2024-02-13 19:03:45 +11:00
///
/// The resulting value in `chain` then becomes null.
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_mtl_filter_chain_t`.
2024-02-13 19:03:45 +11:00
libra_error_t libra_mtl_filter_chain_free ( libra_mtl_filter_chain_t * chain ) ;
# endif
2023-02-12 07:37:21 +11:00
/// Get the ABI version of the loaded instance.
LIBRASHADER_ABI_VERSION libra_instance_abi_version ( void ) ;
/// Get the API version of the loaded instance.
LIBRASHADER_API_VERSION libra_instance_api_version ( void ) ;
2024-02-09 18:07:02 +11:00
/// Create a wildcard context
///
/// The C API does not allow directly setting certain variables
///
/// - `PRESET_DIR` and `PRESET` are inferred on preset creation.
2024-03-08 11:37:39 +11:00
/// - `VID-DRV-SHADER-EXT` and `VID-DRV-PRESET-EXT` are always set to `slang` and `slangp` for librashader.
/// - `VID-FINAL-ROT` is automatically calculated as the sum of `VID-USER-ROT` and `CORE-REQ-ROT` if either are present.
///
/// These automatically inferred variables, as well as all other variables can be overridden with
/// `libra_preset_ctx_set_param`, but the expected string values must be provided.
2024-09-08 15:03:43 +10:00
/// See <https://github.com/libretro/RetroArch/pull/15023> for a list of expected string values.
2024-03-08 11:37:39 +11:00
///
/// No variables can be removed once added to the context, however subsequent calls to set the same
/// variable will overwrite the expected variable.
2024-02-09 18:07:02 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// ## Returns
2024-03-08 11:37:39 +11:00
/// - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`.
2024-02-09 18:07:02 +11:00
libra_error_t libra_preset_ctx_create ( libra_preset_ctx_t * out ) ;
/// Free the wildcard context.
///
2024-03-08 11:37:39 +11:00
/// If `context` is null, this function does nothing. The resulting value in `context` then becomes
/// null.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
/// - `context` must be a valid and aligned pointer to a `libra_preset_ctx_t`
libra_error_t libra_preset_ctx_free ( libra_preset_ctx_t * context ) ;
/// Set the core name (`CORE`) variable in the context
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// - `name` must be null or a valid and aligned pointer to a string.
2024-03-08 11:37:39 +11:00
libra_error_t libra_preset_ctx_set_core_name ( libra_preset_ctx_t * context , const char * name ) ;
2024-02-09 18:07:02 +11:00
/// Set the content directory (`CONTENT-DIR`) variable in the context.
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// - `name` must be null or a valid and aligned pointer to a string.
2024-03-08 11:37:39 +11:00
libra_error_t libra_preset_ctx_set_content_dir ( libra_preset_ctx_t * context , const char * name ) ;
2024-02-09 18:07:02 +11:00
/// Set a custom string variable in context.
///
2024-03-08 11:37:39 +11:00
/// If the path contains this variable when loading a preset, it will be replaced with the
/// provided contents.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// - `name` must be null or a valid and aligned pointer to a string.
/// - `value` must be null or a valid and aligned pointer to a string.
libra_error_t libra_preset_ctx_set_param ( libra_preset_ctx_t * context ,
2024-03-08 11:37:39 +11:00
const char * name ,
const char * value ) ;
2024-02-09 18:07:02 +11:00
/// Set the graphics runtime (`VID-DRV`) variable in the context.
///
/// Note that librashader only supports the following runtimes.
///
/// - Vulkan
/// - GLCore
/// - Direct3D11
/// - Direct3D12
2024-09-30 16:27:16 +10:00
/// - Metal
2024-02-09 18:07:02 +11:00
///
/// This will also set the appropriate video driver extensions.
///
2024-03-08 11:37:39 +11:00
/// For librashader, `VID-DRV-SHADER-EXT` and `VID-DRV-PRESET-EXT` are always `slang` and `slangp`.
/// To override this, use `libra_preset_ctx_set_param`.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
2024-02-09 18:07:02 +11:00
/// - `name` must be null or a valid and aligned pointer to a string.
libra_error_t libra_preset_ctx_set_runtime ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_RUNTIME value ) ;
/// Set the core requested rotation (`CORE-REQ-ROT`) variable in the context.
///
/// Rotation is represented by quarter rotations around the unit circle.
2024-03-08 11:37:39 +11:00
/// For example. `0` = 0deg, `1` = 90deg, `2` = 180deg, `3` = 270deg, `4` = 0deg.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_core_rotation ( libra_preset_ctx_t * context , uint32_t value ) ;
2024-02-09 18:07:02 +11:00
/// Set the user rotation (`VID-USER-ROT`) variable in the context.
///
/// Rotation is represented by quarter rotations around the unit circle.
2024-03-08 11:37:39 +11:00
/// For example. `0` = 0deg, `1` = 90deg, `2` = 180deg, `3` = 270deg, `4` = 0deg.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_user_rotation ( libra_preset_ctx_t * context , uint32_t value ) ;
2024-02-09 18:07:02 +11:00
/// Set the screen orientation (`SCREEN-ORIENT`) variable in the context.
///
/// Orientation is represented by quarter rotations around the unit circle.
2024-03-08 11:37:39 +11:00
/// For example. `0` = 0deg, `1` = 90deg, `2` = 180deg, `3` = 270deg, `4` = 0deg.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_screen_orientation ( libra_preset_ctx_t * context , uint32_t value ) ;
2024-02-09 18:07:02 +11:00
2024-03-08 11:37:39 +11:00
/// Set whether or not to allow rotation (`VID-ALLOW-CORE-ROT`) variable in the context.
2024-02-09 18:07:02 +11:00
///
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_allow_rotation ( libra_preset_ctx_t * context , bool value ) ;
2024-02-09 18:07:02 +11:00
2024-03-08 11:37:39 +11:00
/// Set the view aspect orientation (`VIEW-ASPECT-ORIENT`) variable in the context.
2024-02-09 18:07:02 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_view_aspect_orientation ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_ORIENTATION value ) ;
2024-02-09 18:07:02 +11:00
2024-03-08 11:37:39 +11:00
/// Set the core aspect orientation (`CORE-ASPECT-ORIENT`) variable in the context.
2024-02-09 18:07:02 +11:00
/// ## Safety
2024-03-08 11:37:39 +11:00
/// - `context` must be null or a valid and aligned pointer to a `libra_preset_ctx_t`.
libra_error_t libra_preset_ctx_set_core_aspect_orientation ( libra_preset_ctx_t * context ,
LIBRA_PRESET_CTX_ORIENTATION value ) ;
2024-02-09 18:07:02 +11:00
2022-12-04 10:32:10 +11:00
# ifdef __cplusplus
2024-08-20 15:44:49 +10:00
} // extern "C"
# endif // __cplusplus
2022-12-04 10:32:10 +11:00
2024-08-20 15:44:49 +10:00
# endif /* __LIBRASHADER_H__ */