Enum naga::Expression

pub enum Expression {
    Literal(Literal),
    Constant(Handle<Constant>),
    Override(Handle<Override>),
    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,
    },
    SubgroupBallotResult,
    SubgroupOperationResult {
        ty: Handle<Type>,
    },
}

An expression that can be evaluated to obtain a value.

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

When an Expression variant holds Handle<Expression> fields, they refer to another expression in the same arena, unless explicitly noted otherwise. One Arena<Expression> may only refer to a different arena indirectly, via Constant or Override expressions, which hold handles for their respective types.

Variants

Literal(Literal)

Literal.

Constant(Handle<Constant>)

Constant value.

Override(Handle<Override>)

Pipeline-overridable constant.

ZeroValue(Handle<Type>)

Zero value of a type.

Compose

Composite expression.

Fields

ty: Handle<Type>

components: Vec<Handle<Expression>>

Access

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 with a dynamically computed index unless that matrix appears behind a pointer. In other words, if the inner type of base is Matrix, then index must be a constant. But if the type of base is a Pointer to an matrix, 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 base operands to be behind a pointer.

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

Fields

base: Handle<Expression>

index: Handle<Expression>

AccessIndex

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

Fields

base: Handle<Expression>

index: u32

Splat

Splat scalar into a vector.

Fields

size: VectorSize

value: Handle<Expression>

Swizzle

Vector swizzle.

Fields

size: VectorSize

vector: Handle<Expression>

pattern: [SwizzleComponent; 4]

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

Load a value indirectly.

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

Fields

pointer: Handle<Expression>

ImageSample

Sample a point from a sampled or a depth image.

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>>

This refers to an expression in Module::global_expressions.

level: SampleLevel

depth_ref: Option<Handle<Expression>>

ImageLoad

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.

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).

ImageQuery

Query information from an image.

Fields

image: Handle<Expression>

query: ImageQuery

Unary

Apply an unary operator.

Fields

op: UnaryOperator

expr: Handle<Expression>

Binary

Apply a binary operator.

Fields

op: BinaryOperator

left: Handle<Expression>

right: Handle<Expression>

Select

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.

Fields

condition: Handle<Expression>

Boolean expression

accept: Handle<Expression>

reject: Handle<Expression>

Derivative

Compute the derivative on an axis.

Fields

axis: DerivativeAxis

ctrl: DerivativeControl

expr: Handle<Expression>

Relational

Call a relational function.

Fields

fun: RelationalFunction

argument: Handle<Expression>

Math

Call a math function

Fields

fun: MathFunction

arg: Handle<Expression>

arg1: Option<Handle<Expression>>

arg2: Option<Handle<Expression>>

arg3: Option<Handle<Expression>>

As

Cast a simple type to another kind.

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.

CallResult(Handle<Function>)

Result of calling another function.

AtomicResult

Result of an atomic operation.

This expression must be referred to by the result field of exactly one Atomic statement somewhere in the same function. Let T be the scalar type contained by the Atomic value that the statement operates on.

If comparison is false, then ty must be the scalar type T.

If comparison is true, then ty must be a Struct with two members:

• A member named old_value, whose type is T, and

• A member named exchanged, of type BOOL.

Fields

ty: Handle<Type>

comparison: bool

WorkGroupUniformLoadResult

Result of a WorkGroupUniformLoad statement.

Fields

ty: Handle<Type>

The type of the result

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

Return an intersection found by query.

If committed is true, return the committed result available when

Fields

query: Handle<Expression>

committed: bool

SubgroupBallotResult

Result of a SubgroupBallot statement.

SubgroupOperationResult

Result of a SubgroupCollectiveOperation or SubgroupGather statement.

Fields

ty: Handle<Type>

Implementations

impl Expression

pub const fn bake_ref_count(&self) -> usize

Returns the ref count, upon reaching which this expression should be considered for baking.

Note: we have to cache any expressions that depend on the control flow, or otherwise they may be moved into a non-uniform control flow, accidentally. See the module-level documentation for details.

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 const fn is_dynamic_index(&self) -> bool

Return true if this expression is a dynamic array/vector/matrix 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 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.

impl From<ConcreteInt<1>> for Expression

fn from(value: ConcreteInt<1>) -> Self

Converts to this type from the input type.

impl From<Float<1>> for Expression

fn from(value: Float<1>) -> Self

Converts to this type from the input type.

impl From<Scalar<1>> for Expression

fn from(value: Scalar<1>) -> Self

Converts to this type from the input type.

impl From<Signed<1>> for Expression

fn from(value: Signed<1>) -> Self

Converts to this type from the input type.

impl PartialEq for Expression

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

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

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 StructuralPartialEq for Expression