Enum Statement

pub enum Statement {
    Emit(Range<Expression>),
    Block(Block),
    If {
        condition: Handle<Expression>,
        accept: Block,
        reject: Block,
    },
    Switch {
        selector: Handle<Expression>,
        cases: Vec<SwitchCase>,
    },
    Loop {
        body: Block,
        continuing: Block,
        break_if: Option<Handle<Expression>>,
    },
    Break,
    Continue,
    Return {
        value: Option<Handle<Expression>>,
    },
    Kill,
    Barrier(Barrier),
    Store {
        pointer: Handle<Expression>,
        value: Handle<Expression>,
    },
    ImageStore {
        image: Handle<Expression>,
        coordinate: Handle<Expression>,
        array_index: Option<Handle<Expression>>,
        value: Handle<Expression>,
    },
    Atomic {
        pointer: Handle<Expression>,
        fun: AtomicFunction,
        value: Handle<Expression>,
        result: Option<Handle<Expression>>,
    },
    WorkGroupUniformLoad {
        pointer: Handle<Expression>,
        result: Handle<Expression>,
    },
    Call {
        function: Handle<Function>,
        arguments: Vec<Handle<Expression>>,
        result: Option<Handle<Expression>>,
    },
    RayQuery {
        query: Handle<Expression>,
        fun: RayQueryFunction,
    },
    SubgroupBallot {
        result: Handle<Expression>,
        predicate: Option<Handle<Expression>>,
    },
    SubgroupGather {
        mode: GatherMode,
        argument: Handle<Expression>,
        result: Handle<Expression>,
    },
    SubgroupCollectiveOperation {
        op: SubgroupOperation,
        collective_op: CollectiveOperation,
        argument: Handle<Expression>,
        result: Handle<Expression>,
    },
}

Instructions which make up an executable block.

Handle<Expression> and Range<Expression> values in Statement variants refer to expressions in Function::expressions, unless otherwise noted.

Variants

Emit(Range<Expression>)

Emit a range of expressions, visible to all statements that follow in this block.

See the module-level documentation for details.

Block(Block)

A block containing more statements, to be executed sequentially.

If

Conditionally executes one of two blocks, based on the value of the condition.

Naga IR does not have “phi” instructions. If you need to use values computed in an accept or reject block after the If, store them in a LocalVariable.

Fields

condition: Handle<Expression>

accept: Block

reject: Block

Switch

Conditionally executes one of multiple blocks, based on the value of the selector.

Each case must have a distinct value, exactly one of which must be Default. The Default may appear at any position, and covers all values not explicitly appearing in other cases. A Default appearing in the midst of the list of cases does not shadow the cases that follow.

Some backend languages don’t support fallthrough (HLSL due to FXC, WGSL), and may translate fallthrough cases in the IR by duplicating code. However, all backend languages do support cases selected by multiple values, like case 1: case 2: case 3: { ... }. This is represented in the IR as a series of fallthrough cases with empty bodies, except for the last.

Naga IR does not have “phi” instructions. If you need to use values computed in a SwitchCase::body block after the Switch, store them in a LocalVariable.

Fields

selector: Handle<Expression>

cases: Vec<SwitchCase>

Loop

Executes a block repeatedly.

Each iteration of the loop executes the body block, followed by the continuing block.

Executing a Break, Return or Kill statement exits the loop.

A Continue statement in body jumps to the continuing block. The continuing block is meant to be used to represent structures like the third expression of a C-style for loop head, to which continue statements in the loop’s body jump.

The continuing block and its substatements must not contain Return or Kill statements, or any Break or Continue statements targeting this loop. (It may have Break and Continue statements targeting loops or switches nested within the continuing block.) Expressions emitted in body are in scope in continuing.

If present, break_if is an expression which is evaluated after the continuing block. Expressions emitted in body or continuing are considered to be in scope. If the expression’s value is true, control continues after the Loop statement, rather than branching back to the top of body as usual. The break_if expression corresponds to a “break if” statement in WGSL, or a loop whose back edge is an OpBranchConditional instruction in SPIR-V.

Naga IR does not have “phi” instructions. If you need to use values computed in a body or continuing block after the Loop, store them in a LocalVariable.

Fields

body: Block

continuing: Block

break_if: Option<Handle<Expression>>

Break

Exits the innermost enclosing Loop or Switch.

A Break statement may only appear within a Loop or Switch statement. It may not break out of a Loop from within the loop’s continuing block.

Continue

Skips to the continuing block of the innermost enclosing Loop.

A Continue statement may only appear within the body block of the innermost enclosing Loop statement. It must not appear within that loop’s continuing block.

Return

Returns from the function (possibly with a value).

