Struct web_glitz::image::texture_2d::Texture2D

pub struct Texture2D<F> { /* fields omitted */ }

Image storage for the (partial or complete) mipmap chain of a single 2-dimensional image.

See [RenderingContext::create_texture_2d] for details on how a Texture2D is created.

Mipmap

A Texture2D stores a partial or complete mipmap chain for a single 2-dimensional base image. See the module documentation for [web_glitz::image] for more information on mipmaps.

Note that a Texture2D does not necessarily have to store a complete mipmap chain, it may only store a partial mipmap chain. For example, it may only store the first three levels (see MipmapLevels for details). However, it must store at least the first level: level 0, the base level (see Texture2D::base_level).

Each image in the chain initially starts out in a "cleared" state, where each bit is set to 0 (note that "zeroed data" is valid data for all TextureFormats).

Mipmapping is typically used with minification filtering, in which case each level in the chain is typically a down-filtered version of the previous level (see [MinificationFilter] for details). If the texture format implements Filterable, then the image data for such a chain may be generated by first uploading data for the base level, and then generating the subsequent levels with [Texture2D::generate_mipmap] (see [Texture2D::generate_mipmap] for details). Image data may also be uploaded to each level individually.

Sampling

The GPU may access the data in a Texture2D through a [Sampler] or ShadowSampler, see [Texture2D::sampled_float], [Texture2D::sampled_integer], [Texture2D::sampled_unsigned_integer] and [Texture2D::sampled_shadow]. A sampled Texture2D may be bound to a pipeline as a resource, see [web_glitz::pipeline::resources::Resources].

Example

The following example creates a 2d texture with a width of 256 pixels and a height of 256 pixels stored in the [RGB8] format, with a complete mipmap chain. All pixels in the base image are set to [255, 0, 0] (red) with an "upload" command and then the pixel data for all other levels is generated with a "generate mipmap" command:

use web_glitz::image::{Image2DSource, MipmapLevels};
use web_glitz::image::format::RGB8;
use web_glitz::image::texture_2d::Texture2DDescriptor;
use web_glitz::sequence_all;

let texture = context.try_create_texture_2d(&Texture2DDescriptor {
    format: RGB8,
    width: 256,
    height: 256,
    levels: MipmapLevels::Complete
}).unwrap();

let pixels: Vec<[u8; 3]> = vec![[255, 0, 0]; 256 * 256];
let data = Image2DSource::from_pixels(pixels, 256, 256).unwrap();

context.submit(sequence_all![
    texture.base_level().upload_command(data),
    texture.generate_mipmap_command(),
]);

Implementations

impl<F> Texture2D<F> where
    F: TextureFormat + 'static, 

pub fn base_level(&self) -> Level<'_, F>

Returns a reference to the base mipmap level for this Texture2D (level 0).

pub fn base_level_mut(&mut self) -> LevelMut<'_, F>

Returns a reference to the base mipmap level for this Texture2D (level 0).

pub fn levels(&self) -> Levels<'_, F>

Returns a reference to the levels of this Texture2D.

See also Texture2D::levels_mut.

Examples

// Returns a reference to mipmap level 2 if the texture has a level 2, or None otherwise:
let level_2 = texture.levels().get(2);

// We can also iterate over references to all levels that exist for the texture:
for level in texture.levels().iter() {
    let index = level.level();
    let width = level.width();
    let height = level.height();

    println!("Level {} has a width of {} and height of {}!", index, width, height);
}

pub fn levels_mut(&mut self) -> LevelsMut<'_, F>

Returns a mutable reference to the levels of this Texture2D.

See also Texture2D::levels.

Examples

// Returns a mutable reference to mipmap level 2 if the texture has a level 2, or None
// otherwise:
let level_2 = texture.levels_mut().get_mut(2);

pub fn format(&self) -> F

The texture format for this Texture2D

pub fn width(&self) -> u32

The width of this Texture2D.

pub fn height(&self) -> u32

The height of this Texture2D.

impl<F> Texture2D<F> where
    F: TextureFormat + Filterable + 'static, 

pub fn generate_mipmap_command(&self) -> GenerateMipmapCommand

Returns a command which, when executed, will generate new mipmap data for the Texture2D.

This will overwrite the image data for each mipmap level except the base level. Starting at level 1, an image is generated that is half the width and height of the previous level (rounded down), by linear minification filtering of the previous level (see also [MinificationFilter::Linear]); this stops when the maximum level for which storage was allocated when the texture was created (see [RenderingContext::create_texture_2d]) has been overwritten. Note that the base level (level 0) is not modified (rather, it serves as the input for this process).

This operation is only available to a texture if the texture format implements Filterable.

impl<F> Texture2D<F> where
    F: TextureFormat + FloatSamplable + 'static, 

pub fn float_sampled<S>(&self, sampler: S) -> FloatSampledTexture2D<'_> where
    S: CompatibleSampler<F>, 

Combines this Texture2D with the sampler as a FloatSampledTexture2D, which can be bound to a pipeline as a texture resource.

Returns an [IncompatibleSampler] error if the sampler is not compatible with this texture's format.

See also [web_glitz::pipeline::resources::Resources].

Panics

Panics if this texture and the sampler do not belong to the same RenderingContext.

impl<F> Texture2D<F> where
    F: TextureFormat + IntegerSamplable + 'static, 

pub fn integer_sampled<S>(&self, sampler: S) -> IntegerSampledTexture2D<'_> where
    S: CompatibleSampler<F>, 

Combines this Texture2D with the sampler as a IntegerSampledTexture2D, which can be bound to a pipeline as a texture resource.

Returns an [IncompatibleSampler] error if the sampler is not compatible with this texture's format.

See also [web_glitz::pipeline::resources::Resources].

Panics

Panics if this texture and the sampler do not belong to the same RenderingContext.

impl<F> Texture2D<F> where
    F: TextureFormat + UnsignedIntegerSamplable + 'static, 

pub fn unsigned_integer_sampled<S>(
    &self,
    sampler: S
) -> UnsignedIntegerSampledTexture2D<'_> where
    S: CompatibleSampler<F>, 

Combines this Texture2D with the sampler as a UnsignedIntegerSampledTexture2D, which can be bound to a pipeline as a texture resource.

Returns an [IncompatibleSampler] error if the sampler is not compatible with this texture's format.

See also [web_glitz::pipeline::resources::Resources].

Panics

Panics if this texture and the sampler do not belong to the same RenderingContext.

impl<F> Texture2D<F> where
    F: TextureFormat + ShadowSamplable + 'static, 

pub fn shadow_sampled(
    &self,
    shadow_sampler: &ShadowSampler
) -> ShadowSampledTexture2D<'_>

Combines this Texture2D with the shadow_sampler as a ShadowSampledTexture2D, which can be bound to a pipeline as a texture resource.

See also [web_glitz::pipeline::resources::Resources].

Panics

Panics if this texture and the shadow_sampler do not belong to the same RenderingContext.

Trait Implementations

impl<F> Hash for Texture2D<F>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<F> PartialEq<Texture2D<F>> for Texture2D<F>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.