From 72c72dafa001f40855af0d48e46934817bc2a171 Mon Sep 17 00:00:00 2001 From: chyyran Date: Thu, 3 Oct 2024 00:16:34 -0400 Subject: [PATCH] capi(d3d12): remove unintentional IMAGE_TYPE infix for LIBRA_D3D12_IMAGE_TYPE --- MIGRATION-ABI2.md | 8 ++-- include/librashader.h | 48 +++++++++++++------ .../src/runtime/d3d12/filter_chain.rs | 20 ++++---- 3 files changed, 48 insertions(+), 28 deletions(-) diff --git a/MIGRATION-ABI2.md b/MIGRATION-ABI2.md index 6620896..761ca4c 100644 --- a/MIGRATION-ABI2.md +++ b/MIGRATION-ABI2.md @@ -73,11 +73,11 @@ The following changes are applicable if `LIBRA_RUNTIME_D3D12` is defined. * The fields `width` and `height` have been added to `libra_output_image_d3d12_t`. * You should now pass what was previously `.width` and `.height` of `libra_viewport_t` to these new fields in `libra_output_image_d3d12_t`. * The `image` parameter of `libra_d3d12_filter_chain_frame` has changed from `libra_source_image_d3d12_t` to `libra_image_d3d12_t`. - * To maintain the previous behaviour, `.image_type` of the `libra_image_d3d12_t` should be set to `IMAGE_TYPE_SOURCE_IMAGE`, and `.handle.source` should be the `libra_source_image_d3d12_t`struct. + * To maintain the previous behaviour, `.image_type` of the `libra_image_d3d12_t` should be set to `LIBRA_D3D12_IMAGE_TYPE_SOURCE_IMAGE`, and `.handle.source` should be the `libra_source_image_d3d12_t`struct. * The `out` parameter of `libra_d3d12_filter_chain_frame` has changed from `libra_output_image_d3d11_t` to `libra_image_d3d12_t`. - * To maintain the previous behaviour, `.image_type` of the `libra_image_d3d12_t` should be set to `IMAGE_TYPE_OUTPUT_IMAGE`, and `.handle.output` should be the `libra_output_image_d3d12_t`struct. -* Any `libra_image_d3d12_t` can now optionally pass only the `ID3D12Resource *` for the texture by setting `.image_type` to `IMAGE_TYPE_RESOURCE` and setting `.handle.resource` to the resource pointer. - * If using `IMAGE_TYPE_RESOURCE`, shader resource view and render target view descriptors for the input and output images will be internally allocated by the filter chain. This may result in marginally worse performance. + * To maintain the previous behaviour, `.image_type` of the `libra_image_d3d12_t` should be set to `LIBRA_D3D12_IMAGE_TYPE_OUTPUT_IMAGE`, and `.handle.output` should be the `libra_output_image_d3d12_t`struct. +* Any `libra_image_d3d12_t` can now optionally pass only the `ID3D12Resource *` for the texture by setting `.image_type` to `LIBRA_D3D12_IMAGE_TYPE_RESOURCE` and setting `.handle.resource` to the resource pointer. + * If using `LIBRA_D3D12_IMAGE_TYPE_RESOURCE`, shader resource view and render target view descriptors for the input and output images will be internally allocated by the filter chain. This may result in marginally worse performance. * In `libra_d3d12_filter_chain_frame`, the position of the `viewport` parameter has moved to after the `out` parameter, and its type has changed from `libra_viewport_t` to `libra_viewport_t *`, which is allowed to be `NULL`. See [`libra_viewport_t` changes](#libra_viewport_t-changes) for more details. * The `chain` parameter of `libra_d3d12_filter_chain_get_param` has been made `const`. diff --git a/include/librashader.h b/include/librashader.h index 207f224..b2bbbbc 100644 --- a/include/librashader.h +++ b/include/librashader.h @@ -53,20 +53,27 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. #if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12)) /// The type of image passed to the image. -typedef enum LIBRA_D3D12_IMAGE_TYPE { +enum LIBRA_D3D12_IMAGE_TYPE +#ifdef __cplusplus + : int32_t +#endif // __cplusplus + { #if (defined(_WIN32) && defined(LIBRA_RUNTIME_D3D12)) /// The image handle is a pointer to a `ID3D12Resource`. - LIBRA_D3D12_IMAGE_TYPE_IMAGE_TYPE_RESOURCE = 0, + LIBRA_D3D12_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, + LIBRA_D3D12_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, + LIBRA_D3D12_IMAGE_TYPE_OUTPUT_IMAGE = 2, #endif -} LIBRA_D3D12_IMAGE_TYPE; +}; +#ifndef __cplusplus +typedef int32_t LIBRA_D3D12_IMAGE_TYPE; +#endif // __cplusplus #endif /// Error codes for librashader error types. @@ -493,9 +500,9 @@ typedef union libra_image_d3d12_handle_t { /// 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; + LIBRA_D3D12_IMAGE_TYPE image_type; /// The handle to the image. - union libra_image_d3d12_handle_t image; + union libra_image_d3d12_handle_t handle; } libra_image_d3d12_t; #endif @@ -1786,18 +1793,26 @@ libra_error_t libra_d3d12_filter_chain_create_deferred(libra_shader_preset_t *pr /// remain in `D3D12_RESOURCE_STATE_RENDER_TARGET` after all shader passes. The caller must transition /// the output image to the final resource state. /// +/// The refcount of any COM pointers passed into this frame will not be changed. It is the responsibility +/// of the caller to ensure any resources remain alive until the `ID3D12GraphicsCommandList` provided is +/// submitted. +/// /// ## 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 +/// - `image` is a `libra_image_d3d12_t` with `image_type` set to `IMAGE_TYPE_SOURCE_IMAGE` or `IMAGE_TYPE_RESOURCE`, +/// with `image_handle` either a `ID3D12Resource*` or an `libra_source_image_d3d12_t` containing a CPU descriptor to a shader resource view, +/// and the image resource the view is of, which will serve as the source image for the frame. +/// The input image resource must be in the `D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE` resource state +/// or equivalent barrier layout. The image resource must have dimension `D3D12_RESOURCE_DIMENSION_TEXTURE2D`. +/// - `out` is a `libra_image_d3d12_t`, with `image_type` set to `IMAGE_TYPE_OUTPUT_IMAGE` or `IMAGE_TYPE_RESOURCE`, +/// with `image_handle` being either a `ID3D12Resource*` or an `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. +/// The image resource must have dimension `D3D12_RESOURCE_DIMENSION_TEXTURE2D`. /// /// - `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 @@ -1814,10 +1829,15 @@ libra_error_t libra_d3d12_filter_chain_create_deferred(libra_shader_preset_t *pr /// 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_d3d12_opt_t` /// struct. -/// - `out` must be a descriptor handle to a render target view. -/// - `image.resource` must not be null. +/// - Any resource pointers contained within a `libra_image_d3d12_t` must be non-null. +/// - The `handle` field of any `libra_image_d3d12_t` must be valid for it's `image_type`. +/// - If `image_type` is `IMAGE_TYPE_RESOURCE`, then `handle` must be `ID3D12Resource *`. +/// - If `image_type` is `IMAGE_TYPE_SOURCE`, then `handle` must be `libra_source_image_d3d12_t`. +/// - If `image_type` is `IMAGE_TYPE_OUTPUT`, then `handle` must be `libra_output_image_d3d12_t`. /// - `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. +/// - All resource pointers contained within a `libra_image_d3d12_t` must remain valid until the `ID3D12GraphicsCommandList *` +/// provided is submitted after the call to this function. /// - 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_d3d12_filter_chain_frame(libra_d3d12_filter_chain_t *chain, diff --git a/librashader-capi/src/runtime/d3d12/filter_chain.rs b/librashader-capi/src/runtime/d3d12/filter_chain.rs index 5ca7d3f..d276bb2 100644 --- a/librashader-capi/src/runtime/d3d12/filter_chain.rs +++ b/librashader-capi/src/runtime/d3d12/filter_chain.rs @@ -43,14 +43,14 @@ pub union libra_image_d3d12_handle_t { } /// The type of image passed to the image. -#[repr(C)] +#[repr(i32)] pub enum LIBRA_D3D12_IMAGE_TYPE { /// The image handle is a pointer to a `ID3D12Resource`. - IMAGE_TYPE_RESOURCE = 0, + RESOURCE = 0, /// The image handle is a `libra_source_image_d3d12_t` - IMAGE_TYPE_SOURCE_IMAGE = 1, + SOURCE_IMAGE = 1, /// The image handle is a `libra_output_image_d3d12_t` - IMAGE_TYPE_OUTPUT_IMAGE = 2, + OUTPUT_IMAGE = 2, } /// Direct3D 12 parameters for the source image. @@ -308,14 +308,14 @@ extern_fn! { let output = unsafe { match out.image_type { - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_RESOURCE => { + LIBRA_D3D12_IMAGE_TYPE::RESOURCE => { let out = out.handle.resource; D3D12OutputView::new_from_resource( out, chain, )? } - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_OUTPUT_IMAGE => { + LIBRA_D3D12_IMAGE_TYPE::OUTPUT_IMAGE => { let out = out.handle.output; D3D12OutputView::new_from_raw( out.descriptor, @@ -323,7 +323,7 @@ extern_fn! { out.format, ) } - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_SOURCE_IMAGE => { + LIBRA_D3D12_IMAGE_TYPE::SOURCE_IMAGE => { return Err(LibrashaderError::InvalidParameter("out")) } } @@ -347,18 +347,18 @@ extern_fn! { let image = unsafe { match image.image_type { - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_RESOURCE => { + LIBRA_D3D12_IMAGE_TYPE::RESOURCE => { let image = image.handle.resource; D3D12InputImage::Managed(image) } - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_SOURCE_IMAGE => { + LIBRA_D3D12_IMAGE_TYPE::SOURCE_IMAGE => { let image = ManuallyDrop::into_inner(image.handle.source); D3D12InputImage::External { resource: image.resource, descriptor: image.descriptor, } } - LIBRA_D3D12_IMAGE_TYPE::IMAGE_TYPE_OUTPUT_IMAGE => { + LIBRA_D3D12_IMAGE_TYPE::OUTPUT_IMAGE => { return Err(LibrashaderError::InvalidParameter("image")) } }