Naga

https://docs.rs/naga/latest/
Admin
Naga is a shader translation tool that converts source code written in one shading language to...
Tokens:1,631,564
Snippets:8,910
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Get first chunk of slice

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Example usage of the first_chunk method on a slice.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

--------------------------------

### Instantiate and use Frontend

Source: https://docs.rs/naga/latest/naga/front/glsl/struct.Frontend.html

Demonstrates creating a new Frontend instance and parsing a GLSL shader string.

```rust
use naga::ShaderStage;
use naga::front::glsl::{Frontend, Options};

let glsl = r#"
    #version 450 core

    void main() {}
"#;

let mut frontend = Frontend::default();
let options = Options::from(ShaderStage::Vertex);
frontend.parse(&options, glsl);
```

--------------------------------

### Frontend::default

Source: https://docs.rs/naga/latest/naga/front/glsl/struct.Frontend.html?search=

Creates a new instance of the GLSL Frontend.

```APIDOC
### fn default()

Returns a new `Frontend` instance. This is the standard way to initialize the frontend before parsing shaders.
```

--------------------------------

### Get last element of slice

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Example usage of the last method on a slice.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### Get first element of slice

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Example usage of the first method on a slice.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### Frontend::new

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Frontend.html

Creates a new instance of the WGSL Frontend.

```APIDOC
### pub const fn new() -> Self

Creates a new instance of the WGSL Frontend with default options.
```

--------------------------------

### Get mutable reference to last element

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Example usage of the last_mut method on a slice.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.last_mut());
```

--------------------------------

### Frontend::new

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Frontend.html?search=

Creates a new instance of the WGSL Frontend.

```APIDOC
### pub const fn new() -> Self

Creates a new instance of the WGSL Frontend with default settings.
```

--------------------------------

### Frontend::new

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Frontend.html?search=u32+-%3E+bool

Creates a new instance of the WGSL Frontend.

```APIDOC
## pub const fn new() -> Self

### Description
Creates a new instance of the WGSL Frontend with default options.
```

--------------------------------

### Get mutable reference to first element

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Example usage of the first_mut method on a slice.

```rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.first_mut());
```

--------------------------------

### Retrieve pointer range of a slice

Source: https://docs.rs/naga/latest/naga/ir/struct.Block.html

Use as_ptr_range to get a half-open range of pointers spanning the slice. This is useful for foreign interfaces expecting start and end pointers.

```rust
let a = [1, 2, 3];
let x = &a[1] as *const _;
let y = &5 as *const _;

assert!(a.as_ptr_range().contains(&x));
assert!(!a.as_ptr_range().contains(&y));
```

--------------------------------

### Frontend::new_with_options

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Frontend.html?search=u32+-%3E+bool

Creates a new instance of the WGSL Frontend with specific options.

```APIDOC
## pub const fn new_with_options(options: Options) -> Self

### Description
Creates a new instance of the WGSL Frontend configured with the provided options.
```

--------------------------------

### Example TypeInner::Matrix usage

Source: https://docs.rs/naga/latest/naga/proc/enum.TypeResolution.html?search=

Example of a TypeInner::Matrix variant.

```rust
TypeInner::Matrix { columns, rows, width }
```

--------------------------------

### naga::front::wgsl::Options::new

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Options.html?search=std%3A%3Avec

Creates a new default instance of the Options configuration struct.

```APIDOC
## pub const fn new() -> Self

### Description
Creates a new default `Options` instance for the WGSL parser.

### Returns
- **Self** - A new `Options` instance with default values.
```

--------------------------------

### Initialize and use the WGSL Frontend

Source: https://docs.rs/naga/latest/src/naga/front/wgsl/mod.rs.html?search=

The Frontend struct manages the parsing process. Use new() or new_with_options() to initialize, then call parse() to convert WGSL source into a module.

```rust
impl Frontend {
    pub const fn new() -> Self {
        Self {
            parser: Parser::new(),
            options: Options::new(),
        }
    }

    pub const fn new_with_options(options: Options) -> Self {
        Self {
            parser: Parser::new(),
            options,
        }
    }

