Added mark_externally_initialized to texture (#10075)

This commit is contained in:
Robin Cramer authored and GitHub committed 2026-08-31 10:21:25 -04:00
1 parent c5ab27023a
commit 64b9bb0e90
7 files changed
+250

No files matched your search

+1
View File
@@ -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
+196
View File
@@ -87,6 +87,7 @@ pub fn all_tests(vec: &mut Vec<GpuTestInitializer>) {
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::<hal::vulkan::Api>(&ctx).await;
}
#[cfg(target_vendor = "apple")]
Backend::Metal => {
check_mark_externally_initialized::<hal::metal::Api>(&ctx).await;
}
#[cfg(target_os = "windows")]
Backend::Dx12 => {
check_mark_externally_initialized::<hal::dx12::Api>(&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<A: hal::Api>(ctx: &TestingContext) {
check_mark_externally_initialized_case::<A>(ctx, false).await;
check_mark_externally_initialized_case::<A>(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<A: hal::Api>(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::<A>().expect("adapter backend mismatch");
let hal_texture = texture.as_hal::<A>().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::<A, _, ()>(|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",
);
}
}
+11
View File
@@ -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,
+13
View File
@@ -2196,6 +2196,19 @@ impl Texture {
pub fn descriptor(&self) -> &wgt::TextureDescriptor<String, Vec<wgt::TextureFormat>> {
&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.
+14
View File
@@ -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`].
+4
View File
@@ -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 {
+11
View File
@@ -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);