librashader 0.5.1

Version 0.5.1 has the canonical C ABI version 2, and API version 1.

0.5.1 is mostly a bug and docfix release to enable packaging on Debian 12 via rustc-web, as well as improving shader compatibility with the WGSL backend used in wgpu.

The 0.5.x series of releases is the first series of librashader releases since 0.1.0 with a bump in ABI version, and is thus ABI-incompatible with versions of librashader prior to 0.5.0. Trying to load this version of librashader if the application only supports ABI 1 will fail.

• If you are an end-user, please use librashader 0.4.5 until the developer has updated their application.
• If you are a developer, see MIGRATION-ABI2.md on how to update your application to support librashader ABI 2.
• If you are a package maintainer, you may want to postpone packaging librashader 0.5.1 until relevant applications have been updated. Note that the SONAME for librashader 0.5.0 and above should be librashader.so.2.

ABI 2 cleans up some inconsistencies across runtimes and makes viewport handling much easier and well defined.

Notable Changes

• 2fe66d9 reflect: order variables after type definitions in the link step to improve WGSL compatibility
• 562e1e5 doc: bump msrv to 1.78

Notable Changes from 0.5.0

• #129 cli: add a librashader-cli to interact with shader presets and source code.
  • See CLI.md for more details and usage notes
• presets: introduce the concept of a "shader pack", which is a JSON-serializable format for packaging a shader preset into a single file.
  • A preset pack includes all required textures and preprocessed shader source files. This is a prerequisite for running librashader on environments without filesystems such as the web.
  • All runtimes support loading from a ShaderPresetPack, which implements Serialize/Deserialize with the serde crate feature.
  • Preset packs can be created with the librashader-cli pack command, but this format should not yet be considered stable.
  • There are no plans for a C API that works with preset packs directly.
• aeb0a16 vulkan: allow specifying the graphics queue to use
• OpenGL changes and improvements
  • 1bdadaa opengl: port OpenGL runtime to glow.
    • glow is a platform abstraction layer for OpenGL and is a step towards allowing librashader to run on WebGL.
  • 41353ac opengl: remove need for externally managed FBO for the output image
  • e7fe965 opengl: always ensure framebuffers are bound before rendering
• #102 Major ABI breaking changes to the C API
  • 1e33b4c capi: make viewport optional and default to a viewport that spans the entire texture
  • 61fdaee capi(opengl): take libra_gl_loader_t in filter chain constructor
  • f18c22a capi(d3d11): take ID3D11ShaderResourceView* directly
  • 7a13136 capi(d3d12): allow passing ID3D12Resource* directly without needing an externally allocated CPU descriptor
• Direct3D performance optimizations and fixes
  • b0df631 d3d9: load LUTs with BGRA8 ordering rather than ARGB8
  • dbfa822 d3d9: disable alpha blending
  • 7d483f2 d3d9: take viewport IDirect3DSurface9 by reference to avoid AddRef/Release
  • 2fe7702 d3d11: avoid QueryInterface when getting the dimensions of a texture
  • 7b7fd99 d3d11: take viewport ID3D11RenderTargetView by reference to avoid AddRef/Release
  • 3c20c83 d3d12: take D3D12InputImage without changing the refcount
  • 7a13136 d3d12: allow the filter chain to optionally manage input/output descriptors
  • c57e502 d3d12: reduce unnecessary refcount increment/decrement for resources that last the lifetime of the filter chain

librashader 0.5.0

Version 0.5.0 has the canonical C ABI version 2, and API version 1.

This is the first release since 0.1.0 with a bump in ABI version, and is thus ABI-incompatible with versions of librashader prior to 0.5.0. Trying to load this version of librashader if the application only supports ABI 1 will fail.

• If you are an end-user, please use librashader 0.4.5 until the developer has updated their application.
• If you are a developer, see MIGRATION-ABI2.md on how to update your application to support librashader ABI 2.
• If you are a package maintainer, you may want to postpone packaging librashader 0.5.0 until relevant applications have been updated. Note that the SONAME for librashader 0.5.0 and above should be librashader.so.2.

ABI 2 cleans up some inconsistencies across runtimes and makes viewport handling much easier and well defined.

Notable Changes

• #129 cli: add a librashader-cli to interact with shader presets and source code.
  • See CLI.md for more details and usage notes
• presets: introduce the concept of a "shader pack", which is a JSON-serializable format for packaging a shader preset into a single file.
  • A preset pack includes all required textures and preprocessed shader source files. This is a prerequisite for running librashader on environments without filesystems such as the web.
  • All runtimes support loading from a ShaderPresetPack, which implements Serialize/Deserialize with the serde crate feature.
  • Preset packs can be created with the librashader-cli pack command, but this format should not yet be considered stable.
  • There are no plans for a C API that works with preset packs directly.
