Enum ShaderPanicStrategy

#[non_exhaustive]
pub enum ShaderPanicStrategy {
    SilentExit,
    DebugPrintfThenExit {
        print_inputs: bool,
        print_backtrace: bool,
    },
    UNSOUND_DO_NOT_USE_UndefinedBehaviorViaUnreachable,
}

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

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future 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.

Quick setup for enabling debugPrintf output (to stdout) at runtime:

• set these environment variables:
  • VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation
  • VK_LAYER_PRINTF_ONLY_PRESET=1
  • VK_LAYER_PRINTF_TO_STDOUT=1 (not always needed, but can help)
• if using wgpu, enable wgpu::Features::SPIRV_SHADER_PASSTHROUGH, and use create_shader_module_passthrough instead of create_shader_module
• in case of errors, or no output (from a panic!()/debug_printf!()), keep reading below for additional information and alternatives

---

Note: enabling this automatically adds the SPV_KHR_non_semantic_info extension, as debugPrintf is from a “non-semantic extended instruction set”.

Note: debugPrintf output reaching the user involves:

• being able to load the shader in the first place:
  • for wgpu, use “SPIR-V shader passthrough” (Naga lacks debugPrintf):
    • enable wgpu::Features::SPIRV_SHADER_PASSTHROUGH
    • replace create_shader_module calls with create_shader_module_passthrough
  • in theory, the VK_KHR_shader_non_semantic_info Vulkan Device extension (or requiring at least Vulkan 1.3, which incorporated it)
    • however, Validation Layers don’t actually check this anymore, since Vulkan SDK version 1.4.313.0 (and drivers shouldn’t care either)
• general configurability of Vulkan SDK and/or Vulkan Loader
  • (this list doubles as a legend for shorthands used later below)
  • env: setting environment variables on the fly
    • easiest for quick testing, no code changes/rebuilding needed
    • e.g. FOO=1 cargo run ... (in UNIX-style shells)
  • instance: programmatic control via vkCreateInstance() params
    • best for integration with app-specific debugging functionality
    • limited to direct Vulkan usage (e.g. ash, not wgpu)
    • VK_EXT_layer_settings as a VK_LAYER_* environment variables analogue, e.g. VK_LAYER_FOO controlled by a VkLayerSettingEXT with "foo" as pSettingName (and an appropriate type/value), included in VkLayerSettingsCreateInfoEXT’s pSettings
  • on-disk configuration and interactive tooling, e.g.:
    • vk_layer_settings.txt files, either hand-written, or generated by the “Vulkan Configurator” GUI tool (included with the Vulkan SDK)
    • third-party Vulkan debuggers like RenderDoc
• Vulkan Validation Layers
  • (they contain the debugPrintf implementation, a SPIR-V -> SPIR-V translation)
  • enabled by one of (as per “general configurability” above):
    • env: VK_LOADER_LAYERS_ENABLE=VK_LAYER_KHRONOS_validation
    • instance: "VK_LAYER_KHRONOS_validation" in the list of layers
    • via wgpu: wgpu::InstanceFlags::VALIDATION
• Validation Layers’ debugPrintf support (official docs):
  • enabled by one of (as per “general configurability” above):
    • env: VK_LAYER_PRINTF_ENABLE=1 (validation + debugPrintf)
    • env: VK_LAYER_PRINTF_ONLY_PRESET=1 (only debugPrintf, no validation)
    • instance: "printf_enable" / "printf_only_preset" via VkLayerSettingEXT (i.e. analogues for the two environment variables)
    • instance: VkValidationFeaturesEXT with pEnabledValidationFeatures containing VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT
• outputting the debugPrintf messages sent back from the GPU:
  • defaults to common validation logging (itself defaulting to stdout)
  • env: VK_LAYER_PRINTF_TO_STDOUT=1 (and its instance analogue) forces direct printing to stdout, bypassing VK_EXT_debug_utils etc.
  • validation logging can itself be controlled via VK_EXT_debug_utils
  • wgpu built in debug mode (and/or with debug-assertions enabled):
    • it uses VK_EXT_debug_utils internally, exposing it via log
    • with e.g. env_logger, RUST_LOG=info suffices for debugPrintf messages (as they specifically have the “info” level)
    • other log/tracing subscribers should be configured similarly

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

impl Clone for ShaderPanicStrategy

fn clone(&self) -> ShaderPanicStrategy

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ShaderPanicStrategy

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

Formats the value using the given formatter.

impl Default for ShaderPanicStrategy

fn default() -> ShaderPanicStrategy

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ShaderPanicStrategy

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ShaderPanicStrategy

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Serialize for ShaderPanicStrategy

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for ShaderPanicStrategy

impl Eq for ShaderPanicStrategy

impl StructuralPartialEq for ShaderPanicStrategy