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
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
use crate::math::Vector2;
use std::sync::Arc;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextureFormat {
/// Standard 8-bit sRGB color (e.g. baseColor / albedo).
Rgba8UnormSrgb,
/// Linear 8-bit (e.g. roughness, metalness, normal maps).
Rgba8Unorm,
/// Single-channel 8-bit.
R8Unorm,
/// Linear 16-bit float RGBA (8 bytes/px), stored as raw half-float bytes.
///
/// This is the HDR path: unlike the 8-bit formats it can carry values above
/// 1.0, which is what an environment map needs if it is to hold a sun
/// alongside a sky (a real ratio of ~10^4:1). Use with a tone-mapped
/// renderer — see [`crate::renderer::ToneMapping`].
Rgba16Float,
/// BC1 ("DXT1"), sRGB. 4x4 blocks in 8 bytes — half a byte a pixel, an
/// eighth of `Rgba8UnormSrgb`.
///
/// Two RGB565 endpoints and a 2-bit index per pixel, so a block can express
/// four colours along one line in RGB. That is plenty for photographic
/// ground and poor for smooth wide gradients, where the four steps become
/// visible banding. Alpha is 1 throughout: BC1's punch-through mode is not
/// used here.
///
/// The point of it is size. Blue Marble at its native 500 m is 86400x43200,
/// which is 13.9 GB as RGBA and will not fit anything; as BC1 it is 1.74 GB,
/// or 2.32 with a full mip chain.
Bc1RgbaUnormSrgb,
/// BC7, sRGB. 4x4 blocks in 16 bytes — one byte a pixel, a quarter of
/// `Rgba8UnormSrgb`.
///
/// Eight block modes with variable partitioning and endpoint precision, so
/// it holds gradients that BC1 bands. No encoder here — supply the blocks —
/// but the format, upload path and mip handling all work, so an externally
/// encoded map can be used as-is.
Bc7RgbaUnormSrgb,
}
impl TextureFormat {
/// Block-compressed formats store a `w x h` block of pixels as one fixed
/// unit and cannot be addressed per pixel at all.
pub fn is_block_compressed(self) -> bool {
matches!(self, Self::Bc1RgbaUnormSrgb | Self::Bc7RgbaUnormSrgb)
}
/// Pixels per block, `(1, 1)` for uncompressed formats.
pub fn block_dim(self) -> (u32, u32) {
match self {
Self::Bc1RgbaUnormSrgb | Self::Bc7RgbaUnormSrgb => (4, 4),
_ => (1, 1),
}
}
/// Bytes per block — per pixel, for the uncompressed formats.
pub fn bytes_per_block(self) -> usize {
match self {
Self::Rgba8UnormSrgb | Self::Rgba8Unorm => 4,
Self::R8Unorm => 1,
Self::Rgba16Float => 8,
Self::Bc1RgbaUnormSrgb => 8,
Self::Bc7RgbaUnormSrgb => 16,
}
}
/// Bytes one `width x height` image occupies in this format.
///
/// Block formats round UP to whole blocks, which is why a 4x4-block mip
/// chain does not simply halve in size at the bottom: a 2x2 level still
/// costs a whole block, and a 1x1 level costs one too.
pub fn data_len(self, width: u32, height: u32) -> usize {
let (bw, bh) = self.block_dim();
let blocks = (width.max(1).div_ceil(bw) as usize) * (height.max(1).div_ceil(bh) as usize);
blocks * self.bytes_per_block()
}
/// Bytes per row of blocks, for `ImageDataLayout::bytes_per_row`.
pub fn bytes_per_row(self, width: u32) -> u32 {
let (bw, _) = self.block_dim();
width.max(1).div_ceil(bw) * self.bytes_per_block() as u32
}
/// Rows of blocks, for `ImageDataLayout::rows_per_image`.
pub fn rows_per_image(self, height: u32) -> u32 {
let (_, bh) = self.block_dim();
height.max(1).div_ceil(bh)
}
}
/// Pack linear f32 RGBA into the raw half-float bytes a
/// [`TextureFormat::Rgba16Float`] texture expects.
///
/// Delegates to the same f32→f16 converter the PMREM atlas upload uses, so
/// there is exactly one rounding implementation in the crate.
pub fn pack_rgba16f(rgba: &[f32]) -> Vec<u8> {
let mut out = Vec::with_capacity(rgba.len() * 2);
for v in rgba {
out.extend_from_slice(&crate::renderer::gpu_texture::f32_to_f16_bits(*v).to_le_bytes());
}
out
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextureFilter {
Nearest,
Linear,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextureWrap {
ClampToEdge,
Repeat,
MirroredRepeat,
}
/// 2D texture source. Mirrors three.js's `Texture` for the parts we need.
#[derive(Debug, Clone)]
pub struct Texture {
pub width: u32,
pub height: u32,
pub format: TextureFormat,
pub mag_filter: TextureFilter,
pub min_filter: TextureFilter,
/// three.js's mipmapped `minFilter`s, the part [`min_filter`](Self::min_filter)
/// leaves out: how minification moves between mip levels — `Some(Linear)`
/// (`*MipmapLinearFilter`, three.js's default), `Some(Nearest)`
/// (`*MipmapNearestFilter`) — or `None`, no mipmaps at all (`LinearFilter`
/// / `NearestFilter`), sampling level 0 only.
pub mipmap_filter: Option<TextureFilter>,
pub wrap_s: TextureWrap,
pub wrap_t: TextureWrap,
/// Pixel data. Length must equal `width * height * bytes_per_pixel`.
pub data: Arc<Vec<u8>>,
pub flip_y: bool,
/// UV transform — translation, rotation, scale all collapsed into a 2D
/// affine. Mirrors three.js's `Texture.matrix`.
pub offset: Vector2,
pub repeat: Vector2,
pub rotation: f32,
/// three.js `Texture.center`: the point `rotation` turns about, in UV
/// space (default `(0, 0)`, the lower-left corner).
pub center: Vector2,
/// three.js `Texture.channel` (r151+): which UV set the map reads — 0 is
/// the geometry's `uv`, 1 its `uv1`. Channels the geometry does not carry
/// read zero, as an unbound attribute does in WebGL.
pub channel: u32,
/// three.js `Texture.matrixAutoUpdate` (default `true`): the UV transform
/// is rebuilt from `offset`/`repeat`/`rotation`/`center` each frame.
/// `false` uses [`matrix`](Self::matrix) as given.
pub matrix_auto_update: bool,
/// three.js `Texture.matrix` — column-major `Matrix3` elements, read only
/// when `matrix_auto_update` is off.
pub matrix: [f32; 9],
/// If set, this texture is backed by a RenderTarget's color attachment
/// instead of the CPU `data` bytes. The renderer skips upload and uses
/// the RenderTarget's view directly for sampling.
pub external_rt_id: Option<u32>,
/// Mip levels 1..N, largest first, when they are supplied rather than
/// derived. Empty means "work them out on upload".
///
/// Block-compressed textures have no choice: a mip chain cannot be box
/// filtered from BC blocks, and the GPU cannot render into them either, so
/// the levels have to arrive already encoded. Every sampler in the renderer
/// asks for trilinear filtering, so a large texture without a chain does
/// not merely lose quality — it shimmers under any minification at all.
pub mips: Vec<Arc<Vec<u8>>>,
/// Stable identity, assigned once at construction and carried by clones.
///
/// The upload cache used to key on the DATA'S ADDRESS, which ties a GPU
/// texture's identity to the lifetime of its CPU bytes: release them and
/// the entry is orphaned, free and reallocate and it is silently reused by
/// somebody else. An id decouples the two, which is what makes
/// [`Texture::handle`] possible — and that is worth a great deal when the
/// bytes are gigabytes.
pub id: u64,
/// Bumped when [`replace_rgba_bytes`](Self::replace_rgba_bytes) swaps pixel
/// data so the renderer re-uploads without allocating a new texture id.
pub upload_seq: u64,
}
/// Source of [`Texture::id`]. Monotonic; wrapping it would take 500 years of
/// allocating a texture every nanosecond.
static NEXT_TEXTURE_ID: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
pub(crate) fn next_texture_id() -> u64 {
NEXT_TEXTURE_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
}
const IDENTITY3: [f32; 9] = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0];
impl Texture {
/// three.js `Texture.matrix` as the two rows a shader multiplies the UV
/// by: `uv' = (r0 · (u, v, 1), r1 · (u, v, 1))`.
///
/// With `matrix_auto_update` (the default) this is `Matrix3.setUvTransform(
/// offset.x, offset.y, repeat.x, repeat.y, rotation, center.x, center.y)`,
/// which three.js recomputes in `refreshTransformUniform`; otherwise the
/// user's [`matrix`](Self::matrix).
pub fn uv_transform_rows(&self) -> [[f32; 3]; 2] {
if !self.matrix_auto_update {
let e = &self.matrix;
// Column-major: element (row r, column c) is e[c * 3 + r].
return [[e[0], e[3], e[6]], [e[1], e[4], e[7]]];
}
let (tx, ty) = (self.offset.x, self.offset.y);
let (sx, sy) = (self.repeat.x, self.repeat.y);
let (cx, cy) = (self.center.x, self.center.y);
let (s, c) = self.rotation.sin_cos();
[
[sx * c, sx * s, -sx * (c * cx + s * cy) + cx + tx],
[-sy * s, sy * c, -sy * (-s * cx + c * cy) + cy + ty],
]
}
pub fn new(width: u32, height: u32, format: TextureFormat, data: Vec<u8>) -> Self {
Self {
width,
height,
format,
mag_filter: TextureFilter::Linear,
min_filter: TextureFilter::Linear,
mipmap_filter: Some(TextureFilter::Linear),
wrap_s: TextureWrap::ClampToEdge,
wrap_t: TextureWrap::ClampToEdge,
data: Arc::new(data),
flip_y: true,
offset: Vector2::ZERO,
repeat: Vector2::ONE,
rotation: 0.0,
center: Vector2::ZERO,
channel: 0,
matrix_auto_update: true,
matrix: IDENTITY3,
external_rt_id: None,
mips: Vec::new(),
id: next_texture_id(),
upload_seq: 0,
}
}
/// Build a Texture that's backed by a RenderTarget's color attachment.
/// The renderer skips upload and samples directly from the RT view.
pub fn from_render_target(rt_id: u32, width: u32, height: u32, format: TextureFormat) -> Self {
Self {
width,
height,
format,
mag_filter: TextureFilter::Linear,
min_filter: TextureFilter::Linear,
// three.js gives a render target's texture `LinearFilter`: it has
// no mip chain.
mipmap_filter: None,
wrap_s: TextureWrap::ClampToEdge,
wrap_t: TextureWrap::ClampToEdge,
data: Arc::new(Vec::new()),
flip_y: false,
offset: Vector2::ZERO,
repeat: Vector2::ONE,
rotation: 0.0,
center: Vector2::ZERO,
channel: 0,
matrix_auto_update: true,
matrix: IDENTITY3,
external_rt_id: Some(rt_id),
mips: Vec::new(),
id: next_texture_id(),
upload_seq: 0,
}
}
/// Replace level-0 RGBA bytes in place (same width/height). Returns false when
/// `data` length does not match.
pub fn replace_rgba_bytes(&mut self, data: Vec<u8>) -> bool {
let expected = self.format.data_len(self.width, self.height);
if data.len() != expected {
return false;
}
self.data = Arc::new(data);
self.upload_seq += 1;
true
}
/// Bytes one pixel occupies. **Panics on block-compressed formats**, which
/// have no such number.
///
/// Every caller of this in the crate walks the data per pixel — building
/// mip chains, compositing ice caps, converting height to normals — and not
/// one of those operations is meaningful on 4x4 blocks. Returning something
/// plausible instead (4, say, or 0 with a `.max(1)` downstream) would let
/// all of them run and quietly produce noise. Use
/// [`TextureFormat::data_len`] for sizes and
/// [`TextureFormat::is_block_compressed`] to branch.
/// The pixels as 8-bit RGBA, the right way up for a file.
///
/// `None` when there is nothing to convert: a texture whose bytes live only
/// on the GPU, or one held block-compressed, which would have to be decoded
/// first. Rows come out top-first, which is what every image format stores
/// and what both the glTF and USD writers need — so a texture with
/// [`flip_y`](Self::flip_y) off, meaning its rows are already bottom-up, is
/// turned over here rather than being written upside down.
pub fn to_rgba8(&self) -> Option<Vec<u8>> {
let count = (self.width as usize).checked_mul(self.height as usize)?;
if count == 0 || self.data.is_empty() {
return None;
}
let pixels: Vec<u8> = match self.format {
TextureFormat::Rgba8UnormSrgb | TextureFormat::Rgba8Unorm => {
self.data.get(..count * 4)?.to_vec()
}
// One channel becomes grey, so the file says what the channel said
// however a reader samples it.
TextureFormat::R8Unorm => self
.data
.get(..count)?
.iter()
.flat_map(|v| [*v, *v, *v, 255])
.collect(),
// Half float down to 8 bits. Anything above 1.0 clamps, which is a
// real loss and only reachable for an HDR image.
TextureFormat::Rgba16Float => self
.data
.get(..count * 8)?
.chunks_exact(2)
.map(|h| {
let v = half_to_f32(u16::from_le_bytes([h[0], h[1]]));
(v.clamp(0.0, 1.0) * 255.0).round() as u8
})
.collect(),
_ => return None,
};
if self.flip_y {
return Some(pixels);
}
let stride = self.width as usize * 4;
Some(
pixels
.chunks_exact(stride)
.rev()
.flatten()
.copied()
.collect(),
)
}
pub fn bytes_per_pixel(&self) -> usize {
assert!(
!self.format.is_block_compressed(),
"bytes_per_pixel on {:?}: block-compressed textures have no per-pixel \
stride — use TextureFormat::data_len / is_block_compressed",
self.format
);
self.format.bytes_per_block()
}
/// The same pixels and sampler settings, read in a different format.
///
/// For glTF, where one image can legitimately be both: sRGB when it is
/// baseColour, linear when it is a normal or metallic-roughness map. Gets a
/// fresh id, because the two are different GPU textures.
pub fn with_format(&self, format: TextureFormat) -> Self {
Self {
format,
id: next_texture_id(),
upload_seq: 0,
mips: Vec::new(),
..self.clone()
}
}
/// A twin of this texture with no CPU bytes, for keeping in a material
/// once the pixels are on the GPU.
///
/// Same [`id`](Self::id), so the renderer resolves it to the same uploaded
/// texture; empty `data`, so the copy in system memory can be dropped. The
/// caller must have uploaded it first — see
/// `HeadlessRenderer::preload_texture` — because nothing here can put the
/// bytes back.
///
/// This exists for the case where the bytes are large and numerous: a
/// planet split into tiles holds gigabytes of pixels that are pure
/// duplication the moment the GPU has them, and on unified memory that
/// duplication is not even in a different pool.
pub fn handle(&self) -> Self {
Self {
data: Arc::new(Vec::new()),
mips: Vec::new(),
..self.clone()
}
}
/// Whether this is a [`handle`](Self::handle) — metadata with no pixels.
pub fn is_handle(&self) -> bool {
self.data.is_empty() && self.width > 0 && self.height > 0
}
/// Bytes this texture's level 0 should occupy, block formats included.
pub fn data_len(&self) -> usize {
self.format.data_len(self.width, self.height)
}
/// Build a solid-color 1x1 texture in linear RGBA8. Useful as a placeholder
/// when a material slot is unused.
pub fn solid(rgba: [u8; 4], format: TextureFormat) -> Self {
Self::new(1, 1, format, rgba.to_vec())
}
}
/// An IEEE half as an `f32`.
fn half_to_f32(bits: u16) -> f32 {
crate::renderer::readback::f16_to_f32(bits)
}