Struct shades::Scope

pub struct Scope<R> { /* fields omitted */ }

Lexical scope that must output a R.

Scopes are the only way to add control flow expressions to shaders. Scope<R> is the most general one, parent of all scopes. Depending on the kind of control flow, several kind of scopes are possible:

• Scope<R> is the most general one and every scopes share its features.
• EscapeScope<R> is a special kind of Scope<R> that allows escaping from anywhere in the scope.
• LoopScope<R> is a special kind of EscapeScope<R> that also allows to escape local looping expressions, such as for and while loops.

A Scope<R> allows to perform a bunch of actions:

• Creating variable via Scope::var. Expressions of type Expr<T> where T: ToType are bound in a Scope<R> via Scope::var and a Var<T> is returned, representing the bound variable.
• Variable mutation via Scope::set. Any Var<T> declared previously and still reachable in the current Scope can be mutated.
• Introducing conditional statements with Scope::when and Scope::unless.
• Introducing looping statements with Scope::loop_for and Scope::loop_while.

Implementations

impl<R> Scope<R> where
    Return: From<R>, 

pub fn var<T>(&mut self, init_value: impl Into<Expr<T>>) -> Var<T> where
    T: ToType, 

Bind an expression to a variable in the current scope.

let v = s.var(e); binds the e expression to v in the s Scope<T>, and e must have type Expr<T> and v must be a Var<T>, with T: ToType.

Return

The resulting Var<T> contains the representation of the binding in the EDSL and the actual binding is recorded in the current scope.

Examples

let v = s.var(3.1415); // assign the literal 3.1415 to v
let q = s.var(v * 2.); // assign v * 2. to q

pub fn loop_for<T>(
    &mut self,
    init_value: impl Into<Expr<T>>,
    condition: impl FnOnce(&Expr<T>) -> Expr<bool>,
    iter_fold: impl FnOnce(&Expr<T>) -> Expr<T>,
    body: impl FnOnce(&mut LoopScope<R>, &Expr<T>)
) where
    T: ToType, 

For looping statement — for.

s.loop_for(i, |i| /* cond */, |i| /* fold */, |i| /* body */ ) inserts a looping statement into the EDSL representing a typical “for” loop. i is an Expr<T> satisfying T: ToType and is used as initial value.

In all the following closures, i refers to the initial value.

The first cond closure must return an Expr<bool>, representing the condition that is held until the loop exits. The second fold closure is a pure computation that must return an Expr<T> and that will be evaluated at the end of each iteration before the next check on cond. The last and third body closure is the body of the loop.

The behaviors of the first two closures is important to understand. Those are akin to filtering and folding. The closure returning the Expr<bool> is given the Expr<T> at each iteration and the second closure creates the new Expr<T> for the next iteration. Normally, people are used to write this pattern as i++, for instance, but in the case of our EDSL, it is more akin go i + 1, and this value is affected to a local accumulator hidden from the user.

The LoopScope<R> argument to the body closure is a specialization of Scope<R> that allows breaking out of loops.

Examples

use shades::{CanEscape as _, LoopScope, Scope, ShaderBuilder};

ShaderBuilder::new_vertex_shader(|mut s, vertex| {
  s.main_fun(|s: &mut Scope<()>| {
    s.loop_for(0, |i| i.lt(10), |i| i + 1, |s: &mut LoopScope<()>, i| {
      s.when(i.eq(5), |s: &mut LoopScope<()>| {
        // when i == 5, abort from the main function
        s.abort();
      });
    });
  })
});

pub fn loop_while(
    &mut self,
    condition: impl Into<Expr<bool>>,
    body: impl FnOnce(&mut LoopScope<R>)
)

While looping statement — while.

s.loop_while(cond, body) inserts a looping statement into the EDSL representing a typical “while” loop.

cond is an Expr<bool>, representing the condition that is held until the loop exits. body is the content the loop will execute at each iteration.

The LoopScope<R> argument to the body closure is a specialization of Scope<R> that allows breaking out of loops.

Examples

use shades::{CanEscape as _, LoopScope, Scope, ShaderBuilder};

ShaderBuilder::new_vertex_shader(|mut s, vertex| {
  s.main_fun(|s: &mut Scope<()>| {
    let i = s.var(10);

    s.loop_while(i.lt(10), |s| {
      s.set(&i, &i + 1);
    });
  })
});

pub fn set<T>(&mut self, var: impl Into<Var<T>>, value: impl Into<Expr<T>>)

Mutate a variable in the current scope.

Examples

let v = s.var(1); // v = 1
s.set(&v, 10); // v = 10

Trait Implementations

impl<R> CanEscape<R> for Scope<R> where
    Return: From<R>, 

type InnerScope = EscapeScope<R>

Scope type inside the scope of the conditional.

fn when<'a>(
    &'a mut self,
    condition: impl Into<Expr<bool>>,
    body: impl FnOnce(&mut Self::InnerScope)
) -> When<'a, R>

Conditional statement — if.

fn unless<'a>(
    &'a mut self,
    condition: impl Into<Expr<bool>>,
    body: impl FnOnce(&mut Self::InnerScope)
) -> When<'a, R>

Complement form of Scope::when.

impl<R: Debug> Debug for Scope<R>

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

Formats the value using the given formatter.

impl<R> From<EscapeScope<R>> for Scope<R>

fn from(s: EscapeScope<R>) -> Self

Performs the conversion.

impl<R> From<LoopScope<R>> for Scope<R>

fn from(s: LoopScope<R>) -> Self

Performs the conversion.