Struct web_glitz::image::texture_3d::Texture3D

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

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

A Texture3D is a layered image and has a width, a height and a depth; depth here corresponds to the number of layers (the module documentation for [web_glitz::image] goes into more detail on layered image storage). A Texture3D defines a TextureFormat F: all image data stored in the texture is stored in this format.

See [RenderingContext::create_texture_3d] for details on how a Texture3D is created.

Mipmap

A Texture3D 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 Texture3D 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 Texture3D::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 [Texture3D::generate_mipmap] (see [Texture3D::generate_mipmap] for details).

Sampling

The GPU may access the data in a Texture3D, typically through a [Sampler] or [ShadowSampler], see [Texture3D::sampled_float], [Texture3D::sampled_integer], [Texture3D::sampled_unsigned_integer] and [Texture3D::sampled_shadow]. A sampled Texture3D 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_3d::Texture3DDescriptor;
use web_glitz::sequence_all;

let texture = context.try_create_texture_3d(&Texture3DDescriptor {
    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> Texture3D<F> where
    F: TextureFormat + 'static, 

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

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

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

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

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

Returns a reference to the levels of this Texture3D.

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

See also Texture3D::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 Texture3D

pub fn width(&self) -> u32

The width of this Texture3D.

pub fn height(&self) -> u32

The height of this Texture3D.

pub fn depth(&self) -> u32

The depth of this Texture3D.

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

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

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

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

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

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

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

Combines this Texture3D with the sampler as a UnsignedIntegerSampledTexture3D, 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.

Trait Implementations

impl<F> Hash for Texture3D<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<Texture3D<F>> for Texture3D<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 !=.