• aeb0a16 vulkan: allow specifying the graphics queue to use
• OpenGL changes and improvements
  • 1bdadaa opengl: port OpenGL runtime to glow.
    • glow is a platform abstraction layer for OpenGL and is a step towards allowing librashader to run on WebGL.
  • 41353ac opengl: remove need for externally managed FBO for the output image
  • e7fe965 opengl: always ensure framebuffers are bound before rendering
• #102 Major ABI breaking changes to the C API
  • 1e33b4c capi: make viewport optional and default to a viewport that spans the entire texture
  • 61fdaee capi(opengl): take libra_gl_loader_t in filter chain constructor
  • f18c22a capi(d3d11): take ID3D11ShaderResourceView* directly
  • 7a13136 capi(d3d12): allow passing ID3D12Resource* directly without needing an externally allocated CPU descriptor
• Direct3D performance optimizations and fixes
  • b0df631 d3d9: load LUTs with BGRA8 ordering rather than ARGB8
  • dbfa822 d3d9: disable alpha blending
  • 7d483f2 d3d9: take viewport IDirect3DSurface9 by reference to avoid AddRef/Release
  • 2fe7702 d3d11: avoid QueryInterface when getting the dimensions of a texture
  • 7b7fd99 d3d11: take viewport ID3D11RenderTargetView by reference to avoid AddRef/Release
  • 3c20c83 d3d12: take D3D12InputImage without changing the refcount
  • 7a13136 d3d12: allow the filter chain to optionally manage input/output descriptors
  • c57e502 d3d12: reduce unnecessary refcount increment/decrement for resources that last the lifetime of the filter chain

librashader 0.4.5

Version 0.4.5 has the canonical C ABI version 1, and API version 1.

This will likely be the final release supporting C ABI 1. This is mostly a bugfix release to squash remaining bugs before ABI 2 releases as 0.5.0.

Version 0.4.4 was skipped due to a release configuration error.

Notable Changes

• 57f2dab reflect: fixes handling of the CurrentSubFrame uniform
• 81840a9 reflect: fix #pragma name by inserting shader names as pass aliases.
• cbe6510 preprocess: allow step parameter in #pragma parameter to be optional as per the slang shader spec
• d6f8950 runtimes: only draw the final pass as feedback if used as feedback by the filter chain.

ABI Changes Incoming

The next release in the 0.5.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI.

See #102 for more details.

librashader 0.4.3

Version 0.4.3 has the canonical C ABI version 1, and API version 1.

This is a maintenance release to allow building on stable Rust with caveats noted in the README.

Notable Changes

• #120, #121 build: replaced let_chains and try_blocks with equivalents on stable Rust
• #122 build: allow using trait objects for CompileReflectShader instead of impl Trait
  • This comes with small performance penalty when compiling shaders due to additional indirection required.

Note that C headers will only be generated when running librashader-build-script on nightly Rust. Builds on stable Rust should use the pre-generated headers in the include folder.

ABI Changes Incoming

The next release in the 0.5.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI.

See #102 for more details.

librashader 0.4.2

Version 0.4.2 has the canonical C ABI version 1, and API version 1.

This is a bugfix release to address a long standing issue with PassFeedback0, Metal runtime improvements, and an accidental violation of librashader's C versioning guarantees in an edge case.

Notable Changes

• #117 Runtimes: draw PassFeedback0 to internal feedback buffers

  • This makes shader presets relying on PassFeedback0 display properly. Previously as librashader only drew the final pass to the supplied output texture, the final pass would never be available for feedback. This did not seem to be an issue on most shaders, except those that only have one pass and rely on PassFeedback0. We now draw the final pass twice, once to the internal buffers, and again to the output texture. In the future, this may be reduced to a blit from the internal buffer to the output.

• 22b2118 Metal: don't resize internal buffers if unneeded.

  • This fixes a long-standing bug with the Metal runtime where history and feedback buffers would always be cleared each frame, breaking some shader presets.

• 98d8d91 capi: Undo const qualification of chain in _filter_chain_get_param and _filter_chain_get_active_pass_count

  • While the include headers were not changed, const qualifying the parameters caused the output of librashader-build-script to require code changes without an ABI bump. This was unintended and only affected packagers using the output of librashader-build-script rather than the included headers, but such changes should not be made without a bump in ABI version. This will be postponed to 0.5.x as per the versioning policy.

ABI Changes Incoming

The next release in the 0.5.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI.

See #102 for more details.

librashader 0.4.1

Version 0.4.1 has the canonical C ABI version 1, and API version 1.

This is a bugfix release to address an issue with glShaderSource reading invalid characters for the shader.

Notable Changes