    pub const fn set_options(&mut self, options: Options) {
        self.options = options;
    }

    pub fn parse(&mut self, source: &str) -> core::result::Result<crate::Module, ParseError> {
        self.inner(source).map_err(|x| x.as_parse_error(source))
    }

    fn inner<'a>(&mut self, source: &'a str) -> Result<'a, crate::Module> {
        let tu = self.parser.parse(source, &self.options)?;
        let index = index::Index::generate(&tu)?;
        let module = Lowerer::new(&index).lower(tu)?;

        Ok(module)
    }
}
```

--------------------------------

### WGSL Texture Dimensions Example

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/help.rs.html?search=u32+-%3E+bool

Example of a texture dimension query in WGSL.

```wgsl
let dim_1d = textureDimensions(image_1d);
```

--------------------------------

### Initialize Entry Point Translation

Source: https://docs.rs/naga/latest/src/naga/back/msl/writer.rs.html?search=u32+-%3E+bool

Sets up the translation info and iterates through entry points for MSL generation.

```rust
6962        let ep_range = get_entry_points(module, pipeline_options.entry_point.as_ref())
6963            .map_err(|(stage, name)| Error::EntryPointNotFound(stage, name))?;
6964
6965        let mut info = TranslationInfo {
6966            entry_point_names: Vec::with_capacity(ep_range.len()),
6967        };
6968
6969        for ep_index in ep_range {
6970            let ep = &module.entry_points[ep_index];
6971            let fun = &ep.function;
6972            let fun_info = mod_info.get_entry_point(ep_index);
6973            let mut ep_error = None;
6974
6975            // For vertex_id and instance_id arguments, presume that we'll
6976            // use our generated names, but switch to the name of an
6977            // existing @builtin param, if we find one.
6978            let mut v_existing_id = None;
6979            let mut i_existing_id = None;
6980
6981            log::trace!(
6982                "entry point {:?}, index {:?}",
6983                fun.name.as_deref().unwrap_or("(anonymous)"),
6984                ep_index
6985            );
6986
6987            let ctx = back::FunctionCtx {
```

--------------------------------

### TypeResolution Examples

Source: https://docs.rs/naga/latest/src/naga/proc/typifier.rs.html?search=

Examples of how TypeResolution represents types for matrix and pointer access expressions.

```rust
TypeInner::Matrix { columns, rows, width }
```

```rust
TypeResolution::Value(TypeInner::Vector {
    size: rows,
    kind: ScalarKind::Float,
    width,
})
```

```rust
TypeResolution::Value(TypeInner::ValuePointer {
    size: Some(rows),
    kind: ScalarKind::Float,
    width,
    space,
})
```

--------------------------------

### SPIR-V Function and Interface Setup

Source: https://docs.rs/naga/latest/src/naga/back/spv/writer.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Handles the initialization of function signatures and entry point interface context within the SPIR-V writer.

```rust
1463                            .to_words(&mut self.logical_layout.declarations);
1464                        self.decorate(
1465                            varying_id,
1466                            spirv::Decoration::BuiltIn,
1467                            &[spirv::BuiltIn::PointSize as u32],
1468                        );
1469                        iface.varying_ids.push(varying_id);
1470
1471                        let default_value_id = self.get_constant_scalar(crate::Literal::F32(1.0));
1472                        prelude
1473                            .body
1474                            .push(Instruction::store(varying_id, default_value_id, None));
1475                    }
1476                    if iface.stage == crate::ShaderStage::Task {
1477                        self.get_vec3u_type_id()
1478                    } else {
1479                        self.void_type
1480                    }
1481                } else {
1482                    self.get_handle_type_id(result.ty)
1483                }
1484            }
1485            None => self.void_type,
1486        };
1487
1488        if let Some(ref mut iface) = interface {
1489            if let Some(task_payload) = iface.task_payload {
1490                iface
1491                    .varying_ids
1492                    .push(self.global_variables[task_payload].var_id);
1493            }
1494            self.write_entry_point_mesh_shader_info(
1495                iface,
1496                local_invocation_index_var_id,
1497                ir_module,
1498                &mut ep_context,
1499            )?;
1500        }
1501
1502        let lookup_function_type = LookupFunctionType {
1503            parameter_type_ids,
1504            return_type_id,
1505        };
1506
1507        let function_id = self.id_gen.next();
1508        if self.flags.contains(WriterFlags::DEBUG) {
1509            if let Some(ref name) = ir_function.name {
1510                self.debugs.push(Instruction::name(function_id, name));
1511            }
1512        }
1513
1514        let function_type = self.get_function_type(lookup_function_type);
1515        function.signature = Some(Instruction::function(
1516            return_type_id,
1517            function_id,
1518            spirv::FunctionControl::empty(),
1519            function_type,
1520        ));
1521
1522        if interface.is_some() {
1523            function.entry_point_context = Some(ep_context);
1524        }
```

--------------------------------

### GLSL If Statement Syntax Example

Source: https://docs.rs/naga/latest/src/naga/back/glsl/writer.rs.html?search=

Example of the generated GLSL syntax for if-else blocks.

```glsl
if(condition) {
  accept
} else {
  reject
}
```

--------------------------------

### Frontend::new_with_options

Source: https://docs.rs/naga/latest/naga/front/wgsl/struct.Frontend.html

Creates a new instance of the WGSL Frontend with specific parsing options.

```APIDOC
### pub const fn new_with_options(options: Options) -> Self

