Struct GlTexture 

pub struct GlTexture { /* private fields */ }

A GPU texture holding sampled image data or render-target contents.

Carries the dimensions and mip count the driver was told about so a resize re-allocates instead of stretching stale texels, and records whether a mip chain exists so a caller cannot accidentally select a minification filter that samples across levels the texture does not have, which samples as solid black and is the single most common “my texture is invisible” WebGL bug.

Implementations

impl GlTexture

Implements texture allocation, DOM-source upload, sampling state, and release.

Performance

Wrap and filter are set once by GlTexture::set_parameters and never re-issued per frame, and a freshly created texture is pinned to a single-level LINEAR minification filter because GL’s own default is mip-aware: a texture with no mip chain sampled under LINEAR_MIPMAP_LINEAR is incomplete and reads as solid black.

pub fn create( context: &WebGl2RenderingContext, width: u32, height: u32, format: GpuTextureFormat, pixels: &[u8], ) -> Option<GlTexture>

Allocates a texture and uploads pixels into its base mip level.

pixels is a tightly packed width * height * 4 RGBA byte slice. Pass an empty slice to allocate storage without initializing it, which is what a render target wants; the contents are then undefined until something is drawn into or uploaded onto them.

Arguments

• &WebGl2RenderingContext - The context to allocate against.
• u32 - The width in texels.
• u32 - The height in texels.
• GpuTextureFormat - The texel format.
• &[u8] - The tightly packed RGBA pixels, or empty.

Returns

• Option<GlTexture> - The allocated texture, or None when the driver refused to create one.

pub fn create_from_image( context: &WebGl2RenderingContext, image: &HtmlImageElement, format: GpuTextureFormat, ) -> Option<GlTexture>

Uploads a decoded DOM image into a fresh texture, sized to the image’s own dimensions.

The image is flipped on upload, because a DOM image’s origin is at the top left while GL’s texture origin is at the bottom left. Flipping here rather than negating a v coordinate in the shader costs one unpack-time transpose and leaves the sampler state identical to what a raw pixel upload produces.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &HtmlImageElement - The decoded image to upload.
• GpuTextureFormat - The texel format to allocate as.

Returns

• Option<GlTexture> - The uploaded texture, or None when the driver refused to create one.

pub fn create_from_canvas( context: &WebGl2RenderingContext, canvas: &HtmlCanvasElement, format: GpuTextureFormat, ) -> Option<GlTexture>

Uploads another canvas element into a fresh texture, sized to that canvas’s dimensions.

This is the cheapest path from runtime-generated art to a sampled surface: a 2D context draws into the source canvas, and one texImage2D copies the result into the texture with no CPU round trip. The canvas is not flipped, because a 2D canvas is already addressed with a bottom-left origin in drawImage’s coordinate system.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &HtmlCanvasElement - The source canvas to upload.
• GpuTextureFormat - The texel format to allocate as.

Returns

• Option<GlTexture> - The uploaded texture, or None when the driver refused to create one.

pub fn create_from_bitmap( context: &WebGl2RenderingContext, bitmap: &Object, width: u32, height: u32, format: GpuTextureFormat, ) -> Option<GlTexture>

Uploads an ImageBitmap into a fresh texture, sized to the bitmap’s dimensions.

The bitmap is reached through a cached texImage2D method reference rather than a typed web-sys overload, so the module does not have to enable the ImageBitmap feature for a single call. The method is looked up once per wasm instance and reused on every later upload, so the steady-state cost matches a typed binding’s. The bitmap is flipped, exactly as for a DOM image.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &Object - The ImageBitmap to upload.
• u32 - The bitmap’s width in pixels.
• u32 - The bitmap’s height in pixels.
• GpuTextureFormat - The texel format to allocate as.

Returns

• Option<GlTexture> - The uploaded texture, or None when the driver refused to create one or the upload threw.

pub fn set_parameters( &self, context: &WebGl2RenderingContext, filter: FilterMode, mipmap: MipmapFilter, address: AddressMode, )

Sets the wrap and filter modes the texture is sampled with.

Four texParameteri calls, issued once at setup. The minification filter folds in the mip decision, so selecting a MipmapFilter the texture does not have requires a prior GlTexture::generate_mipmap; without the chain the texture is incomplete and samples as solid black.

Arguments

• &WebGl2RenderingContext - The context to configure against.
• FilterMode - The interpolation mode within one mip level.
• MipmapFilter - How two adjacent mip levels are combined.
• AddressMode - What sampling does outside [0, 1].

pub fn generate_mipmap( &mut self, context: &WebGl2RenderingContext, filter: FilterMode, mipmap: MipmapFilter, address: AddressMode, )

Builds the full mip chain and switches the texture to a mip-aware minification filter.

Required before any filter that samples across levels: a texture with a mip-aware min filter and no chain is incomplete, and an incomplete texture samples as solid black. Costs a full-texture-sized pass, so it belongs at load time rather than in a per-frame path.

Arguments

• &WebGl2RenderingContext - The context to generate against.
• FilterMode - The interpolation mode within one mip level.
• MipmapFilter - How two adjacent mip levels are combined.
• AddressMode - What sampling does outside [0, 1].

pub fn update( &self, context: &WebGl2RenderingContext, region: &GlScissor, format: GpuTextureFormat, data: &[u8], ) -> bool

Writes a sub-rectangle of the texture without re-allocating it.

The write is rejected when the rectangle falls outside the texture, so a caller cannot drive the driver past its own allocation. The rectangle is assumed to match the given format, which is the same assumption every sub-image call makes.

The rectangle is carried as a GlScissor rather than as four loose arguments because its bounds are checked against the texture’s own dimensions: passing the box as one value is what makes it a single value to compare, rather than four independently-supplied edges that could disagree.

Arguments

• &WebGl2RenderingContext - The context to upload through.
• &GlScissor - The sub-rectangle, in texels, whose top-left is the origin.
• GpuTextureFormat - The texel format data is laid out in.
• &[u8] - The tightly packed pixels for the sub-rectangle.

Returns

• bool - true when the write was issued, false when the rectangle fell outside the texture.

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

Releases the texture’s driver-side storage and marks the wrapper empty.

The dimensions are zeroed so a stale size can never be mistaken for a live allocation by a later sub-image write.

Arguments

• &WebGl2RenderingContext - The context to release against.

impl GlTexture

pub fn get_texture(&self) -> &WebGlTexture

pub fn get_mut_texture(&mut self) -> &mut WebGlTexture

pub fn set_texture(&mut self, val: WebGlTexture) -> &mut Self

pub fn get_width(&self) -> u32

pub fn get_mut_width(&mut self) -> &mut u32

pub fn set_width(&mut self, val: u32) -> &mut Self

pub fn get_height(&self) -> u32

pub fn get_mut_height(&mut self) -> &mut u32

pub fn set_height(&mut self, val: u32) -> &mut Self

pub fn get_levels(&self) -> u32

pub fn get_mut_levels(&mut self) -> &mut u32

pub fn set_levels(&mut self, val: u32) -> &mut Self

pub fn get_mipmapped(&self) -> bool

pub fn get_mut_mipmapped(&mut self) -> &mut bool

pub fn set_mipmapped(&mut self, val: bool) -> &mut Self

Trait Implementations

impl Clone for GlTexture

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 GlTexture

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

Formats the value using the given formatter.