use super::{
Arc, Color, Duration, Error, ImageBudget, ImageError, ImageSampling, ImageTexelRect, Instant,
Mesh3dResourceError, Object3dId, RetainedMesh3d, Scene3d, Scene3dError, SurfaceLayout,
SurfacePipelines, WgpuRenderer, create_surface_pipelines, fmt, image, lighting,
submit_pending_uploads,
};
use crate::mesh3d::{TextureAddressMode3d, TextureCoordinate2d, TextureUvTransform3d};
mod mips;
use mips::CpuMipChain;
pub use mips::TextureMipmaps3d;
mod options;
pub use options::Texture3dOptions;
mod creation;
#[cfg(test)]
pub(super) use creation::{create_texture_with_options, crop_texture_tile};
mod updates;
pub use updates::{
Texture3dUpdateBudget, Texture3dUpdateBudgetResource, Texture3dUpdateError,
Texture3dUpdateReport,
};
#[cfg(test)]
pub(super) use updates::{update_scene_texture_region, update_texture_region};
#[cfg(test)]
mod tests;
#[cfg(test)]
pub(super) use tests::{
assert_gpu_partial_mip_recovery, assert_gpu_partial_mip_updates,
assert_gpu_restored_material_policy, assert_gpu_texture_contract, assert_gpu_texture_lifecycle,
assert_gpu_texture_lifecycle_recovery, assert_gpu_textured_recovery, benchmark_texture_updates,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Texture3dError {
Image(ImageError),
NonOpaquePixel {
texel: usize,
},
InvalidTint,
MissingTextureCoordinates,
RendererMismatch,
InvalidRegion,
MipmappedAtlasRegion,
}
impl fmt::Display for Texture3dError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Image(error) => write!(formatter, "3D texture: {error}"),
Self::NonOpaquePixel { texel } => {
write!(formatter, "3D texture texel {texel} is not opaque")
}
Self::InvalidTint => write!(
formatter,
"3D texture tint must be normalized; alpha requires the explicit with_alpha constructor"
),
Self::MissingTextureCoordinates => {
write!(formatter, "textured 3D surfaces require per-vertex UVs")
}
Self::RendererMismatch => {
write!(formatter, "3D texture/mesh belongs to another renderer")
}
Self::InvalidRegion => write!(formatter, "3D texture atlas region is out of bounds"),
Self::MipmappedAtlasRegion => write!(
formatter,
"crop an independent 3D tile before mip filtering; atlas UV insets do not isolate mip levels"
),
}
}
}
impl Error for Texture3dError {}
struct TextureStorage {
renderer_identity: Arc<()>,
chain: CpuMipChain,
texture: wgpu::Texture,
bindings: [wgpu::BindGroup; 4],
preserve_alpha: bool,
first_nonopaque_texel: Option<usize>,
}
#[derive(Clone)]
pub struct Texture3d {
storage: Arc<TextureStorage>,
}
impl Texture3d {
pub fn size(&self) -> (u32, u32) {
self.storage.chain.size()
}
pub fn pixels(&self) -> &[u8] {
self.storage.chain.pixels()
}
pub fn mip_level_count(&self) -> u32 {
self.storage.chain.levels().len() as u32
}
pub fn mip_level_pixels(&self, level: u32) -> Option<&[u8]> {
self.storage
.chain
.levels()
.get(level as usize)
.map(|level| self.storage.chain.level_pixels(*level))
}
pub fn mip_level_size(&self, level: u32) -> Option<(u32, u32)> {
self.storage
.chain
.levels()
.get(level as usize)
.map(|level| (level.width, level.height))
}
pub fn mipmaps(&self) -> TextureMipmaps3d {
self.storage.chain.mode()
}
pub fn options(&self) -> Texture3dOptions {
Texture3dOptions::new()
.with_mipmaps(self.mipmaps())
.with_alpha_preservation(self.preserves_alpha())
}
pub fn preserves_alpha(&self) -> bool {
self.storage.preserve_alpha
}
pub fn budget(&self) -> ImageBudget {
self.storage.chain.budget()
}
pub fn recovery_memory_bytes(&self) -> usize {
self.storage.chain.recovery_memory_bytes()
}
pub fn gpu_allocation_bytes(&self) -> usize {
self.storage.chain.gpu_allocation_bytes()
}
pub fn region_coordinates(
&self,
region: ImageTexelRect,
) -> Result<[TextureCoordinate2d; 4], Texture3dError> {
if self.mip_level_count() > 1 {
return Err(Texture3dError::MipmappedAtlasRegion);
}
let (width, height) = self.size();
if !region.fits(width, height) {
return Err(Texture3dError::InvalidRegion);
}
let left = (region.x() as f64 + 0.5) / f64::from(width);
let right = (f64::from(region.x()) + f64::from(region.width()) - 0.5) / f64::from(width);
let top = (region.y() as f64 + 0.5) / f64::from(height);
let bottom = (f64::from(region.y()) + f64::from(region.height()) - 0.5) / f64::from(height);
let make = |u: f64, v: f64| {
TextureCoordinate2d::new(u as f32, v as f32).map_err(|_| Texture3dError::InvalidRegion)
};
Ok([
make(left, top)?,
make(right, top)?,
make(right, bottom)?,
make(left, bottom)?,
])
}
pub(super) fn identity_key(&self) -> usize {
Arc::as_ptr(&self.storage) as usize
}
pub(super) fn belongs_to(&self, identity: &Arc<()>) -> bool {
Arc::ptr_eq(identity, &self.storage.renderer_identity)
}
fn bind_group(
&self,
sampling: ImageSampling,
address: TextureAddressMode3d,
) -> &wgpu::BindGroup {
&self.storage.bindings[usize::from(address == TextureAddressMode3d::Repeat) * 2
+ usize::from(sampling == ImageSampling::Linear)]
}
}
#[derive(Clone)]
pub struct TextureMaterial3d {
texture: Texture3d,
sampling: ImageSampling,
tint: Color,
uv_transform: TextureUvTransform3d,
address_mode: TextureAddressMode3d,
require_opaque_texture: bool,
}
impl TextureMaterial3d {
pub fn new(
texture: &Texture3d,
sampling: ImageSampling,
tint: Color,
) -> Result<Self, Texture3dError> {
if !tint.is_normalized() || tint.alpha() != 1.0 {
return Err(Texture3dError::InvalidTint);
}
if let Some(texel) = texture.storage.first_nonopaque_texel {
return Err(Texture3dError::NonOpaquePixel { texel });
}
let mut material = Self::with_alpha(texture, sampling, tint)?;
material.require_opaque_texture = true;
Ok(material)
}
pub fn with_alpha(
texture: &Texture3d,
sampling: ImageSampling,
tint: Color,
) -> Result<Self, Texture3dError> {
if !tint.is_normalized() {
return Err(Texture3dError::InvalidTint);
}
Ok(Self {
texture: texture.clone(),
sampling,
tint,
uv_transform: TextureUvTransform3d::IDENTITY,
address_mode: TextureAddressMode3d::Clamp,
require_opaque_texture: false,
})
}
pub fn with_uv_transform(mut self, transform: TextureUvTransform3d) -> Self {
self.uv_transform = transform;
self
}
pub fn with_address_mode(mut self, mode: TextureAddressMode3d) -> Self {
self.address_mode = mode;
self
}
pub fn with_texture(&self, texture: &Texture3d) -> Result<Self, Texture3dError> {
if self.require_opaque_texture
&& let Some(texel) = texture.storage.first_nonopaque_texel
{
return Err(Texture3dError::NonOpaquePixel { texel });
}
Ok(self.with_restored_texture(texture))
}
pub const fn uv_transform(&self) -> TextureUvTransform3d {
self.uv_transform
}
pub const fn address_mode(&self) -> TextureAddressMode3d {
self.address_mode
}
pub const fn texture(&self) -> &Texture3d {
&self.texture
}
pub const fn sampling(&self) -> ImageSampling {
self.sampling
}
pub const fn tint(&self) -> Color {
self.tint
}
pub(super) fn bind_group(&self) -> &wgpu::BindGroup {
self.texture.bind_group(self.sampling, self.address_mode)
}
pub(super) fn with_restored_texture(&self, texture: &Texture3d) -> Self {
Self {
texture: texture.clone(),
sampling: self.sampling,
tint: self.tint,
uv_transform: self.uv_transform,
address_mode: self.address_mode,
require_opaque_texture: self.require_opaque_texture,
}
}
}
#[repr(C)]
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
pub(super) struct MeshUvGpu {
pub(super) coordinate: [f32; 2],
}
impl MeshUvGpu {
const ATTRIBUTES: [wgpu::VertexAttribute; 1] = wgpu::vertex_attr_array![5 => Float32x2];
pub(super) const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
array_stride: std::mem::size_of::<Self>() as u64,
step_mode: wgpu::VertexStepMode::Vertex,
attributes: &Self::ATTRIBUTES,
};
}
pub(super) struct MeshTextureRenderer {
pub(super) layout: wgpu::BindGroupLayout,
pub(super) retained_pipeline: SurfacePipelines,
pub(super) clipped_pipeline: SurfacePipelines,
pub(super) colored_retained_pipeline: SurfacePipelines,
pub(super) colored_clipped_pipeline: SurfacePipelines,
}
impl MeshTextureRenderer {
pub(super) fn new(
device: &wgpu::Device,
format: wgpu::TextureFormat,
camera_layout: &wgpu::BindGroupLayout,
) -> Self {
let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("sim-engine 3D texture layout"),
entries: &[
wgpu::BindGroupLayoutEntry {
binding: 0,
visibility: wgpu::ShaderStages::FRAGMENT,
ty: wgpu::BindingType::Texture {
sample_type: wgpu::TextureSampleType::Float { filterable: true },
view_dimension: wgpu::TextureViewDimension::D2,
multisampled: false,
},
count: None,
},
wgpu::BindGroupLayoutEntry {
binding: 1,
visibility: wgpu::ShaderStages::FRAGMENT,
ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
count: None,
},
],
});
let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("sim-engine textured 3D surfaces"),
source: wgpu::ShaderSource::Wgsl(lighting::shader_source(include_str!(
"primitive.wgsl"
))),
});
let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("sim-engine textured 3D pipeline layout"),
bind_group_layouts: &[Some(camera_layout), Some(&layout)],
immediate_size: 0,
});
let pipeline = |clipped: bool, colored: bool| {
create_surface_pipelines(
device,
format,
&pipeline_layout,
&shader,
SurfaceLayout {
clipped,
colored,
textured: true,
},
)
};
Self {
retained_pipeline: pipeline(false, false),
clipped_pipeline: pipeline(true, false),
colored_retained_pipeline: pipeline(false, true),
colored_clipped_pipeline: pipeline(true, true),
layout,
}
}
}
impl WgpuRenderer {
pub fn create_texture3d_rgba8(
&self,
width: u32,
height: u32,
pixels: Vec<u8>,
budget: ImageBudget,
) -> Result<Texture3d, Texture3dError> {
create_texture(
&self.device,
&self.queue,
&self.renderer_identity,
&self.mesh3d_renderer.textures.layout,
width,
height,
pixels,
budget,
)
}
pub fn create_texture3d_rgba8_with_alpha(
&self,
width: u32,
height: u32,
pixels: Vec<u8>,
budget: ImageBudget,
) -> Result<Texture3d, Texture3dError> {
create_texture_with_alpha(
&self.device,
&self.queue,
&self.renderer_identity,
&self.mesh3d_renderer.textures.layout,
width,
height,
pixels,
budget,
)
}
pub fn restore_texture3d(&self, source: &Texture3d) -> Result<Texture3d, Texture3dError> {
restore_texture(
&self.device,
&self.queue,
&self.renderer_identity,
&self.mesh3d_renderer.textures.layout,
source,
)
}
pub fn with_mesh3d_material(
&self,
mesh: &RetainedMesh3d,
material: &TextureMaterial3d,
) -> Result<RetainedMesh3d, Texture3dError> {
attach_material(&self.renderer_identity, mesh, material)
}
}
pub(super) fn restore_texture(
device: &wgpu::Device,
queue: &wgpu::Queue,
identity: &Arc<()>,
layout: &wgpu::BindGroupLayout,
source: &Texture3d,
) -> Result<Texture3d, Texture3dError> {
source
.storage
.chain
.validate_device_limit(device.limits().max_texture_dimension_2d)
.map_err(Texture3dError::Image)?;
let chain = source
.storage
.chain
.try_clone()
.map_err(Texture3dError::Image)?;
Ok(upload_chain(
device,
queue,
identity,
layout,
chain,
source.preserves_alpha(),
))
}
pub(super) fn attach_material(
identity: &Arc<()>,
mesh: &RetainedMesh3d,
material: &TextureMaterial3d,
) -> Result<RetainedMesh3d, Texture3dError> {
if !Arc::ptr_eq(identity, &mesh.renderer_identity) || !material.texture.belongs_to(identity) {
return Err(Texture3dError::RendererMismatch);
}
if mesh.source.texture_coordinates().len() != mesh.source.vertices().len()
|| mesh.source.triangle_count() == 0
|| mesh.texture_coordinate_buffer.is_none()
{
return Err(Texture3dError::MissingTextureCoordinates);
}
let mut result = mesh.clone();
result.material = Some(material.clone());
Ok(result)
}
pub(super) fn material_uv_parameters(material: Option<&TextureMaterial3d>) -> [f32; 4] {
let transform = material.map_or(
TextureUvTransform3d::IDENTITY,
TextureMaterial3d::uv_transform,
);
[
transform.scale().x(),
transform.scale().y(),
transform.offset().x(),
transform.offset().y(),
]
}
#[allow(clippy::too_many_arguments)]
pub(super) fn create_texture(
device: &wgpu::Device,
queue: &wgpu::Queue,
identity: &Arc<()>,
layout: &wgpu::BindGroupLayout,
width: u32,
height: u32,
pixels: Vec<u8>,
budget: ImageBudget,
) -> Result<Texture3d, Texture3dError> {
create_texture_impl(
device, queue, identity, layout, width, height, pixels, budget, false,
)
}
#[allow(clippy::too_many_arguments)]
pub(super) fn create_texture_with_alpha(
device: &wgpu::Device,
queue: &wgpu::Queue,
identity: &Arc<()>,
layout: &wgpu::BindGroupLayout,
width: u32,
height: u32,
pixels: Vec<u8>,
budget: ImageBudget,
) -> Result<Texture3d, Texture3dError> {
create_texture_impl(
device, queue, identity, layout, width, height, pixels, budget, true,
)
}
#[allow(clippy::too_many_arguments)]
pub(super) fn create_texture_impl(
device: &wgpu::Device,
queue: &wgpu::Queue,
identity: &Arc<()>,
layout: &wgpu::BindGroupLayout,
width: u32,
height: u32,
pixels: Vec<u8>,
budget: ImageBudget,
preserve_alpha: bool,
) -> Result<Texture3d, Texture3dError> {
image::validate_image_shape(
width,
height,
pixels.len(),
budget,
device.limits().max_texture_dimension_2d,
)
.map_err(Texture3dError::Image)?;
let first_nonopaque_texel = pixels.chunks_exact(4).position(|pixel| pixel[3] != 255);
if !preserve_alpha && let Some(texel) = first_nonopaque_texel {
return Err(Texture3dError::NonOpaquePixel { texel });
}
let chain = CpuMipChain::new(
width,
height,
pixels,
budget,
device.limits().max_texture_dimension_2d,
TextureMipmaps3d::None,
)
.map_err(Texture3dError::Image)?;
Ok(upload_chain(
device,
queue,
identity,
layout,
chain,
preserve_alpha,
))
}
pub(super) fn upload_chain(
device: &wgpu::Device,
queue: &wgpu::Queue,
identity: &Arc<()>,
layout: &wgpu::BindGroupLayout,
chain: CpuMipChain,
preserve_alpha: bool,
) -> Texture3d {
let texture = chain.allocate_gpu(device);
let bindings = create_bindings(device, layout, &texture, chain.levels().len());
chain.upload_levels(queue, &texture, 0);
submit_pending_uploads(queue);
let first_nonopaque_texel = chain
.pixels()
.chunks_exact(4)
.position(|pixel| pixel[3] != 255);
Texture3d {
storage: Arc::new(TextureStorage {
renderer_identity: Arc::clone(identity),
chain,
texture,
bindings,
preserve_alpha,
first_nonopaque_texel,
}),
}
}
fn create_bindings(
device: &wgpu::Device,
layout: &wgpu::BindGroupLayout,
texture: &wgpu::Texture,
levels: usize,
) -> [wgpu::BindGroup; 4] {
let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
std::array::from_fn(|index| {
let address = if index >= 2 {
wgpu::AddressMode::Repeat
} else {
wgpu::AddressMode::ClampToEdge
};
let linear = index % 2 == 1;
let filter = if linear {
wgpu::FilterMode::Linear
} else {
wgpu::FilterMode::Nearest
};
let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
label: Some("sim-engine 3D texture sampler"),
address_mode_u: address,
address_mode_v: address,
mag_filter: filter,
min_filter: filter,
mipmap_filter: if linear {
wgpu::MipmapFilterMode::Linear
} else {
wgpu::MipmapFilterMode::Nearest
},
lod_min_clamp: 0.0,
lod_max_clamp: (levels - 1) as f32,
..Default::default()
});
device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("sim-engine 3D texture binding"),
layout,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: wgpu::BindingResource::TextureView(&view),
},
wgpu::BindGroupEntry {
binding: 1,
resource: wgpu::BindingResource::Sampler(&sampler),
},
],
})
})
}
pub(super) struct PreparedTextureRestore {
pub(super) key: usize,
pub(super) source: Texture3d,
pub(super) chain: Option<CpuMipChain>,
}
pub(super) fn prepare_scene_restoration(
device: &wgpu::Device,
identity: &Arc<()>,
scene: &Scene3d,
) -> Result<Vec<PreparedTextureRestore>, Mesh3dResourceError> {
let mut prepared = Vec::new();
prepared
.try_reserve_exact(scene.object_count())
.map_err(|_| Mesh3dResourceError::HostAllocationFailed {
requested_bytes: scene
.object_count()
.saturating_mul(std::mem::size_of::<PreparedTextureRestore>())
as u64,
})?;
for instance in scene.instances() {
if let Some(material) = instance.mesh.material()
&& !material.texture().belongs_to(identity)
{
prepared.push(PreparedTextureRestore {
key: material.texture().identity_key(),
source: material.texture().clone(),
chain: None,
});
}
}
prepared.sort_unstable_by_key(|texture| texture.key);
prepared.dedup_by_key(|texture| texture.key);
for texture in &mut prepared {
let source = &texture.source;
image::validate_image_shape(
source.size().0,
source.size().1,
source.pixels().len(),
source.budget(),
device.limits().max_texture_dimension_2d,
)
.map_err(|error| Mesh3dResourceError::Texture(Texture3dError::Image(error)))?;
source
.storage
.chain
.validate_device_limit(device.limits().max_texture_dimension_2d)
.map_err(|error| Mesh3dResourceError::Texture(Texture3dError::Image(error)))?;
texture.chain = Some(
source
.storage
.chain
.try_clone()
.map_err(|error| Mesh3dResourceError::Texture(Texture3dError::Image(error)))?,
);
}
Ok(prepared)
}