Struct tetra::graphics::Shader

pub struct Shader { /* fields omitted */ }

A shader program, consisting of a vertex shader and a fragment shader.

Data Format

Shaders are written using GLSL.

Vertex Shaders

Vertex shaders take in data via three attributes:

• a_position - A vec2 representing the position of the vertex in world space.
• a_uv - A vec2 representing the texture co-ordinates that are associated with the vertex.
• a_color - A vec4 representing the color of the vertex. This will be multiplied by u_diffuse and the color sampled from u_texture (see ‘Uniforms’ below).

Position data should be output as a vec4 to the built-in gl_Position variable.

Fragment Shaders

Color data should be output as a vec4 to the first output of the shader. This can be the built-in gl_FragColor variable, if you so desire.

Uniforms

By default, the shader is provided with three uniform variables:

• u_projection - A mat4 which can be used to translate world space co-ordinates into screen space.
• u_texture - A sampler2D which can be used to access color data from the currently active texture.
• u_diffuse - A vec4 representing the color of the current geometry. This is currently only used to pass through the DrawParams::color for a Mesh, and will otherwise be set to Color::WHITE.

You can also set data into your own uniform variables via the set_uniform method.

Bear in mind that there is a hardware-defined limit on how many uniform locations can be used per shader. OpenGL 3.0 guarantees there will be at least 1024 of these locations available, which sounds like a lot - however, some types can use up multiple locations (e.g. a vec2 uses 2, a mat4 uses 16, an array of 4 mat4s uses 64, and so on).

Performance

Creating a shader is quite an expensive operation, as it involves parsing and validating the GLSL code. Try to reuse shaders, rather than recreating them every frame.

You can clone a shader cheaply, as it is a reference-counted handle to a GPU resource. However, this does mean that modifying a shader (e.g. setting a uniform) will also affect any clones that exist of it.

Examples

The shaders example demonstrates how to draw using a custom shader, supplying inputs via uniform variables.

Implementations

impl Shader

pub fn new<P>(
    ctx: &mut Context,
    vertex_path: P,
    fragment_path: P
) -> Result<Shader> where
    P: AsRef<Path>, 

Creates a new shader program from the given files.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::FailedToLoadAsset will be returned if the files could not be loaded.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn from_vertex_file<P>(ctx: &mut Context, path: P) -> Result<Shader> where
    P: AsRef<Path>, 

Creates a new shader program from the given vertex shader file.

The default fragment shader will be used.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::FailedToLoadAsset will be returned if the file could not be loaded.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn from_fragment_file<P>(ctx: &mut Context, path: P) -> Result<Shader> where
    P: AsRef<Path>, 

Creates a new shader program from the given fragment shader file.

The default vertex shader will be used.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::FailedToLoadAsset will be returned if the file could not be loaded.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn from_string(
    ctx: &mut Context,
    vertex_shader: &str,
    fragment_shader: &str
) -> Result<Shader>

Creates a new shader program from the given strings.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn from_vertex_string(ctx: &mut Context, shader: &str) -> Result<Shader>

Creates a new shader program from the given vertex shader string.

The default fragment shader will be used.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn from_fragment_string(ctx: &mut Context, shader: &str) -> Result<Shader>

Creates a new shader program from the given fragment shader string.

The default vertex shader will be used.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::InvalidShader will be returned if the shader could not be compiled.

pub fn set_uniform<V>(&self, ctx: &mut Context, name: &str, value: V) where
    V: UniformValue, 

Sets the value of the specifed uniform parameter.

See the UniformValue trait’s docs for a list of which types can be used as a uniform, and what their corresponding GLSL types are.

Trait Implementations

impl Clone for Shader

fn clone(&self) -> Shader

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Shader

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

Formats the value using the given formatter.

impl PartialEq<Shader> for Shader

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

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

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

This method tests for !=.

impl StructuralPartialEq for Shader