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