diff --git a/CHANGELOG.md b/CHANGELOG.md index 23e426125..2ee28090d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -91,6 +91,7 @@ By @sagudev in [#10109](https://github.com/gfx-rs/wgpu/pull/10109). - `wgpu-core` now exposes `validate_device_descriptor` and `validate_texture_descriptor` functions that perform the same descriptor validation the corresponding resource creation APIs would, without actually creating a resource. This may be useful in conjunction with hal raw APIs. By @andyleiserson in [#9967](https://github.com/gfx-rs/wgpu/pull/9967) and [#9979](https://github.com/gfx-rs/wgpu/pull/9979). - Added `TextureDescriptor::theoretical_memory_footprint` to estimate memory footprint of a texture. By @sagudev in [#10032](https://github.com/gfx-rs/wgpu/pull/10032). - `wgpu::WriteOnly<[_]>` now implements `Send`. By @kpreid in [#10163](https://github.com/gfx-rs/wgpu/pull/10163). +- Added `Texture::mark_externally_initialized()` to stop a texture from being lazily cleared if it was written to externally (e.g. via `as_hal`). By @R-Cramer4 in [#10075](https://github.com/gfx-rs/wgpu/pull/10075). #### Hal diff --git a/tests/tests/wgpu-gpu/zero_init.rs b/tests/tests/wgpu-gpu/zero_init.rs index 25c8e6805..c16b6cf42 100644 --- a/tests/tests/wgpu-gpu/zero_init.rs +++ b/tests/tests/wgpu-gpu/zero_init.rs @@ -87,6 +87,7 @@ pub fn all_tests(vec: &mut Vec) { VERTEX_BUFFER_TAIL_INIT_MAP_WRITE_MAPPED_AT_CREATION, COPY_TEXTURE_TO_BUFFER_UNALIGNED_OFFSET_ROW_PADDING_INIT, COPY_TEXTURE_TO_BUFFER_UNALIGNED_OFFSET_IMAGE_PADDING_INIT, + MARK_EXTERNALLY_INITIALIZED_SKIPS_LAZY_CLEAR, ]); } @@ -2824,3 +2825,198 @@ async fn test_copy_texture_to_buffer_padding_init( "the destination buffer of copies from a never-written texture is not all zero", ); } + +#[apply(gpu_test!)] +static MARK_EXTERNALLY_INITIALIZED_SKIPS_LAZY_CLEAR: GpuTestConfiguration = + GpuTestConfiguration::new() + .parameters( + TestParameters::default() + .limits(Limits::downlevel_defaults()) + // This test pokes at raw hal texture state, which is only + // exercised below for the desktop-native backends. + .skip(FailureCase::backend( + Backends::all() - (Backends::VULKAN | Backends::METAL | Backends::DX12), + )), + ) + .run_async(|ctx| async move { + match ctx.adapter_info.backend { + #[cfg(any( + target_os = "windows", + target_os = "linux", + target_os = "android", + target_os = "freebsd" + ))] + Backend::Vulkan => { + check_mark_externally_initialized::(&ctx).await; + } + #[cfg(target_vendor = "apple")] + Backend::Metal => { + check_mark_externally_initialized::(&ctx).await; + } + #[cfg(target_os = "windows")] + Backend::Dx12 => { + check_mark_externally_initialized::(&ctx).await; + } + other => unreachable!( + "test is configured to skip all backends except Vulkan/Metal/Dx12, \ + but ran on {other:?}" + ), + } + }); + +#[cfg(any( + target_os = "windows", + target_os = "linux", + target_os = "android", + target_os = "freebsd", + target_vendor = "apple" +))] +async fn check_mark_externally_initialized(ctx: &TestingContext) { + check_mark_externally_initialized_case::(ctx, false).await; + check_mark_externally_initialized_case::(ctx, true).await; +} + +#[cfg(any( + target_os = "windows", + target_os = "linux", + target_os = "android", + target_os = "freebsd", + target_vendor = "apple" +))] +async fn check_mark_externally_initialized_case(ctx: &TestingContext, mark: bool) { + use core::iter; + use wgpu::hal::{CommandEncoder as _, Device as _}; + + const SENTINEL: u8 = 0xAB; + // `Rgba8Unorm` at this width gives exactly `COPY_BYTES_PER_ROW_ALIGNMENT` bytes per + // row, so the raw hal copy below needs no extra row padding. + let size = Extent3d { + width: COPY_BYTES_PER_ROW_ALIGNMENT / 4, + height: 4, + depth_or_array_layers: 1, + }; + let bytes_per_row = size.width * 4; + let buffer_size = u64::from(bytes_per_row * size.height); + + let texture = ctx.device.create_texture(&TextureDescriptor { + label: Some("mark_externally_initialized target"), + size, + mip_level_count: 1, + sample_count: 1, + dimension: TextureDimension::D2, + format: TextureFormat::Rgba8Unorm, + usage: TextureUsages::COPY_SRC | TextureUsages::COPY_DST, + view_formats: &[], + }); + + // Write a non-zero pattern into the texture through its raw hal handle, entirely + // bypassing wgpu-core's command recording (and thus its init tracking) for the + // texture. This simulates e.g. a video decoder writing into the texture through + // native driver APIs. + // + // SAFETY: `hal_device`, `hal_texture`, and `raw_encoder` are all obtained from the + // same wgpu `Device`, and are only used to write and destroy resources not tracked + // by wgpu-core. + unsafe { + let hal_device = ctx.device.as_hal::().expect("adapter backend mismatch"); + let hal_texture = texture.as_hal::().expect("adapter backend mismatch"); + + let staging_buffer = hal_device + .create_buffer(&hal::BufferDescriptor { + label: Some("mark_externally_initialized staging"), + size: buffer_size, + usage: wgt::BufferUses::MAP_WRITE | wgt::BufferUses::COPY_SRC, + memory_flags: hal::MemoryFlags::TRANSIENT | hal::MemoryFlags::PREFER_COHERENT, + }) + .expect("failed to create staging buffer"); + { + let mapping = hal_device + .map_buffer(&staging_buffer, 0..buffer_size) + .expect("failed to map staging buffer"); + core::ptr::write_bytes(mapping.ptr.as_ptr(), SENTINEL, buffer_size as usize); + if !mapping.is_coherent { + hal_device.flush_mapped_ranges(&staging_buffer, iter::once(0..buffer_size)); + } + hal_device.unmap_buffer(&staging_buffer); + } + + let mut encoder = ctx + .device + .create_command_encoder(&CommandEncoderDescriptor { label: None }); + encoder.as_hal_mut::(|raw_encoder| { + let raw_encoder = raw_encoder.expect("adapter backend mismatch"); + raw_encoder.transition_textures(iter::once(hal::TextureBarrier { + texture: &*hal_texture, + range: wgt::ImageSubresourceRange::default(), + usage: hal::StateTransition { + from: wgt::TextureUses::UNINITIALIZED, + to: wgt::TextureUses::COPY_DST, + }, + queue_family_ownership_transfer: None, + })); + raw_encoder.copy_buffer_to_texture( + &staging_buffer, + &*hal_texture, + iter::once(hal::BufferTextureCopy { + buffer_layout: TexelCopyBufferLayout { + offset: 0, + bytes_per_row: Some(bytes_per_row), + rows_per_image: None, + }, + texture_base: hal::TextureCopyBase { + mip_level: 0, + array_layer: 0, + origin: Origin3d::ZERO, + aspect: hal::FormatAspects::COLOR, + }, + size: hal::CopyExtent { + width: size.width, + height: size.height, + depth: 1, + }, + }), + ); + raw_encoder.transition_textures(iter::once(hal::TextureBarrier { + texture: &*hal_texture, + range: wgt::ImageSubresourceRange::default(), + usage: hal::StateTransition { + from: wgt::TextureUses::COPY_DST, + to: wgt::TextureUses::COPY_SRC, + }, + queue_family_ownership_transfer: None, + })); + }); + // Release the texture's snatch-lock guard before submitting: queue submission + // needs to acquire it too, and it is not reentrant. + drop(hal_texture); + ctx.queue.submit(Some(encoder.finish())); + ctx.async_poll(PollType::wait_indefinitely()).await.unwrap(); + + hal_device.destroy_buffer(staging_buffer); + } + + if mark { + unsafe { texture.mark_externally_initialized() }; + } + + let readback_buffers = ReadbackBuffers::new(&ctx.device, &texture); + let mut encoder = ctx + .device + .create_command_encoder(&CommandEncoderDescriptor { label: None }); + readback_buffers.copy_from(&ctx.device, &mut encoder, &texture); + ctx.queue.submit(Some(encoder.finish())); + + if mark { + assert!( + !readback_buffers.are_zero(ctx).await, + "texture written through as_hal and marked externally initialized was \ + still lazily cleared to zero before being read back", + ); + } else { + assert!( + readback_buffers.are_zero(ctx).await, + "texture written through as_hal without being marked externally initialized \ + was not lazily cleared to zero as expected", + ); + } +} diff --git a/wgpu-core-remote/src/global/device.rs b/wgpu-core-remote/src/global/device.rs index 5ecae86c5..2220e5516 100644 --- a/wgpu-core-remote/src/global/device.rs +++ b/wgpu-core-remote/src/global/device.rs @@ -320,6 +320,17 @@ impl Global { hub.textures.remove(texture_id) } + /// # Safety + /// + /// The entire contents of the texture must already be initialized. + pub unsafe fn texture_mark_externally_initialized(&self, texture_id: id::TextureId) { + let hub = &self.hub.borrow(); + + let texture = hub.textures.get(texture_id); + + unsafe { texture.mark_externally_initialized() }; + } + pub fn texture_create_view( &self, texture_id: id::TextureId, diff --git a/wgpu-core/src/resource.rs b/wgpu-core/src/resource.rs index 353ed8c6f..615e6a373 100644 --- a/wgpu-core/src/resource.rs +++ b/wgpu-core/src/resource.rs @@ -2196,6 +2196,19 @@ impl Texture { pub fn descriptor(&self) -> &wgt::TextureDescriptor> { &self.desc } + + /// Marks the texture's entire contents as already initialized, + /// skipping wgpu-core's lazy zero-initialization of it. + /// + /// # Safety + /// + /// The entire contents of the texture must already be initialized. + pub unsafe fn mark_externally_initialized(&self) { + let mut initialization_status = self.initialization_status.write(); + for mip_tracker in initialization_status.mips.iter_mut() { + mip_tracker.drain(0..self.desc.array_layer_count()); + } + } } /// A texture that has been marked as destroyed and is staged for actual deletion soon. diff --git a/wgpu/src/api/texture.rs b/wgpu/src/api/texture.rs index a30a44763..c076b8503 100644 --- a/wgpu/src/api/texture.rs +++ b/wgpu/src/api/texture.rs @@ -181,6 +181,20 @@ impl Texture { pub fn usage(&self) -> TextureUsages { self.inner.usage() } + + /// Marks this texture's contents as already initialized, skipping wgpu's + /// lazy zero-initialization of it. + /// + /// This is a no-op on backends without a concept of lazy + /// zero-initialization, such as WebGPU. + /// + /// # Safety + /// + /// The entire contents of the texture must already be initialized, e.g. by + /// writing to it through the handle returned by [`Texture::as_hal`]. + pub unsafe fn mark_externally_initialized(&self) { + unsafe { self.inner.mark_externally_initialized() } + } } /// Describes a [`Texture`]. diff --git a/wgpu/src/backend/wgpu_core.rs b/wgpu/src/backend/wgpu_core.rs index 3cc7878c6..1c2fa0639 100644 --- a/wgpu/src/backend/wgpu_core.rs +++ b/wgpu/src/backend/wgpu_core.rs @@ -1819,6 +1819,10 @@ impl dispatch::TextureInterface for CoreTexture { fn usage(&self) -> wgt::TextureUsages { self.wgpu_texture.descriptor().usage } + + unsafe fn mark_externally_initialized(&self) { + unsafe { self.wgpu_texture.mark_externally_initialized() } + } } impl dispatch::BlasInterface for CoreBlas { diff --git a/wgpu/src/dispatch.rs b/wgpu/src/dispatch.rs index bf99b78ba..b9e745783 100644 --- a/wgpu/src/dispatch.rs +++ b/wgpu/src/dispatch.rs @@ -308,6 +308,17 @@ pub trait TextureInterface: CommonTraits { fn format(&self) -> wgt::TextureFormat; fn usage(&self) -> wgt::TextureUsages; + + /// Marks this texture's contents as already initialized, skipping wgpu's + /// lazy zero-initialization of it. + /// + /// Defaults to a no-op, which is a valid implementation for backends + /// (such as WebGPU) that have no concept of lazy zero-initialization. + /// + /// # Safety + /// + /// The entire contents of the texture must already be initialized. + unsafe fn mark_externally_initialized(&self) {} } pub trait ExternalTextureInterface: CommonTraits { fn destroy(&self);