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 /// # Deadlocks
43 ///
44 /// - The returned guard holds a read-lock on a device-local "destruction"
45 /// lock, which will cause all calls to `destroy` to block until the
46 /// guard is released.
47 ///
48 /// # Errors
49 ///
50 /// This method will return None if:
51 /// - The texture view is not from the backend specified by `A`.
52 /// - The texture view is from the `webgpu` or `custom` backend.
53 /// - The texture this view points to has had [`Texture::destroy()`] called on it.
54 ///
55 /// # Safety
56 ///
57 /// - The returned resource must not be destroyed unless the guard
58 /// is the last reference to it and it is not in use by the GPU.
59 /// The guard and handle may be dropped at any time however.
60 /// - All the safety requirements of wgpu-hal must be upheld.
61 ///
62 /// [`A::TextureView`]: hal::Api::TextureView
63 #[cfg(wgpu_core)]
64 pub unsafe fn as_hal<A: wgc::hal_api::HalApi>(
65 &self,
66 ) -> Option<impl Deref<Target = A::TextureView>> {
67 let view = self.inner.as_core_opt()?;
68 unsafe { view.context.texture_view_as_hal::<A>(view) }
69 }
70
71 #[cfg(custom)]
72 /// Returns custom implementation of TextureView (if custom backend and is internally T)
73 pub fn as_custom<T: custom::TextureViewInterface>(&self) -> Option<&T> {
74 self.inner.as_custom()
75 }
76}
77
78/// Describes a [`TextureView`].
79///
80/// For use with [`Texture::create_view`].
81///
82/// Corresponds to [WebGPU `GPUTextureViewDescriptor`](
83/// https://gpuweb.github.io/gpuweb/#dictdef-gputextureviewdescriptor).
84pub type TextureViewDescriptor<'a> = wgt::TextureViewDescriptor<Label<'a>>;
85static_assertions::assert_impl_all!(TextureViewDescriptor<'_>: Send, Sync);