Struct web_glitz::image::texture_2d_array::Texture2DArray

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

Layered image storage for the (partial or complete) mipmap chain of an array of 2-dimensional images.

A Texture2DArray is a layered image and has a width, a height and a depth; depth here corresponds to the length of the array (see also the "Layered Image" section below). A Texture2DArray defines a TextureFormat F: all image data stored in the texture is stored in this format.

See [RenderingContext::create_texture_2d_array] for details on how a Texture2DArray is created.

Layered Image

Although the name might imply that a Texture2DArray should be thought of as an array of 2-dimensional images, the semantics chosen for this API instead consider a Texture2DArray to be a single "layered" image (much like a [Texture3D], with which the Texture2DArray API shares many commonalities). The module documentation for [web_glitz::image] goes into more detail on layered image storage.

These semantics make certain operations more intuitive. It is for example possible to upload the image data for an entire mipmap Level at once from a single LayeredImageSource (see Level::upload_command). It is also possible to first select a sub-image of a mipmap Level (see Level::sub_image) and then upload data to only a sub-region of each layer (see LevelSubImage::upload_command).

Mipmap

A Texture2DArray stores a partial or complete mipmap chains its layered base image (or, if you prefer, it stores an array of mipmap chains for each of its 2-dimensional base images). See the module documentation for [web_glitz::image] for more information on mipmaps.

Note that a Texture2DArray 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 Texture2DArray::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 [Texture2DArray::generate_mipmap] (see [Texture2DArray::generate_mipmap] for details).

Sampling

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

Example

The following example creates a 2d array texture with a width of 256 pixels, a height of 256 and a depth of 16 layers 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::{LayeredImageSource, MipmapLevels};
use web_glitz::image::format::RGB8;
use web_glitz::image::texture_2d_array::Texture2DArrayDescriptor;
use web_glitz::sequence_all;

let texture = context.try_create_texture_2d_array(&Texture2DArrayDescriptor {
    format: RGB8,
    width: 256,
    height: 256,
    depth: 16,
    levels: MipmapLevels::Complete
}).unwrap();

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

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

Implementations

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

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

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

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

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

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

Returns a reference to the levels of this Texture2DArray.

See also Texture2DArray::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 Texture2DArray.

See also Texture2DArray::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 width(&self) -> u32

The width of this Texture2DArray.

pub fn height(&self) -> u32

The height of this Texture2DArray.

pub fn depth(&self) -> u32

The depth of this Texture2DArray.

impl<F> Texture2DArray<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 Texture2DArray.

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_array]) 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> Texture2DArray<F> where
    F: TextureFormat + FloatSamplable + 'static, 

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

Combines this Texture2DArray with the sampler as a FloatSampledTexture2DArray, 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> Texture2DArray<F> where
    F: TextureFormat + IntegerSamplable + 'static, 

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

Combines this Texture2DArray with the sampler as a IntegerSampledTexture2DArray, 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> Texture2DArray<F> where
    F: TextureFormat + UnsignedIntegerSamplable + 'static, 

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

Combines this Texture2DArray with the sampler as a UnsignedIntegerSampledTexture2DArray, 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> Texture2DArray<F> where
    F: TextureFormat + ShadowSamplable + 'static, 

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

Combines this Texture2DArray with the shadow_sampler as a ShadowSampledTexture2DArray, 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 Texture2DArray<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<Texture2DArray<F>> for Texture2DArray<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 !=.