spirv_builder

Enum ShaderPanicStrategy

Source
pub enum ShaderPanicStrategy {
    SilentExit,
    DebugPrintfThenExit {
        print_inputs: bool,
        print_backtrace: bool,
    },
    UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable,
}
Expand description

Strategy used to handle Rust panic!s in shaders compiled to SPIR-V.

Variants§

§

SilentExit

Return from shader entry-point with no side-effects (default).

While similar to the standard SPIR-V OpTerminateInvocation, this is not limited to fragment shaders, and instead supports all shaders (as it’s handled via control-flow rewriting, instead of SPIR-V features).

§

DebugPrintfThenExit

Like SilentExit, but also using debugPrintf to report the panic in a way that can reach the user, before returning from the entry-point.

Will automatically require the SPV_KHR_non_semantic_info extension, as debugPrintf uses a “non-semantic extended instruction set”.

If you have multiple entry-points, you may need to also enable the multimodule node (see https://github.com/KhronosGroup/SPIRV-Tools/issues/4892).

Note: actually obtaining the debugPrintf output requires:

  • Vulkan Validation Layers (from e.g. the Vulkan SDK)
    • (they contain the debugPrintf implementation, a SPIR-V -> SPIR-V translation)
    • set the VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation environment variable to easily enable them without any code changes
    • alternatively, "VK_LAYER_KHRONOS_validation" can be passed during instance creation, to enable them programmatically
  • Validation Layers’ debugPrintf support:
    • set the VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT environment variable to easily enable the debugPrintf support
    • alternatively, VkValidationFeaturesEXT during instance creation, or the khronos_validation.enables field in vk_layer_settings.txt, can be used to enable VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT (see also https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/main/docs/debug_printf.md)
  • for outputting the debugPrintf messages sent back from the GPU:
    • set the DEBUG_PRINTF_TO_STDOUT=1 environment variable if you don’t plan on customizing the reporting (see below for alternatives)
  • for wgpu:
    • required: wgpu::Features::SPIRV_SHADER_PASSTHROUGH (Naga lacks debugPrintf)
    • optional: building in debug mode (and/or with debug-assertions enabled), to enable wgpu logging/debug support
      • (the debug assertions requirement may be lifted in future wgpu versions)
      • this uses VK_EXT_debug_utils internally, and is a better-integrated alternative to just setting DEBUG_PRINTF_TO_STDOUT=1
      • RUST_LOG=wgpu_hal::vulkan=info (or equivalent) will enable said output (as debugPrintf messages have the “info” level)
      • RUST_LOG controls env_logger, which isn’t itself required, but some log/tracing subscriber is needed to get any output
  • for Vulkan (e.g. via ash):
    • required: enabling the VK_KHR_shader_non_semantic_info Vulkan Device extension
    • optional: as described above, enabling the Validation Layers and their debugPrintf support can be done during instance creation
    • optional: integrating VK_EXT_debug_utils allows more reporting flexibility than DEBUG_PRINTF_TO_STDOUT=1)

Fields

§print_inputs: bool

Whether to also print the entry-point inputs (excluding buffers/resources), which should uniquely identify the panicking shader invocation.

§print_backtrace: bool

Whether to also print a “backtrace” (i.e. the chain of function calls that led to the panic!).

As there is no way to dynamically compute this information, the string containing the full backtrace of each panic! is statically generated, meaning this option could significantly increase binary size.

§

UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable

Warning: this is unsound (i.e. adds Undefined Behavior to safe Rust code)

This option only exists for testing (hence the unfriendly name it has), and more specifically testing whether conditional panics are responsible for performance differences when upgrading from older Rust-GPU versions (which used infinite loops for panics, that spirv-opt/drivers could’ve sometimes treated as UB, and optimized as if they were impossible to reach).

Unlike those infinite loops, however, this uses OpUnreachable, so it forces the old worst-case (all panic!s become UB and are optimized out).

Trait Implementations§

Source§

impl Clone for ShaderPanicStrategy

Source§

fn clone(&self) -> ShaderPanicStrategy

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for ShaderPanicStrategy

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl PartialEq for ShaderPanicStrategy

Source§

fn eq(&self, other: &ShaderPanicStrategy) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl Copy for ShaderPanicStrategy

Source§

impl Eq for ShaderPanicStrategy

Source§

impl StructuralPartialEq for ShaderPanicStrategy

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.