{"record":{"id":"b51de4a0bbd7e135","repo":"gfx-rs/wgpu","slug":"metal-does-not-support-vertex-ray-hit-return","errorCode":null,"errorMessage":"metal does not support vertex ray hit return","messagePattern":"metal does not support vertex ray hit return","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"naga/src/back/msl/writer.rs","lineNumber":362,"sourceCode":"                        (\"texture\", \"\", format.into(), access)\n                    }\n                    crate::ImageClass::External => {\n                        return write!(out, \"{EXTERNAL_TEXTURE_WRAPPER_STRUCT}\");\n                    }\n                };\n                let base_name = scalar.to_msl_name();\n                let array_str = if arrayed { \"_array\" } else { \"\" };\n                write!(\n                    out,\n                    \"{NAMESPACE}::{texture_str}{dim_str}{msaa_str}{array_str}<{base_name}, {NAMESPACE}::access::{access}>\",\n                )\n            }\n            crate::TypeInner::Sampler { comparison: _ } => {\n                write!(out, \"{NAMESPACE}::sampler\")\n            }\n            crate::TypeInner::AccelerationStructure { vertex_return } => {\n                if vertex_return {\n                    unimplemented!(\"metal does not support vertex ray hit return\")\n                }\n                write!(out, \"{RT_NAMESPACE}::instance_acceleration_structure\")\n            }\n            crate::TypeInner::RayQuery { vertex_return } => {\n                if vertex_return {\n                    unimplemented!(\"metal does not support vertex ray hit return\")\n                }\n                write!(out, \"{}\", super::ray::metal_intersector_ty())\n            }\n            crate::TypeInner::BindingArray { base, .. } => {\n                let base_inner = &self.gctx.types[base].inner;\n                let base_tyname = Self {\n                    handle: base,\n                    first_time: false,\n                    ..*self\n                };\n                match *base_inner {\n                    crate::TypeInner::Struct { .. } => {","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/naga/src/back/msl/writer.rs#L344-L380","documentation":"The MSL writer panics when translating an `AccelerationStructure` type declared with `vertex_return: true`, because Metal's ray tracing does not support returning ray hits from the vertex stage. This is an explicit unsupported-feature guard in naga's Metal backend.","triggerScenarios":"Compiling a shader for Metal that declares an acceleration structure binding or type with vertex return enabled (ray hit data returned from vertex-stage ray queries), e.g. via `acceleration_structure` with vertex_return in WGSL extensions or naga IR built with `VertexReturnValue` capability.","commonSituations":"Ray tracing on Apple GPUs where a shader attempts vertex-stage ray hit extraction; porting a DXR/Vulkan ray tracing shader that queries intersections in the vertex shader over to Metal via naga/wgpu.","solutions":["Move the ray query to a fragment/compute stage where vertex_return is false","Rebuild the shader/IR so acceleration structure and ray query types use vertex_return: false (drop the vertex ray hit return capability)","Use a backend with vertex ray tracing support (Vulkan/DX12 with appropriate extensions) for this shader"],"exampleFix":"// before (naga IR)\nTypeInner::AccelerationStructure { vertex_return: true }\n// after\nTypeInner::AccelerationStructure { vertex_return: false } // run ray query from fragment/compute stage","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"// compile the shader per-backend at startup; if MSL translation panics/fails, disable ray tracing on Metal","preventionTips":["Never enable vertex_return on acceleration structures for Metal targets","Keep ray queries in fragment or compute stages","Gate ray tracing features per adapter backend at runtime","Compile shaders for all target backends in CI to surface unimplemented paths early"],"tags":["naga","msl","metal","ray-tracing","unimplemented"],"backgroundTag":"unsupported-ray-tracing-feature","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}