Return statements are forbidden within the continuing block of a Loop statement.

Fields

value: Option<Handle<Expression>>

Kill

Aborts the current shader execution.

Kill statements are forbidden within the continuing block of a Loop statement.

Barrier(Barrier)

Synchronize invocations within the work group. The Barrier flags control which memory accesses should be synchronized. If empty, this becomes purely an execution barrier.

Store

Stores a value at an address.

For TypeInner::Atomic type behind the pointer, the value has to be a corresponding scalar. For other types behind the pointer<T>, the value is T.

This statement is a barrier for any operations on the Expression::LocalVariable or Expression::GlobalVariable that is the destination of an access chain, started from the pointer.

Fields

pointer: Handle<Expression>

value: Handle<Expression>

ImageStore

Stores a texel value to an image.

The image, coordinate, and array_index fields have the same meanings as the corresponding operands of an ImageLoad expression; see that documentation for details. Storing into multisampled images or images with mipmaps is not supported, so there are no level or sample operands.

This statement is a barrier for any operations on the corresponding Expression::GlobalVariable for this image.

Fields

image: Handle<Expression>

coordinate: Handle<Expression>

array_index: Option<Handle<Expression>>

value: Handle<Expression>

Atomic

Atomic function.

Fields

pointer: Handle<Expression>

Pointer to an atomic value.

This must be a Pointer to an Atomic value. The atomic’s scalar type may be I32 or U32.

If SHADER_INT64_ATOMIC_MIN_MAX or SHADER_INT64_ATOMIC_ALL_OPS are enabled, this may also be I64 or U64.

fun: AtomicFunction

Function to run on the atomic value.

If pointer refers to a 64-bit atomic value, then:

• The SHADER_INT64_ATOMIC_ALL_OPS capability allows any AtomicFunction value here.

• The SHADER_INT64_ATOMIC_MIN_MAX capability allows AtomicFunction::Min and AtomicFunction::Max here.

• If neither of those capabilities are present, then 64-bit scalar atomics are not allowed.

value: Handle<Expression>

Value to use in the function.

This must be a scalar of the same type as pointer’s atomic’s scalar type.

result: Option<Handle<Expression>>

AtomicResult expression representing this function’s result.

If fun is Exchange { compare: None }, this must be Some, as otherwise that operation would be equivalent to a simple Store to the atomic.

Otherwise, this may be None if the return value of the operation is not needed.

If pointer refers to a 64-bit atomic value, SHADER_INT64_ATOMIC_MIN_MAX is enabled, and SHADER_INT64_ATOMIC_ALL_OPS is not, this must be None.

WorkGroupUniformLoad

Load uniformly from a uniform pointer in the workgroup address space.

Corresponds to the workgroupUniformLoad built-in function of wgsl, and has the same barrier semantics

Fields

pointer: Handle<Expression>

This must be of type Pointer in the WorkGroup address space

result: Handle<Expression>

The WorkGroupUniformLoadResult expression representing this load’s result.

Call

Calls a function.

If the result is Some, the corresponding expression has to be Expression::CallResult, and this statement serves as a barrier for any operations on that expression.

Fields

function: Handle<Function>

arguments: Vec<Handle<Expression>>

result: Option<Handle<Expression>>

RayQuery

Fields

query: Handle<Expression>

The RayQuery object this statement operates on.

fun: RayQueryFunction

The specific operation we’re performing on query.

SubgroupBallot

Calculate a bitmask using a boolean from each active thread in the subgroup

Fields

result: Handle<Expression>

The SubgroupBallotResult expression representing this load’s result.

predicate: Option<Handle<Expression>>

The value from this thread to store in the ballot

SubgroupGather

Gather a value from another active thread in the subgroup

Fields

mode: GatherMode

Specifies which thread to gather from

argument: Handle<Expression>

The value to broadcast over

result: Handle<Expression>

The SubgroupOperationResult expression representing this load’s result.

SubgroupCollectiveOperation

Compute a collective operation across all active threads in the subgroup

Fields

op: SubgroupOperation

What operation to compute

collective_op: CollectiveOperation

How to combine the results

argument: Handle<Expression>

The value to compute over

result: Handle<Expression>

The SubgroupOperationResult expression representing this load’s result.

Implementations

impl Statement

pub const fn is_terminator(&self) -> bool

Returns true if the statement directly terminates the current block.

Used to decide whether case blocks require a explicit break.

Trait Implementations

impl<'arbitrary> Arbitrary<'arbitrary> for Statement

fn arbitrary(u: &mut Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl Clone for Statement

fn clone(&self) -> Statement

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Statement

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Statement

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Statement

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

where __S: Serializer,

Serialize this value into the given Serde serializer.