Struct web_glitz::image::texture_cube::TextureCube

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

Image storage for the (partial or complete) mipmap chain of a cube map.

See [RenderingContext::create_texture_cube] for details on how a TextureCube is created.

Cube map

A TextureCube stores 6 2-dimensional images (one for each face of a cube) of the same size (all six images share the same width, and all 6 images share the same height) and the same [InternalFormat]. The six images in the TextureCube are also referred to as its "faces", specifically they are:

• The "positive x" face (see Level::positive_x).
• The "negative x" face (see Level::negative_x).
• The "positive y" face (see Level::positive_y).
• The "negative y" face (see Level::negative_y).
• The "positive z" face (see Level::positive_z).
• The "negative z" face (see Level::negative_z).

Mipmap

A TextureCube stores a partial or complete mipmap chain for the base image for each of its 6 faces. See the module documentation for [web_glitz::image] for more information on mipmaps.

Note that a TextureCube 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 TextureCube::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 levels of the 6 faces, and then generating the subsequent levels with [TextureCube::generate_mipmap] (see [TextureCube::generate_mipmap] for details). Image data may also be uploaded to each level of each face individually.

Sampling

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

Example

The following example creates a cube map texture with a width of 256 pixels and a height of 256 pixels stored in the [RGB8] format, with a complete mipmap chain. Different colors are uploaded to each of the faces in the texture's base level and then image data for the rest of the mipmap levels is generated:

use web_glitz::image::{Image2DSource, MipmapLevels};
use web_glitz::image::format::RGB8;
use web_glitz::image::texture_cube::TextureCubeDescriptor;
use web_glitz::{join_all, sequence_all};

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

let positive_x_pixels: Vec<[u8; 3]> = vec![[255, 0, 0]; 256 * 256];
let positive_x_data = Image2DSource::from_pixels(positive_x_pixels, 256, 256).unwrap();
let negative_x_pixels: Vec<[u8; 3]> = vec![[0, 255, 0]; 256 * 256];
let negative_x_data = Image2DSource::from_pixels(negative_x_pixels, 256, 256).unwrap();
let positive_y_pixels: Vec<[u8; 3]> = vec![[0, 0, 255]; 256 * 256];
let positive_y_data = Image2DSource::from_pixels(positive_y_pixels, 256, 256).unwrap();
let negative_y_pixels: Vec<[u8; 3]> = vec![[255, 255, 0]; 256 * 256];
let negative_y_data = Image2DSource::from_pixels(negative_y_pixels, 256, 256).unwrap();
let positive_z_pixels: Vec<[u8; 3]> = vec![[255, 0, 255]; 256 * 256];
let positive_z_data = Image2DSource::from_pixels(positive_z_pixels, 256, 256).unwrap();
let negative_z_pixels: Vec<[u8; 3]> = vec![[0, 255, 255]; 256 * 256];
let negative_z_data = Image2DSource::from_pixels(negative_z_pixels, 256, 256).unwrap();

context.submit(sequence_all![
    join_all![
        texture.base_level().positive_x().upload_command(positive_x_data),
        texture.base_level().negative_x().upload_command(negative_x_data),
        texture.base_level().positive_y().upload_command(positive_y_data),
        texture.base_level().negative_y().upload_command(negative_y_data),
        texture.base_level().positive_z().upload_command(positive_z_data),
        texture.base_level().negative_z().upload_command(negative_z_data),
    ],
    texture.generate_mipmap_command()
]);

Implementations

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

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

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

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

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

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

Returns a reference to the levels of this TextureCube.

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

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

pub fn width(&self) -> u32

The width of this TextureCube.

pub fn height(&self) -> u32

The height of this TextureCube.

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

This will overwrite the image data for each face in every 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_cube]) 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> TextureCube<F> where
    F: TextureFormat + FloatSamplable + 'static, 

pub fn float_sampled<S, Min, Mag>(
    &self,
    sampler: S
) -> FloatSampledTextureCube<'_> where
    S: Borrow<Sampler<Min, Mag>> + CompatibleSampler<F>, 

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

pub fn integer_sampled<S, Min, Mag>(
    &self,
    sampler: S
) -> IntegerSampledTextureCube<'_> where
    S: Borrow<Sampler<Min, Mag>> + CompatibleSampler<F>, 

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

pub fn unsigned_integer_sampled<S, Min, Mag>(
    &self,
    sampler: S
) -> UnsignedIntegerSampledTextureCube<'_> where
    S: Borrow<Sampler<Min, Mag>> + CompatibleSampler<F>, 

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

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

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