std::screen::shader

Stability: Tentative — shader roles, typed shader arguments, and the effect values the screen holds: filters, mixes, masks, paints and motions.

A shader is a WGSL file (.wgsl) that the renderer runs on the GPU. Every shader has one of six roles, and the type of its asset constant states the role and the type of its arguments:

use std::screen::shader::{ColorShader, filter};

#[shader_arg]
struct Memory {
    strength: Decimal,
}

const MEMORY: ColorShader<Memory> = asset("memory.wgsl");

A shader is never put on the screen alone. A constructor of this module pairs it with its arguments into an effect value, and the screen holds effect values:

The constructors take the arguments with the shader’s argument type A, so a shader cannot be given arguments of another type, and a shader of one role cannot be used where another role is expected. Effect values hide their fields; the constructors are the only way to build them.

Effect values are Eq: two effects are equal when they use the same shader file with equal arguments. They are part of the logical screen, so two screens whose filters differ only in an argument are different screens. Shader types and effect values are not finite.

std ships ready-made shaders in std::shaders. How to write a shader of each role, the argument layout, and the time a shader sees are described in Writing Shaders. Nothing of this module is in the prelude; import it with use std::screen::shader::….

Overview

Trait: ShaderArg

#[builtin] pub trait ShaderArg {}

The types a shader can take as its arguments: the unit type () and every struct marked #[shader_arg]. The compiler implements it; a game cannot. A #[shader_arg] struct has named fields of the types listed in Arguments.

Trait: Shader

#[builtin] pub trait Shader {}

The six shader asset types below.

Struct: ColorShader<A>

#[builtin] pub struct ColorShader<A>;
impl<A> Asset for ColorShader<A> {}
impl<A> Eq for ColorShader<A> {}
impl<A> Shader for ColorShader<A> {}

A WGSL file that recolours what is drawn below it, with arguments of type A; used by filter. Declared with asset("….wgsl").

Struct: MixShader<A>

#[builtin] pub struct MixShader<A>;
impl<A> Asset for MixShader<A> {}
impl<A> Eq for MixShader<A> {}
impl<A> Shader for MixShader<A> {}

A WGSL file that composites an entity over what is below it; used by mix.

Struct: TextureShader<A>

#[builtin] pub struct TextureShader<A>;
impl<A> Asset for TextureShader<A> {}
impl<A> Eq for TextureShader<A> {}
impl<A> Shader for TextureShader<A> {}

A WGSL file that generates image content; used by paint.

Struct: MaskShader<A>

#[builtin] pub struct MaskShader<A>;
impl<A> Asset for MaskShader<A> {}
impl<A> Eq for MaskShader<A> {}
impl<A> Shader for MaskShader<A> {}

A WGSL file that computes an alpha value per pixel; used by mask.

Struct: LocalMotionShader<A>

#[builtin] pub struct LocalMotionShader<A>;
impl<A> Asset for LocalMotionShader<A> {}
impl<A> Eq for LocalMotionShader<A> {}
impl<A> Shader for LocalMotionShader<A> {}

A WGSL file that moves an entity around its pose; used by local_motion.

Struct: TransitionalMotionShader<A>

#[builtin] pub struct TransitionalMotionShader<A>;
impl<A> Asset for TransitionalMotionShader<A> {}
impl<A> Eq for TransitionalMotionShader<A> {}
impl<A> Shader for TransitionalMotionShader<A> {}

A WGSL file that moves an entity from one pose to another; used by transitional_motion.

Struct: ShaderArgs

#[builtin] pub struct ShaderArgs;
impl Eq for ShaderArgs {}

Shader arguments with their type erased, as the effect values hold them. Values compare by the arguments they hold. A game never builds one directly.

Struct: Filter

pub struct Filter {
    shader: ShaderAsset,
    args: ShaderArgs,
}

A colour filter: a colour shader with its arguments. A filter recolours what it covers: the Background, Stage and Front planes for the screen filter, the entity for an entity filter.

filter(shader, args)

pub const fn filter<A: ShaderArg>(shader: ColorShader<A>, args: A) -> Filter

• shader ColorShader<A> — the shader.
• args A — its arguments.
• Returns: Filter — the filter shader with args.
• Kind: const fn · Builtin: no.

screen.filter().change(Some(filter(MEMORY, Memory { strength: 0.8 }))).apply_animation(tween(ms(800)));

Struct: Mix

pub struct Mix {
    shader: ShaderAsset,
    args: ShaderArgs,
}

A way to composite an entity over what is below it: a mix shader with its arguments. The shader sees the entity and the backdrop and returns the composited pixel, so blend modes and effects such as frosted glass are mixes.

mix(shader, args)

pub const fn mix<A: ShaderArg>(shader: MixShader<A>, args: A) -> Mix

