wgpu/api/texture.rs
1#[cfg(wgpu_core)]
2use core::ops::Deref;
3
4use crate::*;
5
6/// Handle to a texture on the GPU.
7///
8/// It can be created with [`Device::create_texture`].
9///
10/// Corresponds to [WebGPU `GPUTexture`](https://gpuweb.github.io/gpuweb/#texture-interface).
11#[derive(Debug, Clone)]
12pub struct Texture {
13 pub(crate) inner: dispatch::DispatchTexture,
14 pub(crate) descriptor: TextureDescriptor<'static>,
15}
16#[cfg(send_sync)]
17static_assertions::assert_impl_all!(Texture: Send, Sync);
18
19crate::cmp::impl_eq_ord_hash_proxy!(Texture => .inner);
20
21impl Texture {
22 /// Get the [`wgpu_hal`] texture from this `Texture`.
23 ///
24 /// Find the Api struct corresponding to the active backend in [`wgpu_hal::api`],
25 /// and pass that struct to the to the `A` type parameter.
26 ///
27 /// Returns a guard that dereferences to the type of the hal backend
28 /// which implements [`A::Texture`].
29 ///
30 /// # Types
31 ///
32 /// The returned type depends on the backend:
33 ///
34 #[doc = crate::hal_type_vulkan!("Texture")]
35 #[doc = crate::hal_type_metal!("Texture")]
36 #[doc = crate::hal_type_dx12!("Texture")]
37 #[doc = crate::hal_type_gles!("Texture")]
38 ///
39 /// # Deadlocks
40 ///
41 /// - The returned guard holds a read-lock on a device-local "destruction"
42 /// lock, which will cause all calls to `destroy` to block until the
43 /// guard is released.
44 ///
45 /// # Errors
46 ///
47 /// This method will return None if:
48 /// - The texture is not from the backend specified by `A`.
49 /// - The texture is from the `webgpu` or `custom` backend.
50 /// - The texture has had [`Self::destroy()`] called on it.
51 ///
52 /// # Safety
53 ///
54 /// - The returned resource must not be destroyed unless the guard
55 /// is the last reference to it and it is not in use by the GPU.
56 /// The guard and handle may be dropped at any time however.
57 /// - All the safety requirements of wgpu-hal must be upheld.
58 ///
59 /// [`A::Texture`]: hal::Api::Texture
60 #[cfg(wgpu_core)]
61 pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<impl Deref<Target = A::Texture>> {
62 let texture = self.inner.as_core_opt()?;
63 unsafe { texture.context.texture_as_hal::<A>(texture) }
64 }
65
66 #[cfg(custom)]
67 /// Returns custom implementation of Texture (if custom backend and is internally T)
68 pub fn as_custom<T: custom::TextureInterface>(&self) -> Option<&T> {
69 self.inner.as_custom()
70 }
71
72 /// Creates a view of this texture, specifying an interpretation of its texels and
73 /// possibly a subset of its layers and mip levels.
74 ///
75 /// Texture views are needed to use a texture as a binding in a [`BindGroup`]
76 /// or as an attachment in a [`RenderPass`].
77 pub fn create_view(&self, desc: &TextureViewDescriptor<'_>) -> TextureView {
78 let view = self.inner.create_view(desc);
79
80 TextureView {
81 inner: view,
82 texture: self.clone(),
83 }
84 }
85
86 /// Destroy the associated native resources as soon as possible.
87 pub fn destroy(&self) {
88 self.inner.destroy();
89 }
90
91 /// Make an `TexelCopyTextureInfo` representing the whole texture.
92 pub fn as_image_copy(&self) -> TexelCopyTextureInfo<'_> {
93 TexelCopyTextureInfo {
94 texture: self,
95 mip_level: 0,
96 origin: Origin3d::ZERO,
97 aspect: TextureAspect::All,
98 }
99 }
100
101 /// Returns the size of this `Texture`.
102 ///
103 /// This is always equal to the `size` that was specified when creating the texture.
104 pub fn size(&self) -> Extent3d {
105 self.descriptor.size
106 }
107
108 /// Returns the width of this `Texture`.
109 ///
110 /// This is always equal to the `size.width` that was specified when creating the texture.
111 pub fn width(&self) -> u32 {
112 self.descriptor.size.width
113 }
114
115 /// Returns the height of this `Texture`.
116 ///
117 /// This is always equal to the `size.height` that was specified when creating the texture.
118 pub fn height(&self) -> u32 {
119 self.descriptor.size.height
120 }
121
122 /// Returns the depth or layer count of this `Texture`.
123 ///
124 /// This is always equal to the `size.depth_or_array_layers` that was specified when creating the texture.
125 pub fn depth_or_array_layers(&self) -> u32 {
126 self.descriptor.size.depth_or_array_layers
127 }
128
129 /// Returns the mip_level_count of this `Texture`.
130 ///
131 /// This is always equal to the `mip_level_count` that was specified when creating the texture.
132 pub fn mip_level_count(&self) -> u32 {
133 self.descriptor.mip_level_count
134 }
135
136 /// Returns the sample_count of this `Texture`.
137 ///
138 /// This is always equal to the `sample_count` that was specified when creating the texture.
139 pub fn sample_count(&self) -> u32 {
140 self.descriptor.sample_count
141 }
142
143 /// Returns the dimension of this `Texture`.
144 ///
145 /// This is always equal to the `dimension` that was specified when creating the texture.
146 pub fn dimension(&self) -> TextureDimension {
147 self.descriptor.dimension
148 }
149
150 /// Returns the format of this `Texture`.
151 ///
152 /// This is always equal to the `format` that was specified when creating the texture.
153 pub fn format(&self) -> TextureFormat {
154 self.descriptor.format
155 }
156
157 /// Returns the allowed usages of this `Texture`.
158 ///
159 /// This is always equal to the `usage` that was specified when creating the texture.
160 pub fn usage(&self) -> TextureUsages {
161 self.descriptor.usage
162 }
163}
164
165/// Describes a [`Texture`].
166///
167/// For use with [`Device::create_texture`].
168///
169/// Corresponds to [WebGPU `GPUTextureDescriptor`](
170/// https://gpuweb.github.io/gpuweb/#dictdef-gputexturedescriptor).
171pub type TextureDescriptor<'a> = wgt::TextureDescriptor<Label<'a>, &'a [TextureFormat]>;
172static_assertions::assert_impl_all!(TextureDescriptor<'_>: Send, Sync);