Enum naga::Expression

pub enum Expression {
    Literal(Literal),
    Constant(Handle<Constant>),
    ZeroValue(Handle<Type>),
    Compose {
        ty: Handle<Type>,
        components: Vec<Handle<Expression>>,
    },
    Access {
        base: Handle<Expression>,
        index: Handle<Expression>,
    },
    AccessIndex {
        base: Handle<Expression>,
        index: u32,
    },
    Splat {
        size: VectorSize,
        value: Handle<Expression>,
    },
    Swizzle {
        size: VectorSize,
        vector: Handle<Expression>,
        pattern: [SwizzleComponent; 4],
    },
    FunctionArgument(u32),
    GlobalVariable(Handle<GlobalVariable>),
    LocalVariable(Handle<LocalVariable>),
    Load {
        pointer: Handle<Expression>,
    },
    ImageSample {
        image: Handle<Expression>,
        sampler: Handle<Expression>,
        gather: Option<SwizzleComponent>,
        coordinate: Handle<Expression>,
        array_index: Option<Handle<Expression>>,
        offset: Option<Handle<Expression>>,
        level: SampleLevel,
        depth_ref: Option<Handle<Expression>>,
    },
    ImageLoad {
        image: Handle<Expression>,
        coordinate: Handle<Expression>,
        array_index: Option<Handle<Expression>>,
        sample: Option<Handle<Expression>>,
        level: Option<Handle<Expression>>,
    },
    ImageQuery {
        image: Handle<Expression>,
        query: ImageQuery,
    },
    Unary {
        op: UnaryOperator,
        expr: Handle<Expression>,
    },
    Binary {
        op: BinaryOperator,
        left: Handle<Expression>,
        right: Handle<Expression>,
    },
    Select {
        condition: Handle<Expression>,
        accept: Handle<Expression>,
        reject: Handle<Expression>,
    },
    Derivative {
        axis: DerivativeAxis,
        ctrl: DerivativeControl,
        expr: Handle<Expression>,
    },
    Relational {
        fun: RelationalFunction,
        argument: Handle<Expression>,
    },
    Math {
        fun: MathFunction,
        arg: Handle<Expression>,
        arg1: Option<Handle<Expression>>,
        arg2: Option<Handle<Expression>>,
        arg3: Option<Handle<Expression>>,
    },
    As {
        expr: Handle<Expression>,
        kind: ScalarKind,
        convert: Option<Bytes>,
    },
    CallResult(Handle<Function>),
    AtomicResult {
        ty: Handle<Type>,
        comparison: bool,
    },
    WorkGroupUniformLoadResult {
        ty: Handle<Type>,
    },
    ArrayLength(Handle<Expression>),
    RayQueryProceedResult,
    RayQueryGetIntersection {
        query: Handle<Expression>,
        committed: bool,
    },
}

An expression that can be evaluated to obtain a value.

This is a Single Static Assignment (SSA) scheme similar to SPIR-V.

Variants

Literal(Literal)

Literal.

Constant(Handle<Constant>)

Constant value.

ZeroValue(Handle<Type>)

Zero value of a type.

Compose

Fields

ty: Handle<Type>

components: Vec<Handle<Expression>>

Composite expression.

Access

Fields

base: Handle<Expression>

index: Handle<Expression>

Array access with a computed index.

Typing rules

The base operand must be some composite type: Vector, Matrix, Array, a Pointer to one of those, or a ValuePointer with a size.

The index operand must be an integer, signed or unsigned.

Indexing a Vector or Array produces a value of its element type. Indexing a Matrix produces a Vector.

Indexing a Pointer to any of the above produces a pointer to the element/component type, in the same space. In the case of Array, the result is an actual Pointer, but for vectors and matrices, there may not be any type in the arena representing the component’s type, so those produce ValuePointer types equivalent to the appropriate Pointer.

Dynamic indexing restrictions

To accommodate restrictions in some of the shader languages that Naga targets, it is not permitted to subscript a matrix or array with a dynamically computed index unless that matrix or array appears behind a pointer. In other words, if the inner type of base is Array or Matrix, then index must be a constant. But if the type of base is a Pointer to an array or matrix or a ValuePointer with a size, then the index may be any expression of integer type.

You can use the Expression::is_dynamic_index method to determine whether a given index expression requires matrix or array base operands to be behind a pointer.

(It would be simpler to always require the use of AccessIndex when subscripting arrays and matrices that are not behind pointers, but to accommodate existing front ends, Naga also permits Access, with a restricted index.)

AccessIndex

Fields

base: Handle<Expression>

index: u32

Access the same types as Access, plus Struct with a known index.

Splat

Fields

size: VectorSize

value: Handle<Expression>

Splat scalar into a vector.

Swizzle

Fields

size: VectorSize

vector: Handle<Expression>

pattern: [SwizzleComponent; 4]

Vector swizzle.

FunctionArgument(u32)

Reference a function parameter, by its index.

A FunctionArgument expression evaluates to a pointer to the argument’s value. You must use a Load expression to retrieve its value, or a Store statement to assign it a new value.

GlobalVariable(Handle<GlobalVariable>)

Reference a global variable.