• Returns: Mix — the mix shader with args.
• Kind: const fn · Builtin: no.

Struct: Mask

pub struct Mask {
    shader: ShaderAsset,
    args: ShaderArgs,
}

An alpha mask: a mask shader with its arguments. The shader returns a value from 0.0 to 1.0 for each pixel of a box. A mask is used in three places:

• Entity::mask: the entity’s alpha is multiplied by the mask over the entity’s box.
• Paint::masked: the paint’s alpha is multiplied by the mask over the paint.
• anim::masked: a transition switches a pixel once the mask’s value is reached by a sweeping threshold.

mask(shader, args)

pub const fn mask<A: ShaderArg>(shader: MaskShader<A>, args: A) -> Mask

• Returns: Mask — the mask shader with args.
• Kind: const fn · Builtin: no.

Struct: Paint

pub struct Paint {
    texture: ShaderAsset,
    args: ShaderArgs,
    size: Size,
    mask: Option<Mask>,
}

Generated image content of size pixels: a texture shader with its arguments, optionally masked. An ImageLayer shows a paint in place of an image with ImageLayer::paint; it is placed, sized, flipped and swapped with transitions like an image of size pixels. Gradients, light spots and weather are paints.

paint(shader, args, size)

pub const fn paint<A: ShaderArg>(shader: TextureShader<A>, args: A, size: Size) -> Paint

• size Size — the size of the content in pixels.
• Returns: Paint — the content shader draws with args, size pixels large, unmasked.
• Kind: const fn · Builtin: no.

paint.masked(mask)

pub const fn masked(mut self, mask: Mask) -> Paint

• Returns: this paint with its alpha multiplied by mask, computed over the paint’s box. A second masked replaces the first mask.
• Kind: const fn · Builtin: no.

use std::screen::{degrees, size};
use std::shaders::mask::rounded_rect;
use std::shaders::texture::linear_gradient;

screen.entity(PANEL).image().paint(linear_gradient(degrees(90.0), WHITE, BLACK, size(400, 300)).masked(rounded_rect(32.0, 4.0))).apply_animation(fade(ms(300)));

Enum: LocalMotionBehavior

pub enum LocalMotionBehavior {
    Periodic { after: Duration, period: Duration },
    Stall { after: Duration },
}

How a local motion’s time runs. A local motion shader receives a time t in seconds; the behaviour maps the time since the motion started before the shader sees it:

Periodic { after: ZERO, period } is a plain loop; a non-zero after plays an intro before the loop. Stall suits motions that settle, such as a decaying shake.

Struct: LocalMotion

pub struct LocalMotion {
    shader: ShaderAsset,
    args: ShaderArgs,
    behavior: LocalMotionBehavior,
}

A motion around the entity’s pose: a local motion shader with its arguments and time rule. The shader receives the pose the entity has at that frame (with tweens and Motions applied) and returns the pose to draw. It changes only how the entity is drawn: the logical position, scale and rotation stay.

local_motion(shader, args, behavior)

pub const fn local_motion<A: ShaderArg>(shader: LocalMotionShader<A>, args: A, behavior: LocalMotionBehavior) -> LocalMotion

• behavior LocalMotionBehavior — how the motion’s time runs.
• Returns: LocalMotion — the local motion shader with args, its time mapped by behavior.
• Kind: const fn · Builtin: no.

Struct: TransitionalMotion

pub struct TransitionalMotion {
    shader: ShaderAsset,
    args: ShaderArgs,
    duration: Duration,
    easing: Easing,
    delay: Duration,
}

A path from one pose to another: a transitional motion shader with its arguments and timing. Entity::travel moves an entity along it. The shader receives the start pose, the end pose, the eased progress from 0 to 1 and the time, and returns the pose to draw. When the duration is over, the entity is at the end pose whatever the shader returned.

transitional_motion(shader, args, duration)

pub const fn transitional_motion<A: ShaderArg>(shader: TransitionalMotionShader<A>, args: A, duration: Duration) -> TransitionalMotion

• duration Duration — how long the travel takes.
• Returns: TransitionalMotion — the motion shader with args over duration, with easing Linear and no delay.
• Kind: const fn · Builtin: no.

motion.ease(easing), motion.delay(delay)

pub const fn ease(mut self, easing: Easing) -> TransitionalMotion
pub const fn delay(mut self, delay: Duration) -> TransitionalMotion

ease returns this motion with easing on its progress; delay returns it starting delay after the cursor. The easing is checked like a tween’s: an invalid CubicBezier or Steps(0) is a const-evaluation error. Kind: const fn · Builtin: no.

use std::screen::{degrees, pose};
use std::screen::anim::Easing;
use std::shaders::motion::arc;

screen.entity(BIRD).travel(pose(point(900, 400), 1.0, degrees(0.0)), arc(200.0, ms(1200)).ease(Easing::OutQuad));