alex/librashader
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

capi: document rest of capi

Browse source
This commit is contained in:
chyyran 2023-01-13 18:10:09 -05:00
parent 3e628093ae
commit 2728cff55c
5 changed files with 350 additions and 296 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

475
librashader-capi/librashader.h
View file

@ -11,7 +11,7 @@
#if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11) #if defined(_WIN32) && defined(LIBRA_RUNTIME_D3D11)
#include <d3d11.h> #include <d3d11.h>
#else #else
typedef void ID3D11Device; typedef void ID3D11RenderTargetView; typedef void ID3D1ShaderResourceView; typedef void ID3D11Device;typedef void ID3D11RenderTargetView;typedef void ID3D1ShaderResourceView;
#endif #endif
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
#include <vulkan\vulkan.h> #include <vulkan\vulkan.h>
@ -52,13 +52,15 @@ typedef struct _libra_error _libra_error;
/// parameter metadata. /// parameter metadata.
typedef struct _shader_preset _shader_preset; typedef struct _shader_preset _shader_preset;
typedef struct _libra_error* libra_error_t; /// A handle to a librashader error object.
typedef struct _libra_error *libra_error_t;
typedef struct _shader_preset* libra_shader_preset_t; /// A handle to a shader preset object.
typedef struct _shader_preset *libra_shader_preset_t;
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
/// A GL function loader that librashader needs to be initialized with. /// A GL function loader that librashader needs to be initialized with.
typedef const void* (*libra_gl_loader_t)(const char*); typedef const void *(*libra_gl_loader_t)(const char*);
#endif #endif
/// Options for filter chain creation. /// Options for filter chain creation.
@ -72,7 +74,8 @@ typedef struct filter_chain_gl_opt_t {
} filter_chain_gl_opt_t; } filter_chain_gl_opt_t;
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
typedef struct _filter_chain_gl* libra_gl_filter_chain_t; /// A handle to a OpenGL filter chain.
typedef struct _filter_chain_gl *libra_gl_filter_chain_t;
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
@ -89,7 +92,7 @@ typedef struct libra_source_image_gl_t {
} libra_source_image_gl_t; } libra_source_image_gl_t;
#endif #endif
/// Parameters for the output viewport. /// Defines the output viewport for a rendered frame.
typedef struct libra_viewport_t { typedef struct libra_viewport_t {
float x; float x;
float y; float y;
@ -130,14 +133,15 @@ typedef struct filter_chain_d3d11_opt_t {
} filter_chain_d3d11_opt_t; } filter_chain_d3d11_opt_t;
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
typedef struct _filter_chain_d3d11* libra_d3d11_filter_chain_t; /// A handle to a Direct3D11 filter chain.
typedef struct _filter_chain_d3d11 *libra_d3d11_filter_chain_t;
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
/// OpenGL parameters for the source image. /// OpenGL parameters for the source image.
typedef struct libra_source_image_d3d11_t { typedef struct libra_source_image_d3d11_t {
/// A shader resource view into the source image /// A shader resource view into the source image
const ID3D11ShaderResourceView* handle; const ID3D11ShaderResourceView *handle;
/// The width of the source image. /// The width of the source image.
uint32_t width; uint32_t width;
/// The height of the source image. /// The height of the source image.
@ -179,7 +183,8 @@ typedef struct filter_chain_vk_opt_t {
} filter_chain_vk_opt_t; } filter_chain_vk_opt_t;
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
typedef struct _filter_chain_vk* libra_vk_filter_chain_t; /// A handle to a Vulkan filter chain.
typedef struct _filter_chain_vk *libra_vk_filter_chain_t;
#endif #endif
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
@ -204,315 +209,337 @@ typedef struct FrameOptionsVulkan {
int32_t frame_direction; int32_t frame_direction;
} FrameOptionsVulkan; } FrameOptionsVulkan;
typedef libra_error_t(*PFN_libra_preset_free)(libra_shader_preset_t* preset); /// Function pointer definition for
///libra_preset_free
typedef libra_error_t (*PFN_libra_preset_free)(libra_shader_preset_t *preset);
typedef libra_error_t(*PFN_libra_preset_set_param)(libra_shader_preset_t* preset, /// Function pointer definition for
const char* name, ///libra_preset_set_param
typedef libra_error_t (*PFN_libra_preset_set_param)(libra_shader_preset_t *preset,
const char *name,
float value); float value);
typedef libra_error_t(*PFN_libra_preset_get_param)(libra_shader_preset_t* preset, /// Function pointer definition for
const char* name, ///libra_preset_get_param
float* value); typedef libra_error_t (*PFN_libra_preset_get_param)(libra_shader_preset_t *preset,
const char *name,
float *value);
typedef libra_error_t(*PFN_libra_preset_print)(libra_shader_preset_t* preset); /// Function pointer definition for
///libra_preset_print
typedef libra_error_t (*PFN_libra_preset_print)(libra_shader_preset_t *preset);
typedef libra_error_t(*PFN_libra_preset_get_runtime_param_names)(libra_shader_preset_t* preset, typedef libra_error_t (*PFN_libra_preset_get_runtime_param_names)(libra_shader_preset_t *preset,
const char** value); const char **value);
typedef LIBRA_ERRNO(*PFN_libra_error_errno)(libra_error_t error); typedef LIBRA_ERRNO (*PFN_libra_error_errno)(libra_error_t error);
typedef int32_t(*PFN_libra_error_print)(libra_error_t error); typedef int32_t (*PFN_libra_error_print)(libra_error_t error);
typedef int32_t(*PFN_libra_error_free)(libra_error_t* error); typedef int32_t (*PFN_libra_error_free)(libra_error_t *error);
typedef int32_t(*PFN_libra_error_write)(libra_error_t error, char** out); typedef int32_t (*PFN_libra_error_write)(libra_error_t error, char **out);
typedef int32_t(*PFN_libra_error_free_string)(char** out); typedef int32_t (*PFN_libra_error_free_string)(char **out);
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
typedef libra_error_t(*PFN_libra_gl_init_context)(libra_gl_loader_t loader); /// Function pointer definition for
///libra_gl_init_context
typedef libra_error_t (*PFN_libra_gl_init_context)(libra_gl_loader_t loader);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
typedef libra_error_t(*PFN_libra_gl_filter_chain_create)(libra_shader_preset_t* preset, /// Function pointer definition for
const struct filter_chain_gl_opt_t* options, ///libra_gl_filter_chain_create
libra_gl_filter_chain_t* out); typedef libra_error_t (*PFN_libra_gl_filter_chain_create)(libra_shader_preset_t *preset,
const struct filter_chain_gl_opt_t *options,
libra_gl_filter_chain_t *out);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
typedef libra_error_t(*PFN_libra_gl_filter_chain_frame)(libra_gl_filter_chain_t* chain, /// Function pointer definition for
///libra_gl_filter_chain_frame
typedef libra_error_t (*PFN_libra_gl_filter_chain_frame)(libra_gl_filter_chain_t *chain,
size_t frame_count, size_t frame_count,
struct libra_source_image_gl_t image, struct libra_source_image_gl_t image,
struct libra_viewport_t viewport, struct libra_viewport_t viewport,
struct libra_draw_framebuffer_gl_t out, struct libra_draw_framebuffer_gl_t out,
const float* mvp, const float *mvp,
const struct frame_gl_opt_t* opt); const struct frame_gl_opt_t *opt);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
typedef libra_error_t(*PFN_libra_gl_filter_chain_free)(libra_gl_filter_chain_t* chain); /// Function pointer definition for
///libra_gl_filter_chain_free
typedef libra_error_t (*PFN_libra_gl_filter_chain_free)(libra_gl_filter_chain_t *chain);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
typedef libra_error_t(*PFN_libra_d3d11_filter_chain_create)(libra_shader_preset_t* preset, /// Function pointer definition for
const struct filter_chain_d3d11_opt_t* options, ///libra_d3d11_filter_chain_create
const ID3D11Device* device, typedef libra_error_t (*PFN_libra_d3d11_filter_chain_create)(libra_shader_preset_t *preset,
libra_d3d11_filter_chain_t* out); const struct filter_chain_d3d11_opt_t *options,
const ID3D11Device *device,
libra_d3d11_filter_chain_t *out);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
typedef libra_error_t(*PFN_libra_d3d11_filter_chain_frame)(libra_d3d11_filter_chain_t* chain, /// Function pointer definition for
///libra_d3d11_filter_chain_frame
typedef libra_error_t (*PFN_libra_d3d11_filter_chain_frame)(libra_d3d11_filter_chain_t *chain,
size_t frame_count, size_t frame_count,
struct libra_source_image_d3d11_t image, struct libra_source_image_d3d11_t image,
struct libra_viewport_t viewport, struct libra_viewport_t viewport,
const ID3D11RenderTargetView* out, const ID3D11RenderTargetView *out,
const float* mvp, const float *mvp,
const struct frame_vk_opt_t* opt); const struct frame_vk_opt_t *opt);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
typedef libra_error_t(*PFN_libra_d3d11_filter_chain_free)(libra_d3d11_filter_chain_t* chain); /// Function pointer definition for
///libra_d3d11_filter_chain_free
typedef libra_error_t (*PFN_libra_d3d11_filter_chain_free)(libra_d3d11_filter_chain_t *chain);
#endif #endif
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif // __cplusplus #endif // __cplusplus
/// Get the error code corresponding to this error object. /// Get the error code corresponding to this error object.
/// ///
/// ## Safety /// ## Safety
/// - `error` must be valid and initialized. /// - `error` must be valid and initialized.
LIBRA_ERRNO libra_error_errno(libra_error_t error); LIBRA_ERRNO libra_error_errno(libra_error_t error);
/// Print the error message. /// Print the error message.
/// ///
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0. /// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
/// ## Safety /// ## Safety
/// - `error` must be a valid and initialized instance of `libra_error_t`. /// - `error` must be a valid and initialized instance of `libra_error_t`.
int32_t libra_error_print(libra_error_t error); int32_t libra_error_print(libra_error_t error);
/// Frees any internal state kept by the error. /// Frees any internal state kept by the error.
/// ///
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0. /// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
/// The resulting error object becomes null. /// The resulting error object becomes null.
/// ## Safety /// ## Safety
/// - `error` must be null or a pointer to a valid and initialized instance of `libra_error_t`. /// - `error` must be null or a pointer to a valid and initialized instance of `libra_error_t`.
int32_t libra_error_free(libra_error_t* error); int32_t libra_error_free(libra_error_t *error);
/// Writes the error message into `out` /// Writes the error message into `out`
/// ///
/// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0. /// If `error` is null, this function does nothing and returns 1. Otherwise, this function returns 0.
/// ## Safety /// ## Safety
/// - `error` must be a valid and initialized instance of `libra_error_t`. /// - `error` must be a valid and initialized instance of `libra_error_t`.
/// - `out` must be a non-null pointer. The resulting string must not be modified. /// - `out` must be a non-null pointer. The resulting string must not be modified.
int32_t libra_error_write(libra_error_t error, int32_t libra_error_write(libra_error_t error,
char** out); char **out);
/// Frees an error string previously allocated by `libra_error_write`. /// Frees an error string previously allocated by `libra_error_write`.
/// ///
/// After freeing, the pointer will be set to null. /// After freeing, the pointer will be set to null.
/// ## Safety /// ## Safety
/// - If `libra_error_write` is not null, it must point to a string previously returned by `libra_error_write`. /// - If `libra_error_write` is not null, it must point to a string previously returned by `libra_error_write`.
/// Attempting to free anything else, including strings or objects from other librashader functions, is immediate /// Attempting to free anything else, including strings or objects from other librashader functions, is immediate
/// Undefined Behaviour. /// Undefined Behaviour.
int32_t libra_error_free_string(char** out); int32_t libra_error_free_string(char **out);
/// Load a preset. /// Load a preset.
/// ///
/// ## Safety /// ## Safety
/// - `filename` must be either null or a valid, aligned pointer to a string path to the shader preset. /// - `filename` must be either null or a valid, aligned pointer to a string path to the shader preset.
/// - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_shader_preset_t`. /// - `out` must be either null, or an aligned pointer to an uninitialized or invalid `libra_shader_preset_t`.
/// ## Returns /// ## Returns
/// - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`. /// - If any parameters are null, `out` is unchanged, and this function returns `LIBRA_ERR_INVALID_PARAMETER`.
libra_error_t libra_preset_create(const char* filename, libra_error_t libra_preset_create(const char *filename,
libra_shader_preset_t* out); libra_shader_preset_t *out);
/// Free the preset. /// Free the preset.
/// ///
/// If `preset` is null, this function does nothing. The resulting value in `preset` then becomes /// If `preset` is null, this function does nothing. The resulting value in `preset` then becomes
/// null. /// null.
/// ///
/// ## Safety /// ## Safety
/// - `preset` must be a valid and aligned pointer to a shader preset. /// - `preset` must be a valid and aligned pointer to a shader preset.
libra_error_t libra_preset_free(libra_shader_preset_t* preset); libra_error_t libra_preset_free(libra_shader_preset_t *preset);
/// Set the value of the parameter in the preset. /// Set the value of the parameter in the preset.
/// ///
/// ## Safety /// ## Safety
/// - `preset` must be null or a valid and aligned pointer to a shader preset. /// - `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. /// - `name` must be null or a valid and aligned pointer to a string.
libra_error_t libra_preset_set_param(libra_shader_preset_t* preset, const char* name, float value); libra_error_t libra_preset_set_param(libra_shader_preset_t *preset, const char *name, float value);
/// Get the value of the parameter as set in the preset. /// Get the value of the parameter as set in the preset.
/// ///
/// ## Safety /// ## Safety
/// - `preset` must be null or a valid and aligned pointer to a shader preset. /// - `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. /// - `name` must be null or a valid and aligned pointer to a string.
/// - `value` may be a pointer to a uninitialized `float`. /// - `value` may be a pointer to a uninitialized `float`.
libra_error_t libra_preset_get_param(libra_shader_preset_t* preset, const char* name, float* value); libra_error_t libra_preset_get_param(libra_shader_preset_t *preset, const char *name, float *value);
/// Pretty print the shader preset. /// Pretty print the shader preset.
/// ///
/// ## Safety /// ## Safety
/// - `preset` must be null or a valid and aligned pointer to a shader preset. /// - `preset` must be null or a valid and aligned pointer to a shader preset.
libra_error_t libra_preset_print(libra_shader_preset_t* preset); libra_error_t libra_preset_print(libra_shader_preset_t *preset);
/// Get a list of runtime parameter names. /// Get a list of runtime parameter names.
/// ///
/// The returned value can not currently be freed. /// The returned value can not currently be freed.
/// This function should be considered in progress. Its use is discouraged. /// This function should be considered in progress. Its use is discouraged.
libra_error_t libra_preset_get_runtime_param_names(libra_shader_preset_t* preset, libra_error_t libra_preset_get_runtime_param_names(libra_shader_preset_t *preset,
const char** value); const char **value);
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
/// Initialize the OpenGL Context for librashader. /// Initialize the OpenGL Context for librashader.
/// ///
/// ## Safety /// ## Safety
/// Attempting to create a filter chain will fail. /// Attempting to create a filter chain will fail.
/// ///
/// Reinitializing the OpenGL context with a different loader immediately invalidates previous filter /// Reinitializing the OpenGL context with a different loader immediately invalidates previous filter
/// chain objects, and drawing with them causes immediate undefined behaviour. /// chain objects, and drawing with them causes immediate undefined behaviour.
libra_error_t libra_gl_init_context(libra_gl_loader_t loader); libra_error_t libra_gl_init_context(libra_gl_loader_t loader);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
/// Create the filter chain given the shader preset. /// Create the filter chain given the shader preset.
/// ///
/// The shader preset is immediately invalidated and must be recreated after /// The shader preset is immediately invalidated and must be recreated after
/// the filter chain is created. /// the filter chain is created.
/// ///
/// ## Safety: /// ## Safety:
/// - `preset` must be either null, or valid and aligned. /// - `preset` must be either null, or valid and aligned.
/// - `options` 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. /// - `out` must be aligned, but may be null, invalid, or uninitialized.
libra_error_t libra_gl_filter_chain_create(libra_shader_preset_t* preset, libra_error_t libra_gl_filter_chain_create(libra_shader_preset_t *preset,
const struct filter_chain_gl_opt_t* options, const struct filter_chain_gl_opt_t *options,
libra_gl_filter_chain_t* out); libra_gl_filter_chain_t *out);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
/// Draw a frame with the given parameters for the given filter chain. /// Draw a frame with the given parameters for the given filter chain.
/// ///
/// ## Safety /// ## Safety
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this /// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
/// function will return an error. /// function will return an error.
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float` /// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
/// values for the model view projection matrix. /// values for the model view projection matrix.
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t` /// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
/// struct. /// struct.
libra_error_t libra_gl_filter_chain_frame(libra_gl_filter_chain_t* chain, libra_error_t libra_gl_filter_chain_frame(libra_gl_filter_chain_t *chain,
size_t frame_count, size_t frame_count,
struct libra_source_image_gl_t image, struct libra_source_image_gl_t image,
struct libra_viewport_t viewport, struct libra_viewport_t viewport,
struct libra_draw_framebuffer_gl_t out, struct libra_draw_framebuffer_gl_t out,
const float* mvp, const float *mvp,
const struct frame_gl_opt_t* opt); const struct frame_gl_opt_t *opt);
#endif #endif
#if defined(LIBRA_RUNTIME_OPENGL) #if defined(LIBRA_RUNTIME_OPENGL)
/// Free a GL filter chain. /// Free a GL filter chain.
/// ///
/// The resulting value in `chain` then becomes null. /// The resulting value in `chain` then becomes null.
/// ## Safety /// ## Safety
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`. /// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
libra_error_t libra_gl_filter_chain_free(libra_gl_filter_chain_t* chain); libra_error_t libra_gl_filter_chain_free(libra_gl_filter_chain_t *chain);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
/// Create the filter chain given the shader preset. /// Create the filter chain given the shader preset.
/// ///
/// The shader preset is immediately invalidated and must be recreated after /// The shader preset is immediately invalidated and must be recreated after
/// the filter chain is created. /// the filter chain is created.
/// ///
/// ## Safety: /// ## Safety:
/// - `preset` must be either null, or valid and aligned. /// - `preset` must be either null, or valid and aligned.
/// - `options` 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. /// - `out` must be aligned, but may be null, invalid, or uninitialized.
libra_error_t libra_d3d11_filter_chain_create(libra_shader_preset_t* preset, libra_error_t libra_d3d11_filter_chain_create(libra_shader_preset_t *preset,
const struct filter_chain_d3d11_opt_t* options, const struct filter_chain_d3d11_opt_t *options,
const ID3D11Device* device, const ID3D11Device *device,
libra_d3d11_filter_chain_t* out); libra_d3d11_filter_chain_t *out);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
/// Draw a frame with the given parameters for the given filter chain. /// Draw a frame with the given parameters for the given filter chain.
/// ///
/// ## Safety /// ## Safety
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this /// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
/// function will return an error. /// function will return an error.
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float` /// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
/// values for the model view projection matrix. /// values for the model view projection matrix.
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t` /// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
/// struct. /// struct.
libra_error_t libra_d3d11_filter_chain_frame(libra_d3d11_filter_chain_t* chain, libra_error_t libra_d3d11_filter_chain_frame(libra_d3d11_filter_chain_t *chain,
size_t frame_count, size_t frame_count,
struct libra_source_image_d3d11_t image, struct libra_source_image_d3d11_t image,
struct libra_viewport_t viewport, struct libra_viewport_t viewport,
const ID3D11RenderTargetView* out, const ID3D11RenderTargetView *out,
const float* mvp, const float *mvp,
const struct frame_vk_opt_t* opt); const struct frame_vk_opt_t *opt);
#endif #endif
#if defined(LIBRA_RUNTIME_D3D11) #if defined(LIBRA_RUNTIME_D3D11)
/// Free a D3D11 filter chain. /// Free a D3D11 filter chain.
/// ///
/// The resulting value in `chain` then becomes null. /// The resulting value in `chain` then becomes null.
/// ## Safety /// ## Safety
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`. /// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_d3d11_filter_chain_t`.
libra_error_t libra_d3d11_filter_chain_free(libra_d3d11_filter_chain_t* chain); libra_error_t libra_d3d11_filter_chain_free(libra_d3d11_filter_chain_t *chain);
#endif #endif
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
/// Create the filter chain given the shader preset. /// Create the filter chain given the shader preset.
/// ///
/// The shader preset is immediately invalidated and must be recreated after /// The shader preset is immediately invalidated and must be recreated after
/// the filter chain is created. /// the filter chain is created.
/// ///
/// ## Safety: /// ## Safety:
/// - The handles provided in `vulkan` must be valid for the command buffers that /// - The handles provided in `vulkan` must be valid for the command buffers that
/// `libra_vk_filter_chain_frame` will write to. Namely, the VkDevice must have been /// `libra_vk_filter_chain_frame` will write to. Namely, the VkDevice must have been
/// created with the `VK_KHR_dynamic_rendering` extension. /// created with the `VK_KHR_dynamic_rendering` extension.
/// - `preset` must be either null, or valid and aligned. /// - `preset` must be either null, or valid and aligned.
/// - `options` 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. /// - `out` must be aligned, but may be null, invalid, or uninitialized.
libra_error_t libra_vk_filter_chain_create(struct libra_device_vk_t vulkan, libra_error_t libra_vk_filter_chain_create(struct libra_device_vk_t vulkan,
libra_shader_preset_t* preset, libra_shader_preset_t *preset,
const struct filter_chain_vk_opt_t* options, const struct filter_chain_vk_opt_t *options,
libra_vk_filter_chain_t* out); libra_vk_filter_chain_t *out);
#endif #endif
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
/// Records rendering commands for a frame with the given parameters for the given filter chain /// Records rendering commands for a frame with the given parameters for the given filter chain
/// to the input command buffer. /// to the input command buffer.
/// ///
/// librashader will not do any queue submissions. /// librashader will not do any queue submissions.
/// ///
/// ## Safety /// ## Safety
/// - `libra_vk_filter_chain_frame` **must not be called within a RenderPass**. /// - `libra_vk_filter_chain_frame` **must not be called within a RenderPass**.
/// - `command_buffer` must be a valid handle to a `VkCommandBuffer` that is ready for recording. /// - `command_buffer` must be a valid handle to a `VkCommandBuffer` that is ready for recording.
/// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this /// - `chain` may be null, invalid, but not uninitialized. If `chain` is null or invalid, this
/// function will return an error. /// function will return an error.
/// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float` /// - `mvp` may be null, or if it is not null, must be an aligned pointer to 16 consecutive `float`
/// values for the model view projection matrix. /// values for the model view projection matrix.
/// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t` /// - `opt` may be null, or if it is not null, must be an aligned pointer to a valid `frame_gl_opt_t`
/// struct. /// struct.
libra_error_t libra_vk_filter_chain_frame(libra_vk_filter_chain_t* chain, libra_error_t libra_vk_filter_chain_frame(libra_vk_filter_chain_t *chain,
VkCommandBuffer command_buffer, VkCommandBuffer command_buffer,
size_t frame_count, size_t frame_count,
struct libra_image_vk_t image, struct libra_image_vk_t image,
struct libra_viewport_t viewport, struct libra_viewport_t viewport,
struct libra_image_vk_t out, struct libra_image_vk_t out,
const float* mvp, const float *mvp,
const struct FrameOptionsVulkan* opt); const struct FrameOptionsVulkan *opt);
#endif #endif
#if defined(LIBRA_RUNTIME_VULKAN) #if defined(LIBRA_RUNTIME_VULKAN)
/// Free a GL filter chain. /// Free a GL filter chain.
/// ///
/// The resulting value in `chain` then becomes null. /// The resulting value in `chain` then becomes null.
/// ## Safety /// ## Safety
/// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`. /// - `chain` must be either null or a valid and aligned pointer to an initialized `libra_gl_filter_chain_t`.
libra_error_t libra_vk_filter_chain_free(libra_vk_filter_chain_t* chain); libra_error_t libra_vk_filter_chain_free(libra_vk_filter_chain_t *chain);
#endif #endif
#ifdef __cplusplus #ifdef __cplusplus

12
librashader-capi/src/ctypes.rs
View file

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

5
librashader-capi/src/error.rs
View file

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

20
librashader-capi/src/ffi.rs
View file

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

4
librashader-capi/src/presets.rs
View file

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