Enum naga::Expression

pub enum Expression {
    Access {
        base: Handle<Expression>,
        index: Handle<Expression>,
    },
    AccessIndex {
        base: Handle<Expression>,
        index: u32,
    },
    Constant(Handle<Constant>),
    Splat {
        size: VectorSize,
        value: Handle<Expression>,
    },
    Swizzle {
        size: VectorSize,
        vector: Handle<Expression>,
        pattern: [SwizzleComponent; 4],
    },
    Compose {
        ty: Handle<Type>,
        components: Vec<Handle<Expression>>,
    },
    FunctionArgument(u32),
    GlobalVariable(Handle<GlobalVariable>),
    LocalVariable(Handle<LocalVariable>),
    Load {
        pointer: Handle<Expression>,
    },
    ImageSample {
        image: Handle<Expression>,
        sampler: Handle<Expression>,
        coordinate: Handle<Expression>,
        array_index: Option<Handle<Expression>>,
        offset: Option<Handle<Constant>>,
        level: SampleLevel,
        depth_ref: Option<Handle<Expression>>,
    },
    ImageLoad {
        image: Handle<Expression>,
        coordinate: Handle<Expression>,
        array_index: Option<Handle<Expression>>,
        index: 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,
        expr: Handle<Expression>,
    },
    Relational {
        fun: RelationalFunction,
        argument: Handle<Expression>,
    },
    Math {
        fun: MathFunction,
        arg: Handle<Expression>,
        arg1: Option<Handle<Expression>>,
        arg2: Option<Handle<Expression>>,
    },
    As {
        expr: Handle<Expression>,
        kind: ScalarKind,
        convert: Option<Bytes>,
    },
    CallResult(Handle<Function>),
    AtomicResult {
        kind: ScalarKind,
        width: Bytes,
        comparison: bool,
    },
    ArrayLength(Handle<Expression>),
}

An expression that can be evaluated to obtain a value.

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

Variants

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 an Array produces a Pointer to its base type, taking on the Pointer’s storage class.

Indexing a Pointer to a Vector produces a ValuePointer whose size is None, taking on the Vector’s scalar kind and width and the Pointer’s storage class.

Indexing a Pointer to a Matrix produces a ValuePointer for a column of the matrix: its size is the matrix’s height, its kind is Float, and it inherits the Matrix’s width and the Pointer’s storage class.

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

Fields of Access

base: Handle<Expression>index: Handle<Expression>

AccessIndex

Array access with a known index.

Fields of AccessIndex

base: Handle<Expression>index: u32

Constant(Handle<Constant>)

Constant value.

Every Constant expression

Tuple Fields of Constant

0: Handle<Constant>

Splat

Splat scalar into a vector.

Fields of Splat

size: VectorSizevalue: Handle<Expression>

Swizzle

Vector swizzle.

Fields of Swizzle

size: VectorSizevector: Handle<Expression>pattern: [SwizzleComponent; 4]

Compose

Composite expression.

Fields of Compose

ty: Handle<Type>components: Vec<Handle<Expression>>

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.

Tuple Fields of FunctionArgument

0: u32

GlobalVariable(Handle<GlobalVariable>)

Reference a global variable.

If the given GlobalVariable’s class is StorageClass::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 storage class, 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.

Tuple Fields of GlobalVariable

0: Handle<GlobalVariable>

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.

Tuple Fields of LocalVariable

0: Handle<LocalVariable>

Load

Load a value indirectly.

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

Fields of Load

pointer: Handle<Expression>

ImageSample

Sample a point from a sampled or a depth image.

Fields of ImageSample

image: Handle<Expression>sampler: Handle<Expression>coordinate: Handle<Expression>array_index: Option<Handle<Expression>>offset: Option<Handle<Constant>>level: SampleLeveldepth_ref: Option<Handle<Expression>>

ImageLoad

Load a texel from an image.

Fields of ImageLoad

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.

index: Option<Handle<Expression>>

The sample within a particular texel.

The meaning of this value depends on the class of image:

• Storage images hold exactly one sample per texel, so index must be None.

• Depth images may have mipmaps, so index must be Some(level), where level identifies the level of detail.

• Sampled images may be multisampled or have mipmaps, but not both. Which one is indicated by the Sampled variant’s multi field:

  • If multi is true, then the image has multiple samples per texel, and index must be Some(sample), where sample is the index of the sample to retrieve.

  • If multi is false, then the image may have mipmaps. In this case, index must be Some(level), where level identifies the level of detail. Even if the image has only the full-sized version, level must still be present; its only in-range value is zero.

When index is Some the value must be a Sint scalar value. If it identifes a level of detail, zero represents the full resolution mipmap.

ImageQuery

Query information from an image.

Fields of ImageQuery

image: Handle<Expression>query: ImageQuery

Unary

Apply an unary operator.

Fields of Unary

op: UnaryOperatorexpr: Handle<Expression>

Binary

Apply a binary operator.

Fields of Binary

op: BinaryOperatorleft: 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 of Select

condition: Handle<Expression>

Boolean expression

accept: Handle<Expression>reject: Handle<Expression>

Derivative

Compute the derivative on an axis.

Fields of Derivative

axis: DerivativeAxisexpr: Handle<Expression>

Relational

Call a relational function.

Fields of Relational

fun: RelationalFunctionargument: Handle<Expression>

Math

Call a math function

Fields of Math

fun: MathFunctionarg: Handle<Expression>arg1: Option<Handle<Expression>>arg2: Option<Handle<Expression>>

As

Cast a simple type to another kind.

Fields of As

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.

Tuple Fields of CallResult

0: Handle<Function>

AtomicResult

Result of an atomic operation.

Fields of AtomicResult

kind: ScalarKindwidth: Bytescomparison: bool

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.

Tuple Fields of ArrayLength

0: Handle<Expression>

Implementations

impl Expression

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

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