If the given GlobalVariable’s space is AddressSpace::Handle, then the variable stores some opaque type like a sampler or an image, and a GlobalVariable expression referring to it produces the variable’s value directly.

For any other address space, a GlobalVariable expression produces a pointer to the variable’s value. You must use a Load expression to retrieve its value, or a Store statement to assign it a new value.

LocalVariable(Handle<LocalVariable>)

Reference a local variable.

A LocalVariable expression evaluates to a pointer to the variable’s value. You must use a Load expression to retrieve its value, or a Store statement to assign it a new value.

Load

Fields

pointer: Handle<Expression>

Load a value indirectly.

For TypeInner::Atomic the result is a corresponding scalar. For other types behind the pointer<T>, the result is T.

ImageSample

Fields

image: Handle<Expression>

sampler: Handle<Expression>

gather: Option<SwizzleComponent>

If Some(), this operation is a gather operation on the selected component.

coordinate: Handle<Expression>

array_index: Option<Handle<Expression>>

offset: Option<Handle<Expression>>

Expression handle lives in const_expressions

level: SampleLevel

depth_ref: Option<Handle<Expression>>

Sample a point from a sampled or a depth image.

ImageLoad

Fields

image: Handle<Expression>

The image to load a texel from. This must have type Image. (This will necessarily be a GlobalVariable or FunctionArgument expression, since no other expressions are allowed to have that type.)

coordinate: Handle<Expression>

The coordinate of the texel we wish to load. This must be a scalar for D1 images, a Bi vector for D2 images, and a Tri vector for D3 images. (Array indices, sample indices, and explicit level-of-detail values are supplied separately.) Its component type must be Sint.

array_index: Option<Handle<Expression>>

The index into an arrayed image. If the arrayed flag in image’s type is true, then this must be Some(expr), where expr is a Sint scalar. Otherwise, it must be None.

sample: Option<Handle<Expression>>

A sample index, for multisampled Sampled and Depth images.

level: Option<Handle<Expression>>

A level of detail, for mipmapped images.

This must be present when accessing non-multisampled Sampled and Depth images, even if only the full-resolution level is present (in which case the only valid level is zero).

Load a texel from an image.

For most images, this returns a four-element vector of the same ScalarKind as the image. If the format of the image does not have four components, default values are provided: the first three components (typically R, G, and B) default to zero, and the final component (typically alpha) defaults to one.

However, if the image’s class is Depth, then this returns a Float scalar value.

ImageQuery

Fields

image: Handle<Expression>

query: ImageQuery

Query information from an image.

Unary

Fields

op: UnaryOperator

expr: Handle<Expression>

Apply an unary operator.

Binary

Fields

op: BinaryOperator

left: Handle<Expression>

right: Handle<Expression>

Apply a binary operator.

Select

Fields

condition: Handle<Expression>

Boolean expression

accept: Handle<Expression>

reject: Handle<Expression>

Select between two values based on a condition.

Note that, because expressions have no side effects, it is unobservable whether the non-selected branch is evaluated.

Derivative

Fields

axis: DerivativeAxis

ctrl: DerivativeControl

expr: Handle<Expression>

Compute the derivative on an axis.

Relational

Fields

fun: RelationalFunction

argument: Handle<Expression>

Call a relational function.

Math

Fields

fun: MathFunction

arg: Handle<Expression>

arg1: Option<Handle<Expression>>

arg2: Option<Handle<Expression>>

arg3: Option<Handle<Expression>>

Call a math function

As

Fields

expr: Handle<Expression>

Source expression, which can only be a scalar or a vector.

kind: ScalarKind

Target scalar kind.

convert: Option<Bytes>

If provided, converts to the specified byte width. Otherwise, bitcast.

Cast a simple type to another kind.

CallResult(Handle<Function>)

Result of calling another function.

AtomicResult

Fields

ty: Handle<Type>

comparison: bool

Result of an atomic operation.

WorkGroupUniformLoadResult

Fields

ty: Handle<Type>

The type of the result

Result of a WorkGroupUniformLoad statement.

ArrayLength(Handle<Expression>)

Get the length of an array. The expression must resolve to a pointer to an array with a dynamic size.

This doesn’t match the semantics of spirv’s OpArrayLength, which must be passed a pointer to a structure containing a runtime array in its’ last field.

RayQueryProceedResult

Result of a Proceed RayQuery statement.

RayQueryGetIntersection

Fields

query: Handle<Expression>

committed: bool

Return an intersection found by query.

If committed is true, return the committed result available when

Implementations

impl Expression

pub const fn needs_pre_emit(&self) -> bool

Returns true if the expression is considered emitted at the start of a function.

pub fn is_dynamic_index(&self, module: &Module) -> bool

Return true if this expression is a dynamic array index, for Access.

This method returns true if this expression is a dynamically computed index, and as such can only be used to index matrices and arrays when they appear behind a pointer. See the documentation for Access for details.

Note, this does not check the type of the given expression. It’s up to the caller to establish that the Access expression is well-typed through other means, like ResolveContext.

Trait Implementations

impl Clone for Expression

fn clone(&self) -> Expression

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Expression

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

Formats the value using the given formatter.