Struct nannou::wgpu::Texture

pub struct Texture { /* private fields */ }

A convenient wrapper around a handle to a texture on the GPU along with its descriptor.

A texture can be thought of as an image that resides in GPU memory (as opposed to CPU memory).

This type is a thin wrapper around the wgpu crate’s Texture type, but provides access to useful information like size, format, usage, etc.

Implementations

impl Texture

pub fn from_path<T, P>(src: T, path: P) -> Result<Texture, ImageError>

where T: WithDeviceQueuePair, P: AsRef<Path>,

Load an image from the given path and upload it as a texture.

The device and queue src can be either the App, a Window, a wgpu::DeviceQueuePair or a tuple (&wgpu::Device, &mut wgpu::Queue). Access to a Device is necessary in order to create the texture and buffer GPU resources, and access to a Queue is necessary for submitting the commands responsible for copying the buffer contents to the texture. Note that a texture may only be used with the device with which it was created. This is worth keeping in mind if you have more than one window and they do not share the same device.

By default, the texture will have the COPY_SRC, COPY_DST, SAMPLED and RENDER_ATTACHMENT usages enabled. If you wish to specify the usage yourself, see the load_from_path constructor.

If the &App is passed as the src, the window returned via app.main_window() will be used as the source of the device and queue.

pub fn from_image<T>(src: T, image: &DynamicImage) -> Texture

where T: WithDeviceQueuePair,

Load a texture from the given image.

The device and queue src can be either the App, a Window, a wgpu::DeviceQueuePair or a tuple (&wgpu::Device, &mut wgpu::Queue). Access to a Device is necessary in order to create the texture and buffer GPU resources, and access to a Queue is necessary for submitting the commands responsible for copying the buffer contents to the texture. Note that a texture may only be used with the device with which it was created. This is worth keeping in mind if you have more than one window and they do not share the same device.

By default, the texture will have the COPY_SRC, COPY_DST, SAMPLED and RENDER_ATTACHMENT usages enabled. If you wish to specify the usage yourself, see the load_from_path constructor.

If the &App is passed as the src, the window returned via app.main_window() will be used as the source of the device and queue.

The DeviceQueuePairSource can be either the App, a Window, a DeviceQueuePair or a tuple (&Device, &Queue).

pub fn load_from_path<P>( device: &Device, queue: &Queue, usage: TextureUsages, path: P ) -> Result<Texture, ImageError>

where P: AsRef<Path>,

Read an image file from the given path and load it directly into a texture.

This is short-hand for calling image::open and then Texture::load_from_image.

pub fn load_from_image( device: &Device, queue: &Queue, usage: TextureUsages, image: &DynamicImage ) -> Texture

Load a texture directly from a dynamic image.

If the image is already in a format supported by wgpu, no conversions are performed and the image is loaded directly as-is with a texture format that matches the original image color type.

If the image is of an unsupported format, it will be converted to the closest supported format before being uploaded.

pub fn load_from_image_buffer<P, Container>( device: &Device, queue: &Queue, usage: TextureUsages, buffer: &ImageBuffer<P, Container> ) -> Texture

where P: 'static + Pixel, Container: Deref<Target = [<P as Pixel>::Subpixel]>,

Load a texture directly from an image buffer using the given device queue.

No format or size conversions are performed - the given buffer is loaded directly into GPU memory.

Pixel type compatibility is ensured via the Pixel trait.

pub fn load_array_from_image_buffers<'a, I, P, Container>( device: &Device, queue: &Queue, usage: TextureUsages, buffers: I ) -> Option<Texture>

where I: IntoIterator<Item = &'a ImageBuffer<P, Container>>, <I as IntoIterator>::IntoIter: ExactSizeIterator, P: 'static + Pixel, Container: 'a + Deref<Target = [<P as Pixel>::Subpixel]>,

Load a texture array directly from a sequence of image buffers.

No format or size conversions are performed - the given buffer is loaded directly into GPU memory.

Pixel type compatibility is ensured via the Pixel trait.

Returns None if there are no images in the given sequence.

pub fn encode_load_from_image( device: &Device, encoder: &mut CommandEncoder, usage: TextureUsages, image: &DynamicImage ) -> Texture

Encode the necessary commands to load a texture directly from a dynamic image.

If the image is already in a format supported by wgpu, no conversions are performed and the image is loaded directly as-is with a texture format that matches the original image color type.

If the image is of an unsupported format, it will be converted to the closest supported format before being uploaded.

NOTE: The returned texture will remain empty until the given encoder has its command buffer submitted to the given device’s queue.

pub fn encode_load_from_image_buffer<P, Container>( device: &Device, encoder: &mut CommandEncoder, usage: TextureUsages, buffer: &ImageBuffer<P, Container> ) -> Texture

where P: 'static + Pixel, Container: Deref<Target = [<P as Pixel>::Subpixel]>,

Encode the necessary commands to load a texture from the given image buffer.

NOTE: The returned texture will remain empty until the given encoder has its command buffer submitted to the given device’s queue.

No format or size conversions are performed - the given buffer is loaded directly into GPU memory.

Pixel type compatibility is ensured via the Pixel trait.

pub fn encode_load_3d_from_image_buffers<'a, I, P, Container>( device: &Device, encoder: &mut CommandEncoder, usage: TextureUsages, buffers: I ) -> Option<Texture>

where I: IntoIterator<Item = &'a ImageBuffer<P, Container>>, <I as IntoIterator>::IntoIter: ExactSizeIterator, P: 'static + Pixel, Container: 'a + Deref<Target = [<P as Pixel>::Subpixel]>,

Encode the necessary commands to load a 3d texture directly from a sequence of image buffers.

NOTE: The returned texture will remain empty until the given encoder has its command buffer submitted to the given device’s queue.