• 075a298 gl: fix glShaderSource reading past the string buffer.

ABI Changes Incoming

The next release in the 0.5.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI.

See #102 for more details.

librashader 0.4.0

Version 0.4.0 has the canonical C ABI version 1, and API version 1.

⚠️ The ABI changes previously announced in the release notes for the 0.3.x series have been pushed back to 0.5.0. This is only a Rust-semver breaking release. ⚠️

This is a buffered release mainly intended to deprecate librashader-spirv-cross while addressing the concerns raised in #111. Alongside it brings some bugfixes and semver-incompatible performance optimizations, mostly affecting the preset, preprocess, and reflect APIs.

If you only consume the runtime API, the only change that will affect you are changes to the FilterChainParameters trait.

C API consumers do not need to update their headers. This release is not C API-breaking.

Notable Changes

• c3033cf reflect: port SPIRV-Cross usage to spirv-cross2
  • It is very clear that librashader-spirv-cross is unsound due to cross FFI unwind behaviour and inconsistent bindings. spirv-cross2 is a much more solid foundation to build upon.
  • This release allows Rust consumers to transition to librashader 0.4.0 with minimal changes while librashader-spirv-cross is deprecated and yanked.
• c447e40 runtime: make runtime parameters explicitly thread safe.
  • Before, setting parameters through FFI in separate threads could possibly cause a data race, this closes the soundness hole, adhering to the documented thread-safety guarantees.
  • While the C API does not change, this incurs a semver-breaking change on the Rust API.
• Direct3D 12 performance improvements
  • e934f17 d3d12: stop leaking resources in transition barriers.
  • 2e7c3b3 d3d12: use a shared heap for the filter chain rather than CreateCommittedResource.

ABI Changes Incoming

The next release in the 0.5.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI.

See #102 for more details.

librashader 0.3.3

Version 0.3.3 has the canonical C ABI version 1, and API version 1.

This is a bugfix release to address BGRA LUT image loads having the final 31 pixels be swizzled as ARGB. It also fixes builds for Windows 7 on an unsupported but recognized basis. Version 0.3.2 was skipped as that was published only for librashader as a doc-fix for macOS.

Notable Changes

b7fd3bc runtime: fix swizzle for remainder of pixels not being swizzled correctly

ABI Changes Incoming

The next release in the 0.4.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI. See #102

librashader 0.3.1

Version 0.3.1 has the canonical C ABI version 1, and API version 1.

This release promotes the Direct3D 9 runtime from experimental support to secondary support following improvements in uniform bindings, as well as bringing a much improved linking algorithm that properly demotes unused vertex shader outputs to global variables for better handling in cross-compile scenarios such as via SPIR-V Cross or spirv-to-dxil.

While this has been the case for the past couple of releases already, as of 0.3.1, tagged builds will only be provided for Windows and macOS for x86_64 and aarch64. Linux users are served by OpenBuildService, or AUR for Arch users.

CI builds will remain available on all tested platforms for the retention period of 90 days.

†The librashader crate had a 0.3.2 release to fix docs building on docs.rs for macOS and iOS due to missing wgpu dependencies.

Notable Changes

• 5ef0055 d3d9: fix searching for vertex uniform names in the fragment shader
• d1e49b7 d3d9: search for uniform names starting with global to determine register assignments
• 9b40c10, 1957f57 reflect: demote unused vertex shader outputs to global variables in SPIR-V
• 5560c1e runtime: improve LUT load swizzling using an algorithm LLVM is more likely to autovectorize

ABI Changes Incoming

The next release in the 0.4.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI. See #102

librashader 0.3.0

Version 0.3.0 has the canonical C ABI version 1, and API version 1.

This is the first "tagged" release in a while, and includes a multitude of bugfixes since 0.2.4. This is a Rust-breaking change due to updates in wgpu and windows updates, but maintains the same C ABI and API version and is backwards compatible with all versions in the 0.2.x series.

Notable Changes

• bacfbf0 cache: delete cache if corrupted
• e02e1ae gl: fix luts loading with incorrect origin
• b707195 d3d9: add an experimental Direct3D 9 runtime
• 9c895ca wgpu: fix incorrect format mismatch for framebuffer copies
• fa48b93 rt: cap texture scaling to [1, 16384], fixes crashes on Metal
• c646086 wgpu: update to wgpu 22
• 35f499f wgpu: cache pipelines for wgpu
• 3cda5b7 d3d12: ignore user-provided size for input view, and use the texture size
• 4d6793d d3d11: remove output/input view wrappers, ignoring libra_viewport_t for sizes and use the texture size directly.

ABI Changes Incoming

The next release in the 0.4.x series will be C ABI-incompatible to clean up some inconsistencies in the C ABI. See #102.