Creates a new instance of the WGSL Frontend using the provided Options.
```

--------------------------------

### Example TypeResolution::Value for ValuePointer

Source: https://docs.rs/naga/latest/naga/proc/enum.TypeResolution.html?search=

Example of resolving an access expression to a pointer of a matrix.

```rust
TypeResolution::Value(TypeInner::ValuePointer {
    size: Some(rows),
    kind: ScalarKind::Float,
    width,
    space,
})
```

--------------------------------

### Example TypeResolution::Value for Vector

Source: https://docs.rs/naga/latest/naga/proc/enum.TypeResolution.html?search=

Example of resolving an access expression to a vector type.

```rust
TypeResolution::Value(TypeInner::Vector {
    size: rows,
    kind: ScalarKind::Float,
    width,
})
```

--------------------------------

### Parse a GLSL shader

Source: https://docs.rs/naga/latest/src/naga/front/glsl/mod.rs.html?search=

Example of initializing the frontend and parsing a basic GLSL shader string.

```rust
let mut frontend = Frontend::default();
let options = Options::from(ShaderStage::Vertex);
frontend.parse(&options, glsl);
```

--------------------------------

### Initialize Frontend

Source: https://docs.rs/naga/latest/src/naga/front/spv/mod.rs.html?search=u32+-%3E+bool

Constructor for the Frontend struct, requiring an iterator over u32 words and configuration options.

```rust
impl<I: Iterator<Item = u32>> Frontend<I> {
    pub fn new(data: I, options: &Options) -> Self {
        Frontend {
            data,
            data_offset: 0,
            state: ModuleState::Empty,
            layouter: Layouter::default(),
            temp_bytes: Vec::new(),
```

--------------------------------

### GLSL Switch Statement Syntax Example

Source: https://docs.rs/naga/latest/src/naga/back/glsl/writer.rs.html?search=

Example of the generated GLSL syntax for switch blocks.

```glsl
switch (selector) {
```

--------------------------------

### Write Entry Point Argument Initialization

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/writer.rs.html?search=

Maps WGSL built-in bindings to HLSL intrinsic functions during entry point argument initialization.

```rust
    fn write_ep_argument_initialization(
        &mut self,
        ep: &crate::EntryPoint,
        ep_input: &EntryPointBinding,
        fake_member: &EpStructMember,
    ) -> BackendResult {
        match fake_member.binding {
            Some(crate::Binding::BuiltIn(crate::BuiltIn::SubgroupSize)) => {
                write!(self.out, "WaveGetLaneCount()")?
            }
            Some(crate::Binding::BuiltIn(crate::BuiltIn::SubgroupInvocationId)) => {
                write!(self.out, "WaveGetLaneIndex()")?
            }
            Some(crate::Binding::BuiltIn(crate::BuiltIn::NumSubgroups)) => write!(
                self.out,
                "({}u + WaveGetLaneCount() - 1u) / WaveGetLaneCount()",
                ep.workgroup_size[0] * ep.workgroup_size[1] * ep.workgroup_size[2]
            )?,
            Some(crate::Binding::BuiltIn(crate::BuiltIn::SubgroupId)) => {
                write!(
                    self.out,
                    "{}.{} / WaveGetLaneCount()",
                    ep_input.arg_name,
                    // When writing SubgroupId, we always guarantee that local_invocation_index_name is written
                    ep_input.local_invocation_index_name.as_ref().unwrap()
                )?;
            }
            Some(crate::Binding::Location {
                interpolation: Some(crate::Interpolation::PerVertex),
                ..
            }) => {
                if self.options.shader_model < ShaderModel::V6_1 {
                    return Err(Error::ShaderModelTooLow(
                        "per_vertex fragment inputs".to_string(),
```

--------------------------------

### GLSL Uniform Structure Example

Source: https://docs.rs/naga/latest/naga/back/glsl/struct.ImmediateItem.html?search=

Example of a GLSL structure definition that would be mapped by ImmediateItem.

```glsl
struct InnerStruct {
    value: f32,
}

struct ImmediateData {
    InnerStruct inner;
    vec4 array[2];
}

uniform ImmediateData _immediates_binding_cs;
```

--------------------------------

### Frontend::default

Source: https://docs.rs/naga/latest/naga/front/glsl/struct.Frontend.html

Creates a new instance of the Frontend structure.

```APIDOC
## Frontend::default

### Description
Instantiates a new Frontend instance using the Default trait.

### Signature
`pub fn default() -> Frontend`
```

--------------------------------

### HLSL Switch Case Syntax Examples

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/writer.rs.html?search=

Examples of supported and unsupported switch case patterns in FXC.

```hlsl
case 1:
case 2: do_stuff()
```

```hlsl
case 1: do_this();
case 2: do_that();
```

--------------------------------

### Frontend::new

Source: https://docs.rs/naga/latest/naga/front/spv/struct.Frontend.html?search=

Creates a new instance of the SPIR-V Frontend.

```APIDOC
## pub fn new(data: I, options: &Options) -> Self

### Description
Initializes a new Frontend instance with the provided SPIR-V data iterator and parsing options.

### Parameters
- **data** (I: Iterator<Item = u32>) - Required - An iterator over the SPIR-V binary data.
- **options** (&Options) - Required - Configuration options for the parsing process.
```

--------------------------------

### WGSL Texture Dimension Query Example

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/help.rs.html

Example of a texture dimension query with a mipmap level in WGSL.

```wgsl
let dim_cube_array_lod = textureDimensions(image_cube_array, 1);
```

--------------------------------

### Example SPIR-V conditional structure logic

Source: https://docs.rs/naga/latest/src/naga/back/spv/selection.rs.html

Conceptual example of how to structure conditional logic using the Selection builder.

```rust
    value = DEFAULT;
    if COND1 && COND2 {
        value = THEN_VALUE;
    }
    // use value
```

```rust
    let cond = Selection::start(block, merge_type);
        // ... compute `cond1` ...
    cond.if_true(ctx, cond1, DEFAULT);
        // ... compute `cond2` ...
    cond.if_true(ctx, cond2, DEFAULT);
        // ... compute THEN_VALUE
    let merged_value = cond.finish(ctx, THEN_VALUE);
```

--------------------------------

### Initialize Entry Point Translation

Source: https://docs.rs/naga/latest/src/naga/back/msl/writer.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets up the translation process for entry points, including name resolution and context initialization.

```rust
let ep_range = get_entry_points(module, pipeline_options.entry_point.as_ref())
            .map_err(|(stage, name)| Error::EntryPointNotFound(stage, name))?;

        let mut info = TranslationInfo {
            entry_point_names: Vec::with_capacity(ep_range.len()),
        };

        for ep_index in ep_range {
            let ep = &module.entry_points[ep_index];
            let fun = &ep.function;
            let fun_info = mod_info.get_entry_point(ep_index);
            let mut ep_error = None;

            // For vertex_id and instance_id arguments, presume that we'll
            // use our generated names, but switch to the name of an
            // existing @builtin param, if we find one.
            let mut v_existing_id = None;
            let mut i_existing_id = None;

            log::trace!(
                "entry point {:?}, index {:?}",
                fun.name.as_deref().unwrap_or("(anonymous)"),
                ep_index
            );

            let ctx = back::FunctionCtx {
```

--------------------------------

### MSL Infinite Loop Example

Source: https://docs.rs/naga/latest/src/naga/back/msl/writer.rs.html?search=

Example of code that may trigger MSL compiler assumptions about infinite loops.

```cpp
if (i >= 10) {
    while (true) { }
}
```

--------------------------------

### Synthesize GLSL Entry Point

Source: https://docs.rs/naga/latest/src/naga/front/glsl/functions.rs.html?search=

Creates a Naga EntryPoint that initializes input variables, calls the main function, and collects output variables.

```rust
pub(crate) fn add_entry_point(
        &mut self,
        function: Handle<Function>,
        mut ctx: Context,
    ) -> Result<()> {
        let mut arguments = Vec::new();

        let body = Block::with_capacity(
            // global init body
            ctx.body.len() +
            // prologue and epilogue
            self.entry_args.len() * 2
            // Call, Emit for composing struct and return
            + 3,
        );

        let global_init_body = core::mem::replace(&mut ctx.body, body);

        for arg in self.entry_args.iter() {
            if arg.storage != StorageQualifier::Input {
                continue;
            }

            let pointer = ctx
                .expressions
                .append(Expression::GlobalVariable(arg.handle), Default::default());
            ctx.local_expression_kind_tracker
                .insert(pointer, crate::proc::ExpressionKind::Runtime);

            let ty = ctx.module.global_variables[arg.handle].ty;

            ctx.arg_type_walker(
                arg.name.clone(),
                arg.binding.clone(),
                pointer,
                ty,
                &mut |ctx, name, pointer, ty, binding| {
                    let idx = arguments.len() as u32;

                    arguments.push(FunctionArgument {
                        name,
                        ty,
                        binding: Some(binding),
                    });

                    let value = ctx
                        .expressions
                        .append(Expression::FunctionArgument(idx), Default::default());
                    ctx.local_expression_kind_tracker
                        .insert(value, crate::proc::ExpressionKind::Runtime);
                    ctx.body
                        .push(Statement::Store { pointer, value }, Default::default());
                },
            )?
        }

        ctx.body.extend_block(global_init_body);

        ctx.body.push(
            Statement::Call {
                function,
                arguments: Vec::new(),
                result: None,
            },
            Default::default(),
        );

        let mut span = 0;
        let mut members = Vec::new();
        let mut components = Vec::new();

        for arg in self.entry_args.iter() {
            if arg.storage != StorageQualifier::Output {
                continue;
            }

            let pointer = ctx
                .expressions
                .append(Expression::GlobalVariable(arg.handle), Default::default());
            ctx.local_expression_kind_tracker
                .insert(pointer, crate::proc::ExpressionKind::Runtime);

            let ty = ctx.module.global_variables[arg.handle].ty;

            ctx.arg_type_walker(
                arg.name.clone(),
                arg.binding.clone(),
                pointer,
                ty,
```

--------------------------------

### HLSL Wrapped Function Example

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/help.rs.html?search=u32+-%3E+bool

Example of how the HLSL backend wraps a texture dimension query into a unique function.

```hlsl
int NagaDimensions1D(Texture1D<float4>)
{
   uint4 ret;
   image_1d.GetDimensions(ret.x);
   return ret.x;
}

int dim_1d = NagaDimensions1D(image_1d);
```

--------------------------------

### Options

Source: https://docs.rs/naga/latest/src/naga/front/glsl/mod.rs.html

Configuration structure for the GLSL frontend.

```APIDOC
## Options

### Description
Configuration structure passed to the `Frontend::parse` method to define how the GLSL code should be processed.

### Fields
- **stage** (ShaderStage) - Required - The shader stage in the pipeline (e.g., Vertex, Fragment, Compute).
- **defines** (FastHashMap<String, String>) - Optional - Preprocessor definitions to be applied during parsing.
```

--------------------------------

### Create HashMap with Capacity and Allocator

Source: https://docs.rs/naga/latest/naga/back/type.PipelineConstants.html?search=

Demonstrates initializing a HashMap with a specific capacity and custom allocator.

```rust
use hashbrown::HashMap;
use bumpalo::Bump;

let bump = Bump::new();
let mut map = HashMap::with_capacity_in(5, &bump);

// The created HashMap holds none elements
assert_eq!(map.len(), 0);
// But it can hold at least 5 elements without reallocating
let empty_map_capacity = map.capacity();
assert!(empty_map_capacity >= 5);

// Now we insert some 5 elements inside created HashMap
map.insert("One",   1);
map.insert("Two",   2);
map.insert("Three", 3);
map.insert("Four",  4);
map.insert("Five",  5);

// We can see that the HashMap holds 5 elements
assert_eq!(map.len(), 5);
// But its capacity isn't changed
assert_eq!(map.capacity(), empty_map_capacity)
```

--------------------------------

### GLSL Uniform Mapping Example

Source: https://docs.rs/naga/latest/naga/back/glsl/struct.ImmediateItem.html

Example showing how a struct definition maps to generated GLSL uniform names.

```glsl
struct InnerStruct {
    value: f32,
}

struct ImmediateData {
    InnerStruct inner;
    vec4 array[2];
}

uniform ImmediateData _immediates_binding_cs;
```

```text
- _immediates_binding_cs.inner.value
- _immediates_binding_cs.array[0]
- _immediates_binding_cs.array[1]
```

--------------------------------

### Construct Ray Query Instructions

Source: https://docs.rs/naga/latest/src/naga/back/spv/instructions.rs.html

Methods for initializing and managing ray queries in SPIR-V.

```rust
    #[allow(clippy::too_many_arguments)]
    pub(super) fn ray_query_initialize(
        query: Word,
        acceleration_structure: Word,
        ray_flags: Word,
        cull_mask: Word,
        ray_origin: Word,
        ray_tmin: Word,
        ray_dir: Word,
        ray_tmax: Word,
    ) -> Self {
        let mut instruction = Self::new(Op::RayQueryInitializeKHR);
        instruction.add_operand(query);
        instruction.add_operand(acceleration_structure);
        instruction.add_operand(ray_flags);
        instruction.add_operand(cull_mask);
        instruction.add_operand(ray_origin);
        instruction.add_operand(ray_tmin);
        instruction.add_operand(ray_dir);
        instruction.add_operand(ray_tmax);
        instruction
    }

    pub(super) fn ray_query_proceed(result_type_id: Word, id: Word, query: Word) -> Self {
        let mut instruction = Self::new(Op::RayQueryProceedKHR);
        instruction.set_type(result_type_id);
        instruction.set_result(id);
        instruction.add_operand(query);
        instruction
    }

    pub(super) fn ray_query_generate_intersection(query: Word, hit: Word) -> Self {
        let mut instruction = Self::new(Op::RayQueryGenerateIntersectionKHR);
        instruction.add_operand(query);
        instruction.add_operand(hit);
        instruction
    }

    pub(super) fn ray_query_confirm_intersection(query: Word) -> Self {
        let mut instruction = Self::new(Op::RayQueryConfirmIntersectionKHR);
        instruction.add_operand(query);
        instruction
    }

    pub(super) fn ray_query_return_vertex_position(
        result_type_id: Word,
        id: Word,
        query: Word,
        intersection: Word,
    ) -> Self {
        let mut instruction = Self::new(Op::RayQueryGetIntersectionTriangleVertexPositionsKHR);
        instruction.set_type(result_type_id);
        instruction.set_result(id);
        instruction.add_operand(query);
        instruction.add_operand(intersection);
        instruction
    }

    pub(super) fn ray_query_get_intersection(
        op: Op,
        result_type_id: Word,
        id: Word,
        query: Word,
        intersection: Word,
    ) -> Self {
        let mut instruction = Self::new(op);
        instruction.set_type(result_type_id);
        instruction.set_result(id);
        instruction.add_operand(query);
        instruction.add_operand(intersection);
        instruction
    }

    pub(super) fn ray_query_get_t_min(result_type_id: Word, id: Word, query: Word) -> Self {
        let mut instruction = Self::new(Op::RayQueryGetRayTMinKHR);
        instruction.set_type(result_type_id);
        instruction.set_result(id);
        instruction.add_operand(query);
        instruction
    }

    pub(super) fn ray_query_terminate(query: Word) -> Self {
        let mut instruction = Self::new(Op::RayQueryTerminateKHR);
        instruction.add_operand(query);
        instruction
    }
```

--------------------------------

### SPIR-V Array Type Definition Examples

Source: https://docs.rs/naga/latest/src/naga/front/spv/mod.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples of SPIR-V instructions used to define image arrays and pointers to image arrays.

```text
%image = OpTypeImage %float 2D 2 0 0 2 Rgba16f
%uint_256 = OpConstant %uint 256
%image_array = OpTypeArray %image %uint_256
```

```text
%image = OpTypeImage %float 2D 2 0 0 2 Rgba16f
%uint_256 = OpConstant %uint 256
%image_array = OpTypeArray %image %uint_256
%image_array_ptr = OpTypePointer UniformConstant %image_array
```

--------------------------------

### Create HashMap with Allocator

Source: https://docs.rs/naga/latest/naga/back/type.PipelineConstants.html?search=

Demonstrates initializing a HashMap using a custom allocator.

```rust
use hashbrown::HashMap;
use bumpalo::Bump;

let bump = Bump::new();
let mut map = HashMap::new_in(&bump);

// The created HashMap holds none elements
assert_eq!(map.len(), 0);

// The created HashMap also doesn't allocate memory
assert_eq!(map.capacity(), 0);

// Now we insert element inside created HashMap
map.insert("One", 1);
// We can see that the HashMap holds 1 element
assert_eq!(map.len(), 1);
// And it also allocates some capacity
assert!(map.capacity() > 1);
```

--------------------------------

### WGSL Texture Dimensions Example

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/help.rs.html?search=std%3A%3Avec

Example of texture dimension queries in WGSL that trigger the HLSL backend's wrapping logic.

```wgsl
let dim_cube_array_lod = textureDimensions(image_cube_array, 1);
let dim_cube_array_lod2 = textureDimensions(image_cube_array, 1);
```

--------------------------------

### Conditional Assignment Optimization Example

Source: https://docs.rs/naga/latest/src/naga/back/msl/writer.rs.html?search=

Example of how the MSL compiler might optimize away a conditional check if it determines the condition is always true.

```ignore
if (i < 10) {
    a[i] = 1;
}
```

```ignore
a[i] = 1;
```

--------------------------------

### Initialize Entry Point Wrapper

Source: https://docs.rs/naga/latest/src/naga/front/spv/function.rs.html

Creates a new wrapping function structure for an entry point.

```rust
pub(super) fn process_entry_point(
        &mut self,
        module: &mut crate::Module,
        ep: super::EntryPoint,
        fun_id: u32,
    ) -> Result<(), Error> {
        // create a wrapping function
        let mut function = crate::Function {
            name: Some(format!("{}_wrap", ep.name)),
            arguments: Vec::new(),
            result: None,
            local_variables: Arena::new(),
            expressions: Arena::new(),
            named_expressions: crate::NamedExpressions::default(),
```

--------------------------------

### DXC Zero Value Compilation Error Example

Source: https://docs.rs/naga/latest/src/naga/back/hlsl/help.rs.html?search=std%3A%3Avec

Example of a compilation error encountered when using direct zero-value casting in HLSL with DXC.

```text
tests\out\hlsl\access.hlsl:183:41: error: cannot compile this l-value expression yet
```
Tokens:
Raw