Add documentation for 5 simple Dawn extensions.
Bug: None
Change-Id: I00fbb727bff7ce1abde764af29837d724c29136f
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/161684
Kokoro: Kokoro <noreply+kokoro@google.com>
Reviewed-by: Austin Eng <enga@chromium.org>
Commit-Queue: Corentin Wallez <cwallez@chromium.org>
diff --git a/docs/dawn/features/angle_texture_sharing.md b/docs/dawn/features/angle_texture_sharing.md
new file mode 100644
index 0000000..4d5da04
--- /dev/null
+++ b/docs/dawn/features/angle_texture_sharing.md
@@ -0,0 +1,8 @@
+# ANGLE Texture Sharing
+
+Available only on the OpenGL ES backend when running on top of ANGLE.
+When a device is created with this extension, it is added to the `EGL_DISPLAY_TEXTURE_SHARE_GROUP_ANGLE` which is a display-wide share context, but only for texturs.
+
+When enabled, `dawn::native::opengl::ExternalImageDescriptorGLTexture` and `dawn::native::opengl::WrapExternalGLTexture` become available which can import a GL texture into a `wgpu::Device` with a GL texture ID.
+
+See the spec for [`EGL_ANGLE_display_texture_share_group`](https://chromium.googlesource.com/angle/angle/+/refs/heads/main/extensions/EGL_ANGLE_display_texture_share_group.txt).
diff --git a/docs/dawn/features/d3d11_multithread_protected.md b/docs/dawn/features/d3d11_multithread_protected.md
new file mode 100644
index 0000000..e139688
--- /dev/null
+++ b/docs/dawn/features/d3d11_multithread_protected.md
@@ -0,0 +1,6 @@
+# D3D11 multithread protected
+
+Optional feature available on the D3D11 backend that when enabled makes all calls to the ID3D11DeviceContext happen inside a ID3D11Mulithread scope.
+This ensure that the D3D11 device can be used concurrently by other components, in particular ANGLE in Chromium.
+
+The initial tracking bug was crbug.com/dawn/1927.
diff --git a/docs/dawn/features/implicit_device_synchronization.md b/docs/dawn/features/implicit_device_synchronization.md
new file mode 100644
index 0000000..5071156
--- /dev/null
+++ b/docs/dawn/features/implicit_device_synchronization.md
@@ -0,0 +1,9 @@
+# Implicit Device Synchronization
+
+Makes most public API methods implicitly lock the device, making them safe to call in a multi-threaded environment.
+All commands for the `wgpu::Device` and child objects are safe, except command encoding which doesn't get implicit synchronization.
+
+Note that this extension is quite heavy-handed in terms of synchronization, and should eventually disappear in favor of proper fine-grained and efficient synchronization in Dawn.
+Also there are likely still cases where Dawn's reentrancy is not handled properly and could cause deadlocks with this extension.
+
+The initial tracking bug was https://crbug.com/dawn/1662.
diff --git a/docs/dawn/features/norm16_texture_formats.md b/docs/dawn/features/norm16_texture_formats.md
new file mode 100644
index 0000000..bd24854
--- /dev/null
+++ b/docs/dawn/features/norm16_texture_formats.md
@@ -0,0 +1,13 @@
+# Norm16 texture formats
+
+Adds support for norm16 formats with `CopySrc|CopyDest|RenderAttachment|TextureBinding` usages, multisampling and resolving capabilities.
+Additional formats are:
+
+ - `wgpu::TextureFormat::R16Snorm`
+ - `wgpu::TextureFormat::RG16Snorm`
+ - `wgpu::TextureFormat::RGBA16Snorm`
+ - `wgpu::TextureFormat::R16Unorm`
+ - `wgpu::TextureFormat::RG16Unorm`
+ - `wgpu::TextureFormat::RGBA16Unorm`
+
+The initial tracking bug was https://crbug.com/dawn/1982.
diff --git a/docs/dawn/features/timestamp_query_inside_passes.md b/docs/dawn/features/timestamp_query_inside_passes.md
new file mode 100644
index 0000000..427c5a9
--- /dev/null
+++ b/docs/dawn/features/timestamp_query_inside_passes.md
@@ -0,0 +1,20 @@
+# Timestamp Query Inside Passes (experimental!)
+
+Adds support for the `writeTimestamp` call inside render and compute passes.
+This method might not always make a lot of sense on tiler GPUs (so basically any modern GPU) where the ordering of operations inside render passes is not strictly like the order of commands recorded (each tile being executed independently),
+
+Adds the following methods:
+
+```
+voi wgpu::ComputePassEncoder::writeTimestamp(wgpu::QuerySet querySet, uint32_t queryIndex);
+voi wgpu::RenderPassEncoder::writeTimestamp(wgpu::QuerySet querySet, uint32_t queryIndex);
+```
+
+The validation is the following:
+
+ - `querySet` must be a valid query set.
+ - `querySet` must have been created with `wgpu::QueryType::Timestamp`.
+ - `queryIndex` must be less than `querySet`'s size.
+ - During the `wgpu::Queue::Submit` for these commands, `querySet` must not be destroyed.
+
+The initial tracking bug was https://crbug.com/dawn/434.
diff --git a/src/dawn/native/Features.cpp b/src/dawn/native/Features.cpp
index e3c8f11..a955654 100644
--- a/src/dawn/native/Features.cpp
+++ b/src/dawn/native/Features.cpp
@@ -64,7 +64,8 @@
FeatureInfo::FeatureState::Stable}},
{Feature::ChromiumExperimentalTimestampQueryInsidePasses,
{"Support experimental Timestamp Query inside render/compute pass",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=434",
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "timestamp_query_inside_passes.md",
FeatureInfo::FeatureState::Experimental}},
{Feature::DepthClipControl,
{"Disable depth clipping of primitives to the clip volume",
@@ -143,7 +144,9 @@
{Feature::ImplicitDeviceSynchronization,
{"Public API methods (except encoding) will have implicit device synchronization. So they "
"will be safe to be used on multiple threads.",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=1662", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "implicit_device_synchronization.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::SurfaceCapabilities,
{"Support querying Surface's capabilities such as supported usage flags. This feature also "
"enables swap chain to be created with usage other than RenderAttachment.",
@@ -163,12 +166,14 @@
FeatureInfo::FeatureState::Experimental}},
{Feature::D3D11MultithreadProtected,
{"Enable ID3D11Multithread protection for interop with external users of the D3D11 device.",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=1927", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "d3d11_multithread_protected.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::ANGLETextureSharing,
{"Enable ANGLE texture sharing to allow the OpenGL ES backend to share textures by external "
"OpenGL texture ID.",
- "https://chromium.googlesource.com/angle/angle/+/refs/heads/main/extensions/"
- "EGL_ANGLE_display_texture_share_group.txt",
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "angle_texture_sharing.md",
FeatureInfo::FeatureState::Stable}},
{Feature::PixelLocalStorageCoherent,
{"Supports passing information between invocation in a render pass that cover the same pixel."
@@ -187,7 +192,9 @@
FeatureInfo::FeatureState::Experimental}},
{Feature::Norm16TextureFormats,
{"Supports R/RG/RGBA16 norm texture formats",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=1982", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "norm16_texture_formats.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::SharedTextureMemoryVkDedicatedAllocation,
{"Support specifying whether a Vulkan allocation for shared texture memory is a dedicated "
"memory allocation.",
