wgpu/api/
texture.rs

1use crate::*;
2
3/// Handle to a texture on the GPU.
4///
5/// It can be created with [`Device::create_texture`].
6///
7/// Corresponds to [WebGPU `GPUTexture`](https://gpuweb.github.io/gpuweb/#texture-interface).
8#[derive(Debug, Clone)]
9pub struct Texture {
10    pub(crate) inner: dispatch::DispatchTexture,
11    pub(crate) descriptor: TextureDescriptor<'static>,
12}
13#[cfg(send_sync)]
14static_assertions::assert_impl_all!(Texture: Send, Sync);
15
16crate::cmp::impl_eq_ord_hash_proxy!(Texture => .inner);
17
18impl Texture {
19    /// Returns the inner hal Texture using a callback. The hal texture will be `None` if the
20    /// backend type argument does not match with this wgpu Texture
21    ///
22    /// # Safety
23    ///
24    /// - The raw handle obtained from the hal Texture must not be manually destroyed
25    #[cfg(wgpu_core)]
26    pub unsafe fn as_hal<A: wgc::hal_api::HalApi, F: FnOnce(Option<&A::Texture>) -> R, R>(
27        &self,
28        hal_texture_callback: F,
29    ) -> R {
30        if let Some(tex) = self.inner.as_core_opt() {
31            unsafe {
32                tex.context
33                    .texture_as_hal::<A, F, R>(tex, hal_texture_callback)
34            }
35        } else {
36            hal_texture_callback(None)
37        }
38    }
39
40    /// Creates a view of this texture, specifying an interpretation of its texels and
41    /// possibly a subset of its layers and mip levels.
42    ///
43    /// Texture views are needed to use a texture as a binding in a [`BindGroup`]
44    /// or as an attachment in a [`RenderPass`].
45    pub fn create_view(&self, desc: &TextureViewDescriptor<'_>) -> TextureView {
46        let view = self.inner.create_view(desc);
47
48        TextureView { inner: view }
49    }
50
51    /// Destroy the associated native resources as soon as possible.
52    pub fn destroy(&self) {
53        self.inner.destroy();
54    }
55
56    /// Make an `TexelCopyTextureInfo` representing the whole texture.
57    pub fn as_image_copy(&self) -> TexelCopyTextureInfo<'_> {
58        TexelCopyTextureInfo {
59            texture: self,
60            mip_level: 0,
61            origin: Origin3d::ZERO,
62            aspect: TextureAspect::All,
63        }
64    }
65
66    /// Returns the size of this `Texture`.
67    ///
68    /// This is always equal to the `size` that was specified when creating the texture.
69    pub fn size(&self) -> Extent3d {
70        self.descriptor.size
71    }
72
73    /// Returns the width of this `Texture`.
74    ///
75    /// This is always equal to the `size.width` that was specified when creating the texture.
76    pub fn width(&self) -> u32 {
77        self.descriptor.size.width
78    }
79
80    /// Returns the height of this `Texture`.
81    ///
82    /// This is always equal to the `size.height` that was specified when creating the texture.
83    pub fn height(&self) -> u32 {
84        self.descriptor.size.height
85    }
86
87    /// Returns the depth or layer count of this `Texture`.
88    ///
89    /// This is always equal to the `size.depth_or_array_layers` that was specified when creating the texture.
90    pub fn depth_or_array_layers(&self) -> u32 {
91        self.descriptor.size.depth_or_array_layers
92    }
93
94    /// Returns the mip_level_count of this `Texture`.
95    ///
96    /// This is always equal to the `mip_level_count` that was specified when creating the texture.
97    pub fn mip_level_count(&self) -> u32 {
98        self.descriptor.mip_level_count
99    }
100
101    /// Returns the sample_count of this `Texture`.
102    ///
103    /// This is always equal to the `sample_count` that was specified when creating the texture.
104    pub fn sample_count(&self) -> u32 {
105        self.descriptor.sample_count
106    }
107
108    /// Returns the dimension of this `Texture`.
109    ///
110    /// This is always equal to the `dimension` that was specified when creating the texture.
111    pub fn dimension(&self) -> TextureDimension {
112        self.descriptor.dimension
113    }
114
115    /// Returns the format of this `Texture`.
116    ///
117    /// This is always equal to the `format` that was specified when creating the texture.
118    pub fn format(&self) -> TextureFormat {
119        self.descriptor.format
120    }
121
122    /// Returns the allowed usages of this `Texture`.
123    ///
124    /// This is always equal to the `usage` that was specified when creating the texture.
125    pub fn usage(&self) -> TextureUsages {
126        self.descriptor.usage
127    }
128}
129
130/// Describes a [`Texture`].
131///
132/// For use with [`Device::create_texture`].
133///
134/// Corresponds to [WebGPU `GPUTextureDescriptor`](
135/// https://gpuweb.github.io/gpuweb/#dictdef-gputexturedescriptor).
136pub type TextureDescriptor<'a> = wgt::TextureDescriptor<Label<'a>, &'a [TextureFormat]>;
137static_assertions::assert_impl_all!(TextureDescriptor<'_>: Send, Sync);
wgpu/api/texture.rs

wgpu/api/
texture.rs
