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

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

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

This refers to an expression in Module::global_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.

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.

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

SubgroupBallotResult

Result of a SubgroupBallot statement.

SubgroupOperationResult

Fields

ty: Handle<Type>

Result of a SubgroupCollectiveOperation or SubgroupGather statement.

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<'arbitrary> Arbitrary<'arbitrary> for Expression

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.

fn try_size_hint( depth: usize ) -> Result<(usize, Option<usize>), MaxRecursionReached>

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

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<'de> Deserialize<'de> for Expression

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Expression

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Expression

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Expression