NOTE: The returned texture will be 3d; you must create

No format or size conversions are performed - the given buffer is loaded directly into GPU memory.

Pixel type compatibility is ensured via the Pixel trait.

Returns None if there are no images in the given sequence.

impl Texture

pub fn descriptor( &self ) -> &TextureDescriptor<Option<&'static str>, &'static [TextureFormat]>

The inner descriptor from which this Texture was constructed.

pub fn into_inner(self) -> Arc<Texture>

Consume the Texture and produce the inner Arc.

pub fn inner(&self) -> &Arc<Texture>

A reference to the inner TextureHandle.

pub fn size(&self) -> [u32; 2]

The width and height of the texture.

See the extent method for producing the full width, height and depth of the texture.

pub fn extent(&self) -> Extent3d

The width, height and depth of the texture.

pub fn mip_level_count(&self) -> u32

Mip count of texture. For a texture with no extra mips, this must be 1.

pub fn sample_count(&self) -> u32

Sample count of texture. If this is not 1, texture must have BindingType::SampledTexture::multisampled set to true.

pub fn dimension(&self) -> TextureDimension

Describes whether the texture is of 1, 2 or 3 dimensions.

pub fn format(&self) -> TextureFormat

The format of the underlying texture data.

pub fn usage(&self) -> TextureUsages

The set of usage bits describing the ways in which the Texture may be used.

pub fn size_bytes(&self) -> usize

The size of the texture data in bytes.

pub fn sample_type(&self) -> TextureSampleType

The component type associated with the texture’s format.

pub fn from_handle_and_descriptor( handle: Arc<Texture>, descriptor: TextureDescriptor<Option<&'static str>, &'static [TextureFormat]> ) -> Texture

Create a Texture from the inner wgpu texture handle and the descriptor used to create it.

This constructor should only be used in the case that you already have a texture handle and a descriptor but need a Texture. The preferred construction approach is to use the TextureBuilder.

The descriptor must be the same used to create the texture.

pub fn id(&self) -> TextureId

A unique identifier associated with this texture.

This is useful for distinguishing between two Textures or for producing a hashable representation.

pub fn view(&self) -> ViewBuilder<'_>

Begin building a TextureView for this Texture.

By default, the produced TextureViewBuilder will build a texture view for the descriptor returned via default_view_descriptor.

pub fn view_dimension(&self) -> TextureViewDimension

A TextureViewDimension for a full view of the entire texture.

NOTE: This will never produce the D2Array, Cube or CubeArray variants. You may have to construct your own wgpu::TextureViewDimension via the view method if these are desired.

pub fn default_view_info(&self) -> TextureViewInfo

The view info, describing a full view of the texture.

pub fn default_view_descriptor(&self) -> TextureViewDescriptor<'static>

The view descriptor, describing a full view of the texture.

pub fn upload_data( &self, device: &Device, encoder: &mut CommandEncoder, data: &[u8] )

Encode a command for uploading the given data to the texture.

The length of the data must be equal to the length returned by texture.size_bytes().

pub fn to_buffer( &self, device: &Device, encoder: &mut CommandEncoder ) -> RowPaddedBuffer

Write the contents of the texture into a new buffer.

Commands will be added to the given encoder to copy the entire contents of the texture into the buffer.

If the texture has a sample count greater than one, it will first be resolved to a non-multisampled texture before being copied to the buffer. copy_texture_to_buffer command has been performed by the GPU.

NOTE: read should not be called on the returned buffer until the encoded commands have been submitted to the device queue.

Methods from Deref<Target = Texture>

pub unsafe fn as_hal<A, F>(&self, hal_texture_callback: F)

where A: HalApi, F: FnOnce(Option<&<A as Api>::Texture>),

Returns the inner hal Texture using a callback. The hal texture will be None if the backend type argument does not match with this wgpu Texture

Safety

• The raw handle obtained from the hal Texture must not be manually destroyed

pub fn create_view(&self, desc: &TextureViewDescriptor<'_>) -> TextureView

Creates a view of this texture.

pub fn destroy(&self)

Destroy the associated native resources as soon as possible.

pub fn as_image_copy(&self) -> ImageCopyTexture<&Texture>

Make an ImageCopyTexture representing the whole texture.

pub fn size(&self) -> Extent3d

Returns the size of this Texture.

This is always equal to the size that was specified when creating the texture.

pub fn width(&self) -> u32

Returns the width of this Texture.

This is always equal to the size.width that was specified when creating the texture.

pub fn height(&self) -> u32

Returns the height of this Texture.

This is always equal to the size.height that was specified when creating the texture.

pub fn depth_or_array_layers(&self) -> u32

Returns the depth or layer count of this Texture.

This is always equal to the size.depth_or_array_layers that was specified when creating the texture.

pub fn mip_level_count(&self) -> u32

Returns the mip_level_count of this Texture.

This is always equal to the mip_level_count that was specified when creating the texture.

pub fn sample_count(&self) -> u32

Returns the sample_count of this Texture.

This is always equal to the sample_count that was specified when creating the texture.

pub fn dimension(&self) -> TextureDimension

Returns the dimension of this Texture.

This is always equal to the dimension that was specified when creating the texture.

pub fn format(&self) -> TextureFormat

Returns the format of this Texture.

This is always equal to the format that was specified when creating the texture.

pub fn usage(&self) -> TextureUsages

Returns the allowed usages of this Texture.

This is always equal to the usage that was specified when creating the texture.

Trait Implementations

impl Clone for Texture

fn clone(&self) -> Texture

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Texture

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for Texture

type Target = Texture

The resulting type after dereferencing.

fn deref(&self) -> &<Texture as Deref>::Target

Dereferences the value.

impl ToTextureView for Texture

fn to_texture_view(&self) -> TextureView