Struct GlProgram 

pub struct GlProgram { /* private fields */ }

A linked GLSL program together with its cached uniform locations.

Uniform locations are stable for the lifetime of a linked program, but resolving one costs a round trip into the GL frontend that walks the program’s uniform table. Caching them in a name-keyed map means a per-frame set_uniform_1f is a hash lookup plus the upload with no re-resolution, and a name the GLSL compiler optimized out caches the None so the miss is paid exactly once rather than every frame.

Implementations

impl GlProgram

Implements shader compilation, program linking, and cached uniform upload.

Performance

Every uniform name this program has ever been asked about is resolved exactly once and cached, including the negative result for a name the GLSL compiler optimized out. A per-frame set_uniform_1f is therefore a hash lookup plus the upload, with no trip into the GL frontend’s uniform table. Matrix uploads additionally go through a fixed-size stack array rather than a heap one, so uploading a Matrix4x4 costs no allocation on any frame, including the first.

pub fn create( context: &WebGl2RenderingContext, vertex_source: &str, fragment_source: &str, ) -> Result<GlProgram, WebGlProgramError>

Compiles and links a vertex and fragment shader into a program.

Both shader objects are deleted once linking succeeds, since the program keeps the compiled code and the shader objects are pure intermediate products. On failure the browser’s info log is returned verbatim, because a GLSL diagnostic is only actionable in the driver’s own wording.

Arguments

• &WebGl2RenderingContext - The context to compile against.
• &str - The vertex shader source.
• &str - The fragment shader source.

Returns

• Result<GlProgram, WebGlProgramError> - The linked program with an empty uniform cache, or the compile and link info log.

pub fn bind(&self, context: &WebGl2RenderingContext)

Makes the program current, so subsequent uniform writes and draws target it.

Arguments

• &WebGl2RenderingContext - The context to bind against.

pub fn uniform( &mut self, context: &WebGl2RenderingContext, name: &str, ) -> Option<WebGlUniformLocation>

Resolves a uniform’s location once and caches it, including the case where the GLSL compiler removed the uniform entirely.

Caching the None matters as much as caching the location: a uniform the compiler optimized out is the common case for a per-feature flag, and re-querying it every frame would walk the program’s uniform table for a result that can never change.

Arguments

• &WebGl2RenderingContext - The context to resolve against.
• &str - The uniform name, with an explicit [0] index for array uniforms per the getUniformLocation spec.

Returns

• Option<WebGlUniformLocation> - The location, or None when the uniform does not exist in the program.

pub fn set_uniform_1f( &mut self, context: &WebGl2RenderingContext, name: &str, value: f32, )

Uploads a float uniform through its cached location.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name.
• f32 - The value to upload.

pub fn set_uniform_2f( &mut self, context: &WebGl2RenderingContext, name: &str, x: f32, y: f32, )

Uploads a vec2 uniform through its cached location.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name.
• f32 - The x component.
• f32 - The y component.

pub fn set_uniform_3f( &mut self, context: &WebGl2RenderingContext, name: &str, x: f32, y: f32, z: f32, )

Uploads a vec3 uniform through its cached location.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name.
• f32 - The x component.
• f32 - The y component.
• f32 - The z component.

pub fn set_uniform_4f( &mut self, context: &WebGl2RenderingContext, name: &str, x: f32, y: f32, z: f32, w: f32, )

Uploads a vec4 uniform through its cached location.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name.
• f32 - The x component.
• f32 - The y component.
• f32 - The z component.
• f32 - The w component.

pub fn set_uniform_mat4( &mut self, context: &WebGl2RenderingContext, name: &str, matrix: &Matrix4x4, )

Uploads a mat4 uniform from the engine’s Matrix4x4, with no allocation.

This is the single most important primitive the WebGL path was missing: the engine’s matrices are f64 and GL’s uniforms are f32, so every upload needs a conversion, and doing that into a freshly allocated Vec would put a heap allocation in the middle of the draw path. The conversion goes through a fixed-size stack array, so it is a sixteen-element copy into memory that already exists.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name.
• &Matrix4x4 - The matrix to upload.

pub fn set_uniform_vec4_array( &mut self, context: &WebGl2RenderingContext, name: &str, data: &[f32], )

Uploads a flat vec4 array uniform from a caller-owned slice.

The slice is handed to the driver directly, so there is no staging copy and no allocation: the only cost is the borrow for the duration of the call. data.len() should be a multiple of four, since a vec4 array element is four floats; a length that is not is the caller’s bug, and GL rejects it.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &str - The uniform name, with an explicit [0] index.
• &[f32] - The packed float data.

pub fn bind_uniform_block( &mut self, context: &WebGl2RenderingContext, name: &str, binding: u32, ) -> bool

Points a named uniform block at a binding index, and caches the block’s index so the lookup happens once.

The driver’s answer for a block name the program does not declare is UNIFORM_BLOCK_INDEX, which is not a valid index. That negative result is deliberately not cached: a miss here usually means the shader changed under the program, and caching it would make the mismatch permanent rather than recoverable on the next call.

Arguments

• &WebGl2RenderingContext - The context to bind against.
• &str - The block name as written in the shader.
• u32 - The binding point the block should read from.

Returns

• bool - true when the block exists and was bound.

pub fn delete(&mut self, context: &WebGl2RenderingContext)

Releases the program and drops its uniform cache.

Arguments

• &WebGl2RenderingContext - The context to release against.

impl GlProgram

pub fn get_program(&self) -> &WebGlProgram

pub fn get_mut_program(&mut self) -> &mut WebGlProgram

pub fn set_program(&mut self, val: WebGlProgram) -> &mut Self

pub fn get_uniforms(&self) -> HashMap<String, Option<WebGlUniformLocation>>

pub fn get_mut_uniforms( &mut self, ) -> &mut HashMap<String, Option<WebGlUniformLocation>>

pub fn set_uniforms( &mut self, val: HashMap<String, Option<WebGlUniformLocation>>, ) -> &mut Self

pub fn get_matrix_scratch(&self) -> &[f32; 16]

pub fn get_mut_matrix_scratch(&mut self) -> &mut [f32; 16]

pub fn set_matrix_scratch(&mut self, val: [f32; 16]) -> &mut Self

pub fn get_blocks(&self) -> HashMap<String, u32>

pub fn get_mut_blocks(&mut self) -> &mut HashMap<String, u32>

pub fn set_blocks(&mut self, val: HashMap<String, u32>) -> &mut Self

Trait Implementations

impl Clone for GlProgram

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for GlProgram

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

Formats the value using the given formatter.