diff --git a/design/ImageBitmapToTexture.md b/design/ImageBitmapToTexture.md new file mode 100644 index 0000000000..8487cccf0c --- /dev/null +++ b/design/ImageBitmapToTexture.md @@ -0,0 +1,37 @@ +# WebGPU + ImageBitmap + +```webidl +dictionary ImageBitmapCopyView { + ImageBitmap imageBitmap; + GPUOrigin2D origin; +}; + +partial interface GPUCommandEncoder { + void copyImageBitmapToTexture( + ImageBitmapCopyView source, + GPUTextureCopyView destination, + // For now, copySize.z must be 1. + GPUExtent3D copySize); +}; +``` + +`copyImageBitmapToTexture` encodes a copy from a source sub-rectangle of an `ImageBitmap` into a destination sub-resource of a `GPUTexture`. +When the command buffer is submitted, the `ImageBitmap` must not be detached. +If it is, a validation error is generated. + +## Alternatives Considered + + * Creating a `GPUTexture` directly from an `ImageBitmap`, attempting to avoid copies, is impractical because it requires the GPUTexture's format to match the internal representation of the `ImageBitmap`, which is not exposed to the Web platform. + Additionally, `ImageBitmap`s may be GPU- or CPU-backed, and wrapping a CPU-backed `ImageBitmap` is a significant meta-operation that requires an additional copy to be submitted. + +## Issues + + * Some of the `ImageBitmap` creation options, such as `"flipY"`, have semantics that have to match the target graphics API where the data is intended to be used. + For WebGL, `imageOrientation: "flipY"` is necessary to ensure that the resulting `WebGLTexture` is oriented correctly. + For WebGPU, it may be the case that texture origins are defined differently from WebGL, necessitating `imageOrientation: "none"`. + These cases will have to be thoroughly tested. + + * The browser may choose an internal representation for an `ImageBitmap` which is not ideal for usage by WebGPU (or, for that matter, [by WebGL](https://crbug.com/831740)). + This could result in texture uploads being significantly more expensive than necessary due to per-pixel data swizzling during upload. + Providing any hint about the intended usage of the `ImageBitmap` during its construction (for example "for use with WebGL" or "for use with this WebGPU adapter") would require changes to the HTML specification. + Attempts to change Chrome's internal representation of `ImageBitmap` have not yet been successful; it's not clear how feasible it would be in other browsers. diff --git a/spec/index.bs b/spec/index.bs index fe59e1e6af..542875c13a 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -30,6 +30,11 @@ dictionary GPUColor { required float a; }; +dictionary GPUOrigin2D { + u32 x = 0; + u32 y = 0; +}; + dictionary GPUOrigin3D { u32 x = 0; u32 y = 0; @@ -691,6 +696,11 @@ dictionary GPUTextureCopyView { GPUOrigin3D origin; // defaults to {x: 0, y: 0, z: 0} }; +dictionary ImageBitmapCopyView { + ImageBitmap imageBitmap; + GPUOrigin2D origin; +}; + interface GPUCommandBuffer : GPUObjectBase { }; @@ -721,6 +731,12 @@ interface GPUCommandEncoder : GPUObjectBase { GPUTextureCopyView destination, GPUExtent3D copySize); + void copyImageBitmapToTexture( + ImageBitmapCopyView source, + GPUTextureCopyView destination, + // For now, copySize.z must be 1. + GPUExtent3D copySize); + // Debugging assistance void pushDebugGroup(DOMString groupLabel); void popDebugGroup();