Document the multi-planar extensions
Bug: dawn:551
Change-Id: Id4c77f256655dcd3e5f83ea92c343358316c4456
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/161682
Reviewed-by: Austin Eng <enga@chromium.org>
Commit-Queue: Corentin Wallez <cwallez@chromium.org>
Kokoro: Kokoro <noreply+kokoro@google.com>
diff --git a/docs/dawn/features/multi_planar_format_nv12a.md b/docs/dawn/features/multi_planar_format_nv12a.md
deleted file mode 100644
index 35c4e7e..0000000
--- a/docs/dawn/features/multi_planar_format_nv12a.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Multi Planar Format NV12A (Experimental!)
-
-The `multi-planar-format-nv12a` feature allows rendering NV12 format with an extra alpha plane. A typical usage scenario of this feature is HEVC with Alpha video decoding feature on Chrome for Mac. macOS will directly decode the buffer into such format without extra YUVA to RGBA conversion, which turns out has better power efficiency.
-
-Notes:
- - The format is only available on macOS >= 10.15.
diff --git a/docs/dawn/features/multi_planar_formats.md b/docs/dawn/features/multi_planar_formats.md
new file mode 100644
index 0000000..53fa65e
--- /dev/null
+++ b/docs/dawn/features/multi_planar_formats.md
@@ -0,0 +1,57 @@
+# Multi Planar Formats
+
+Video is often decoded to formats with a full resolution luminance image and a lower resolution chrominance image.
+This is represented in GPU APIs with multi-planar color texture formats where plane 0 is luminance, plane 1 is chrominance and plane 2 an optional alpha channel. It is important to support these formats in Dawn because in combination with `wgpu::ExternalTexture` they can provide 0-copy access to video data with less memory bandwidth than if it were decoded to `RGBA8Unorm` textures.
+
+Dawn has a number of optional features that give access to some of these formats and texture capabilities.
+Note however that Dawn doesn't specify the semantics of the planes (luminance vs. chrominance), but instead just exposes multiple planes with varying sizes and formats.
+
+Multi planar formats introduce new `wgpu::TextureAspect` values `Plane0Only`, `Plane1Only` and `Plane2Only` to allow using a single aspect of multi planar textures in `TextureView` creation or copy operations. All multi planar formats support `wgpu::TextureUsage::TextureBinding` and `wgpu::TextureUsage::CopySrc` without any need for another optional feature (and cannot be created directly, only imported with `SharedTextureMemory`).
+
+TODO(dawn:551): It seems these aspects enums are always allowed. Maybe they should be gated on the base feature?
+
+## `DawnMultiPlanarFormats`
+
+This feature adds support for "NV12", a common format for decoded SDR videos.
+It is composed of:
+
+ - a full-res `R8Unorm` plane 0 (luminance)
+ - an half res `RG8Unorm` plane 1 (chrominance).
+
+For historical reasons the feature is called `DawnMultiPlanarFormats`.
+This format is called `wgpu::TextureFormat::R8BG8Biplanar420Unorm`.
+
+TODO(dawn:551): Rename to MultiPlanarFormatNV12 ?
+
+## `MultiPlanarFormatP010`
+
+This feature adds support for "P010", a common format for decoded HDR videos.
+It is composed of:
+
+ - a full-res `R16Unorm` plane 0 (luminance) with only the first 10 bits used in the decoding of the videos.
+ - an half res `RG16Unorm` plane 1 (chrominance) with only the first 10 bits of each channel used in the decoding of the videos.
+
+This format is called `wgpu::TextureFormat::R10X6BG10X6Biplanar420Unorm`.
+
+TODO(dawn:551) is it possible to merge this feature with the nv12 feature?
+
+## `MultiPlanarFormatNV12A` (Experimental!)
+
+This feature adds support for "NV12", a format for decoded SDR videos with an alpha channel.
+It is composed of:
+
+ - a full-res `R8Unorm` plane 0 (luminance)
+ - an half res `` plane 1 (chrominance)
+ - an half res `r8unorm` plane 2 (alpha).
+
+This format is called `wgpu::TextureFormat::R8BG8Biplanar420Unorm`.
+
+At the moment it is only available on macOS >= 10.15.
+
+## `MultiPlanarFormatExtendedUsages`
+
+Adds the ability to create multi-planar textures with `device.CreateTexture()` and the `wgpu::TextureUsage::CopyDst`usage.
+
+## `MultiPlanarRenderTargets`
+
+Adds the `wgpu::TextureUsage::RenderAttachment` usage to multi planar formats.
diff --git a/src/dawn/native/Features.cpp b/src/dawn/native/Features.cpp
index 4435f5b..47fd613 100644
--- a/src/dawn/native/Features.cpp
+++ b/src/dawn/native/Features.cpp
@@ -111,27 +111,32 @@
FeatureInfo::FeatureState::Stable}},
{Feature::DawnMultiPlanarFormats,
{"Import and use multi-planar texture formats with per plane views",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=551", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "multi_planar_formats.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::MultiPlanarFormatExtendedUsages,
{"Enable creating multi-planar formatted textures directly without importing. Also allows "
"including CopyDst as texture's usage and per plane copies between a texture and a buffer.",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=551",
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "multi_planar_formats.md",
FeatureInfo::FeatureState::Experimental}},
- // TODO(dawn:551): Merge the feature 'MultiPlanarFormatP010' to 'DawnMultiPlanarFormats' once it
- // is implemented on all other missing backends.
{Feature::MultiPlanarFormatP010,
{"Import and use the P010 multi-planar texture format with per plane views",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=551", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "multi_planar_formats.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::MultiPlanarFormatNv12a,
{"Import and use the NV12A multi-planar texture format with per plane views",
"https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
- "multi_planar_format_nv12a.md",
+ "multi_planar_formats.md",
FeatureInfo::FeatureState::Experimental}},
{Feature::MultiPlanarRenderTargets,
{"Import and use multi-planar texture formats as render attachments",
- "https://bugs.chromium.org/p/dawn/issues/detail?id=1337", FeatureInfo::FeatureState::Stable}},
+ "https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
+ "multi_planar_formats.md",
+ FeatureInfo::FeatureState::Stable}},
{Feature::DawnNative,
- {"WebGPU is running on top of dawn_native.",
+ {"WebGPU is running on top of dawn_native, granting some additional capabilities.",
"https://dawn.googlesource.com/dawn/+/refs/heads/main/docs/dawn/features/"
"dawn_native.md",
FeatureInfo::FeatureState::Stable}},
