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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
use crate::{
assets::upload::Asset,
ecs::system::Res,
wgpu::{
backend::WGPUBackend,
mipmap::MipmapGenerator,
textures::{bytes_per_pixel, decode_file},
},
};
/// Source data for [`GPUCubemap`]. Prefer the
/// [`from_files`](Self::from_files)/[`from_faces`](Self::from_faces)/
/// [`empty`](Self::empty) constructors over setting fields by hand.
pub struct CubemapDescriptor {
/// Edge length in pixels — cubemap faces are always square.
pub size: u32,
/// GPU pixel format to upload as. Defaults to `Rgba8UnormSrgb`.
pub format: wgpu::TextureFormat,
/// `Some` uploads 6 faces of pixel data up front (wgpu's expected
/// order: +X, -X, +Y, -Y, +Z, -Z). `None` allocates an empty cubemap
/// meant to be filled later by rendering into per-face views — e.g. an
/// environment-map capture pass — in which case [`wgpu_descriptor`](Self::wgpu_descriptor)
/// adds `RENDER_ATTACHMENT` usage instead of requiring upload data.
pub faces: Option<[Vec<u8>; 6]>,
/// File paths for each of the 6 faces (same order as `faces`), decoded
/// through the same loader used by `GPUTexture`/`GPUTextureArray`.
pub face_files: Option<[&'static str; 6]>,
/// Whether to generate a full mip chain (via [`MipmapGenerator`]). Only
/// applies when uploading pixel data (`faces`/`face_files` set) —
/// meaningless for an [`empty`](Self::empty) render-target cubemap.
pub generate_mips: bool,
}
impl CubemapDescriptor {
/// Load 6 faces from files (+X, -X, +Y, -Y, +Z, -Z). Size is inferred from the first face.
pub fn from_files(size: u32, files: [&'static str; 6]) -> Self {
Self {
size,
format: wgpu::TextureFormat::Rgba8UnormSrgb,
faces: None,
face_files: Some(files),
generate_mips: false,
}
}
/// Supply raw pixel bytes for each face (+X, -X, +Y, -Y, +Z, -Z).
pub fn from_faces(size: u32, format: wgpu::TextureFormat, faces: [Vec<u8>; 6]) -> Self {
Self {
size,
format,
faces: Some(faces),
face_files: None,
generate_mips: false,
}
}
/// Allocate an empty cubemap for use as a render target (e.g. environment capture).
pub fn empty(size: u32, format: wgpu::TextureFormat) -> Self {
Self {
size,
format,
faces: None,
face_files: None,
generate_mips: false,
}
}
/// Override the format set by whichever constructor was used (all
/// three default to or take `format` directly — this exists for the
/// builder-chain case, e.g. `CubemapDescriptor::empty(size, format).with_mips()`
/// followed later by a format change, without re-specifying `size`).
pub fn with_format(mut self, format: wgpu::TextureFormat) -> Self {
self.format = format;
self
}
/// Enable full mip chain generation.
pub fn with_mips(mut self) -> Self {
self.generate_mips = true;
self
}
/// `render_target` is set for an empty capture-target cubemap (see
/// [`empty`](Self::empty)), rendered into directly. Separately from
/// that, `mip_count > 1` also needs `RENDER_ATTACHMENT` — mips beyond
/// level 0 are rendered into by [`MipmapGenerator::generate_mips`](super::mipmap::MipmapGenerator::generate_mips)
/// regardless of whether the base texture is a capture target or one
/// uploaded from real face data, so the two conditions are OR'd rather
/// than `render_target` alone deciding the usage.
fn wgpu_descriptor(&self, mip_count: u32, render_target: bool) -> wgpu::TextureDescriptor<'_> {
let mut usage = super::mipmap::texture_usage(mip_count);
if render_target {
usage |= wgpu::TextureUsages::RENDER_ATTACHMENT;
}
wgpu::TextureDescriptor {
label: None,
size: wgpu::Extent3d {
width: self.size,
height: self.size,
depth_or_array_layers: 6,
},
mip_level_count: mip_count,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: self.format,
usage,
view_formats: &[],
}
}
}
/// A cubemap uploaded to the GPU, ready to bind (e.g. via
/// [`BindingInstanceEntry::Cubemap`](super::instance::BindingInstanceEntry::Cubemap))
/// or, for an [`empty`](CubemapDescriptor::empty) one, rendered into
/// per-face for environment capture.
pub struct GPUCubemap {
pub texture: wgpu::Texture,
pub view: wgpu::TextureView,
}
impl Asset<WGPUBackend> for GPUCubemap {
type Source = CubemapDescriptor;
type Deps<'a> = Res<'a, MipmapGenerator>;
fn upload<'a>(
source: &CubemapDescriptor,
backend: &WGPUBackend,
mipmap_generator: &Res<'a, MipmapGenerator>,
) -> Option<Self> {
let faces: Option<[Vec<u8>; 6]> = if let Some(files) = &source.face_files {
let mut out: [Vec<u8>; 6] = Default::default();
for (i, path) in files.iter().enumerate() {
let (w, h, data) = decode_file(path, source.format)?;
if w != source.size || h != source.size {
tracing::error!(
"CubemapSpec: face {i} ('{path}') is {w}x{h}, expected {0}x{0}",
source.size
);
return None;
}
out[i] = data;
}
Some(out)
} else {
source.faces.clone()
};
let mip_count = super::mipmap::mip_count(source.size, source.generate_mips);
let texture = backend
.device
.create_texture(&source.wgpu_descriptor(mip_count, faces.is_none()));
if let Some(faces) = &faces {
for (face, data) in faces.iter().enumerate() {
backend.queue.write_texture(
wgpu::TexelCopyTextureInfo {
texture: &texture,
mip_level: 0,
origin: wgpu::Origin3d {
x: 0,
y: 0,
z: face as u32,
},
aspect: wgpu::TextureAspect::All,
},
data,
wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(bytes_per_pixel(source.format) * source.size),
rows_per_image: Some(source.size),
},
wgpu::Extent3d {
width: source.size,
height: source.size,
depth_or_array_layers: 1,
},
);
}
if mip_count > 1 {
mipmap_generator.generate_mips(
&backend.device,
&backend.queue,
&texture,
source.format,
mip_count,
6,
);
}
}
let view = texture.create_view(&wgpu::TextureViewDescriptor {
dimension: Some(wgpu::TextureViewDimension::Cube),
..Default::default()
});
Some(Self { texture, view })
}
}
crate::wgpu::plugin_macros::mipmap_asset_plugin! {
/// Registers the [`GPUCubemap`] asset pipeline (`Assets<CubemapDescriptor>`
/// → `ProcessedAssets<GPUCubemap>`), plus the [`MipmapGenerator`] it
/// depends on for `generate_mips`. Included by
/// [`WGPUPlugin`](super::backend::WGPUPlugin); add directly only if you're
/// assembling the `wgpu` module's plugins by hand.
CubemapPlugin, GPUCubemap
}