pub struct Shader { /* private fields */ }
Expand description
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
- Avec2
representing the position of the vertex in world space.a_uv
- Avec2
representing the texture co-ordinates that are associated with the vertex.a_color
- Avec4
representing the color of the vertex. This will be multiplied byu_diffuse
and the color sampled fromu_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
- Amat4
which can be used to translate world space co-ordinates into screen space.u_texture
- Asampler2D
which can be used to access color data from the currently active texture.u_diffuse
- Avec4
representing the color of the current geometry. This is currently only used to pass through theDrawParams::color
for aMesh
, and will otherwise be set toColor::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 mat4
s 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
sourceimpl Shader
impl Shader
sourcepub fn new<P>(
ctx: &mut Context,
vertex_path: P,
fragment_path: P
) -> Result<Shader> where
P: AsRef<Path>,
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.
sourcepub fn from_vertex_file<P>(ctx: &mut Context, path: P) -> Result<Shader> where
P: AsRef<Path>,
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.
sourcepub fn from_fragment_file<P>(ctx: &mut Context, path: P) -> Result<Shader> where
P: AsRef<Path>,
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.
sourcepub fn from_string(
ctx: &mut Context,
vertex_shader: &str,
fragment_shader: &str
) -> Result<Shader>
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.
sourcepub fn from_vertex_string(ctx: &mut Context, shader: &str) -> Result<Shader>
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.
sourcepub fn from_fragment_string(ctx: &mut Context, shader: &str) -> Result<Shader>
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.
sourcepub fn set_uniform<V>(&self, ctx: &mut Context, name: &str, value: V) where
V: UniformValue,
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 StructuralPartialEq for Shader
Auto Trait Implementations
impl !RefUnwindSafe for Shader
impl !Send for Shader
impl !Sync for Shader
impl Unpin for Shader
impl !UnwindSafe for Shader
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more