Struct GlTexture 

pub struct GlTexture {
    pub texture: WebGlTexture,
    pub width: u32,
    pub height: u32,
    pub levels: u32,
    pub mipmapped: bool,
}

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.

Fields

texture: WebGlTexture

The GL texture object.

width: u32

The width in texels the texture was allocated with.

height: u32

The height in texels the texture was allocated with.

levels: u32

The number of mip levels allocated.

mipmapped: bool

Whether generateMipmap was called, so a minification filter that samples across levels is known to be legal.

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_width(&self) -> u32

pub fn get_height(&self) -> u32

pub fn get_levels(&self) -> u32

pub fn get_mipmapped(&self) -> bool

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.