Struct golem::ShaderProgram

pub struct ShaderProgram { /* fields omitted */ }

A GPU program that draws data to the screen

Implementations

impl ShaderProgram

pub fn new(
    ctx: &Context,
    desc: ShaderDescription<'_>
) -> Result<ShaderProgram, GolemError>

Create a shader program with the given ShaderDescription

pub fn is_bound(&self) -> bool

Check if this shader program is currently bound to be operated on

pub fn set_uniform(
    &self,
    name: &str,
    uniform: UniformValue
) -> Result<(), GolemError>

Set a uniform value, assuming the shader is bound by ShaderProgram::bind

pub fn bind(&mut self)

Bind this shader to use it, either to set a uniform or to draw

pub unsafe fn draw(
    &self,
    vb: &VertexBuffer,
    eb: &ElementBuffer,
    range: Range<usize>,
    geometry: GeometryMode
) -> Result<(), GolemError>

Draw the given elements from the element buffer with this shader

The range should fall within the elements of the buffer (which is checked for via an assert!.) The GeometryMode determines what the set of indices produces: triangles consumes 3 vertices into a filled triangle, lines consumes 2 vertices into a thin line, etc.

The ShaderProgram must be bound first, see ShaderProgram::bind.

Safety

The safety concerns to keep in mind:

1. The elements in the ElementBuffer are not checked against the size of the VertexBuffer. If they are illegal indices, this will result in out-of-bounds reads on the GPU and therefore undefined behavior. The caller is responsible for ensuring all elements are valid and in-bounds.

pub fn prepare_draw(
    &self,
    vb: &VertexBuffer,
    eb: &ElementBuffer
) -> Result<(), GolemError>

Set up a VertexBuffer and ElementBuffer to draw multiple times with the same buffers.

The ShaderProgram must be bound first, see ShaderProgram::bind.

See ShaderProgram::draw_prepared to execute the draw calls. If you're only drawing the buffers once before replacing their data, see ShaderProgram::draw.

pub unsafe fn draw_prepared(&self, range: Range<usize>, geometry: GeometryMode)

Draw the given elements from the prepared element buffer with this shader

This relies on the caller having a valid prepared state: see prepare_draw.

Safety

The safety concerns to keep in mind:

1. prepare_draw must be called before this method, and the buffers passed to it must not have their underlying storage changed. Their values can change, but calls to set_data may cause them to expand and move to a new memory location on the GPU, invalidating the cal to preparation. Some calls to set_data are optimized to calls to set_sub_data; do not rely on this implementation detail.
2. No other buffers may be operated on between prepare_draw and draw_prepared. Any calls to set_data or set_sub_data from a buffer that wasn't passed to prepare_draw will result in the wrong buffer being bound when draw_prepared is called.
3. The elements in the prepared buffer must correspond to valid locations within the vertex buffer. See draw for details.
4. This shader must still be bound (see bind)

Trait Implementations

impl Drop for ShaderProgram

fn drop(&mut self)

Executes the destructor for this type.