wgpu/api/
texture_view.rs

1#[cfg(wgpu_core)]
2use core::ops::Deref;
3
4use crate::*;
5
6/// Handle to a texture view.
7///
8/// A `TextureView` object refers to a [`Texture`], or a subset of its layers and mip levels, and
9/// specifies an interpretation of the texture’s texels, which is needed to use a texture as a
10/// binding in a [`BindGroup`] or as an attachment in a [`RenderPass`].
11/// It can be created using [`Texture::create_view()`], which accepts a [`TextureViewDescriptor`]
12/// specifying the properties of the view.
13///
14/// Corresponds to [WebGPU `GPUTextureView`](https://gpuweb.github.io/gpuweb/#gputextureview).
15#[derive(Debug, Clone)]
16pub struct TextureView {
17    pub(crate) inner: dispatch::DispatchTextureView,
18    pub(crate) texture: Texture,
19}
20#[cfg(send_sync)]
21static_assertions::assert_impl_all!(TextureView: Send, Sync);
22
23crate::cmp::impl_eq_ord_hash_proxy!(TextureView => .inner);
24
25impl TextureView {
26    /// Returns the [`Texture`] that this `TextureView` refers to.
27    ///
28    /// All wgpu resources are refcounted, so you can own the returned [`Texture`]
29    /// by cloning it.
30    pub fn texture(&self) -> &Texture {
31        &self.texture
32    }
33
34    /// Get the [`wgpu_hal`] texture view from this `TextureView`.
35    ///
36    /// Find the Api struct corresponding to the active backend in [`wgpu_hal::api`],
37    /// and pass that struct to the to the `A` type parameter.
38    ///
39    /// Returns a guard that dereferences to the type of the hal backend
40    /// which implements [`A::TextureView`].
41    ///
42    /// # Types
43    ///
44    /// The returned type depends on the backend:
45    ///
46    #[doc = crate::macros::hal_type_vulkan!("TextureView")]
47    #[doc = crate::macros::hal_type_metal!("TextureView")]
48    #[doc = crate::macros::hal_type_dx12!("TextureView")]
49    #[doc = crate::macros::hal_type_gles!("TextureView")]
50    ///
51    /// # Deadlocks
52    ///
53    /// - The returned guard holds a read-lock on a device-local "destruction"
54    ///   lock, which will cause all calls to `destroy` to block until the
55    ///   guard is released.
56    ///
57    /// # Errors
58    ///
59    /// This method will return None if:
60    /// - The texture view is not from the backend specified by `A`.
61    /// - The texture view is from [`Backend::BrowserWebGpu`].
62    ///   (Use `TextureView::as_webgpu()` instead.)
63    /// - The texture view is from a custom backend.
64    ///
65    /// # Safety
66    ///
67    /// - The returned resource must not be destroyed unless the guard
68    ///   is the last reference to it and it is not in use by the GPU.
69    ///   The guard and handle may be dropped at any time however.
70    /// - All the safety requirements of wgpu-hal must be upheld.
71    ///
72    /// [`A::TextureView`]: hal::Api::TextureView
73    #[cfg(wgpu_core)]
74    pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<impl Deref<Target = A::TextureView>> {
75        let view = self.inner.as_core_opt()?;
76        unsafe { view.as_hal::<A>() }
77    }
78
79    /// Returns the underlying [`webgpu::GpuTextureView`] handle if this view
80    /// is on the WebGPU backend, otherwise `None`.
81    ///
82    /// [`webgpu::GpuTextureView`]: crate::webgpu::GpuTextureView
83    #[cfg(webgpu)]
84    pub fn as_webgpu(&self) -> Option<&webgpu::GpuTextureView> {
85        self.inner.as_webgpu_opt().map(|wv| &wv.inner)
86    }
87
88    #[cfg(custom)]
89    /// Returns custom implementation of TextureView (if custom backend and is internally T)
90    pub fn as_custom<T: custom::TextureViewInterface>(&self) -> Option<&T> {
91        self.inner.as_custom()
92    }
93}
94
95#[cfg(wgpu_core)]
96impl TextureView {
97    /// Create a new texture view of wgpu from a wgpu-core texture view.
98    ///
99    /// # Arguments
100    ///
101    /// - `core_texture_view` - wgpu-core texture view.
102    pub fn from_core(core_texture_view: alloc::sync::Arc<wgc::resource::TextureView>) -> Self {
103        let texture = Texture::from_core(core_texture_view.texture().clone());
104        Self {
105            inner: crate::backend::wgpu_core::CoreTextureView::from_core(core_texture_view).into(),
106            texture,
107        }
108    }
109
110    /// Returns the underlying wgpu-core device if this `Device` is on the wgpu-core backend, otherwise `None`.
111    pub fn as_core(&self) -> Option<alloc::sync::Arc<wgc::resource::TextureView>> {
112        self.inner.as_core_opt().map(|cd| cd.as_core())
113    }
114}
115
116/// Describes a [`TextureView`].
117///
118/// For use with [`Texture::create_view`].
119///
120/// Corresponds to [WebGPU `GPUTextureViewDescriptor`](
121/// https://gpuweb.github.io/gpuweb/#dictdef-gputextureviewdescriptor).
122pub type TextureViewDescriptor<'a> = wgt::TextureViewDescriptor<Label<'a>>;
123static_assertions::assert_impl_all!(TextureViewDescriptor<'_>: Send, Sync);
wgpu/api/texture_view.rs

wgpu/api/
texture_view.rs
