This adds HLSL backend support for `ImageClass::External` (ie WGSL's
`external_texture` texture type).
For each external texture global variable in the IR, we declare 3
`Texture2D` globals as well as a `cbuffer` for the params. The
additional bindings required by these are found in the newly added
`external_texture_binding_map`. Unique names for each can be obtained
using `NameKey::ExternalTextureGlobalVariable`.
For functions that contain ImageQuery::Size, ImageLoad, or ImageSample
expressions for external textures, ensure we have generated wrapper
functions for those expressions. When emitting code for the
expressions themselves, simply insert a call to the wrapper function.
For size queries, we return the value provided in the params
struct. If that value is [0, 0] then we query the size of the plane 0
texture and return that.
For load and sample, we sample the textures based on the number of
planes specified in the params struct. If there is more than one plane
we additionally perform YUV to RGB conversion using the provided
matrix.
Unfortunately HLSL does not allow structs to contain textures, meaning
we are unable to wrap the 3 textures and params struct variables in a
single variable that can be passed around.
For our wrapper functions we therefore ensure they take the three
textures and the params as consecutive arguments. Likewise, when
declaring user-defined functions with external texture arguments, we
expand the single external texture argument into 4 consecutive
arguments. (Using NameKey::ExternalTextureFunctionArgument to ensure
unique names for each.)
Thankfully external textures can only be used as either global
variables or function arguments. This means we only have to handle the
`Expression::GlobalVariable` and `Expression::FunctionArgument` cases
of `write_expr()`. Since in both cases we know the external texture
can only be an argument to either a user-defined function or one of
our wrapper functions, we can simply emit the names of the variables
for each three textures and the params struct in a comma-separated
list.
* Additional validation of buffer-texture copies
Fixes#7936, but leaves a TODO for #7947
* Skip tests failing on dx12
* Update comments and change unwrap_or to expect
`ExternalTexture` will form the basis of wgpu's implementation of
WebGPU's `GPUExternalTexture`. [1]
The application will be responsible for creating `Texture`(s) and
`TextureView`(s) from the external texture source and managing their
lifecycle. It may have a single RGBA texture, or it may have multiple
textures for separate Y and Cb/Cr planes. It can then create an external
texture by calling `create_external_texture()`, providing the texture
views and a descriptor. The descriptor provides the following required
information:
* Whether the texture data is RGBA, or multiplanar or interleaved
YCbCr.
* The purpoted size of the external texture, which may not match the
actual size of the underlying textures.
* A matrix for converting from YCbCr to RGBA, if required.
* A transform to apply to texture sample coordinates, allowing for
rotation and crop rects.
The external texture stores a reference to the provided texture views,
and additionally owns a `Buffer`. This buffer holds data of the type
`ExternalTextureParams`, and will be provided as a uniform buffer to
shaders containing external textures. This contains information that
will be required by the shaders to handle external textures correctly.
Note that attempting to create an external texture will fail unless the
`Feature::EXTERNAL_TEXTURE` feature is enabled, which as of yet is not
supported by any HAL backends.
Additionally add the relevant API to wgpu, implemented for the
wgpu-core backend. The web and custom backends are unimplemented.
[1] https://www.w3.org/TR/webgpu/#gpuexternaltexture
Adds a new feature flag, `EXTERNAL_TEXTURE`, indicating device support
for our implementation of WebGPU's `GPUExternalTexture` [1] which will
land in upcoming patches. Conceptually this would make more sense as a
downlevel flag, as it is a core part of the WebGPU spec which we do not
yet support. We do not want, however, to cause applications to reject
adapters because we have not finished implementing this, so for now we
are making it an opt-in feature.
As an initial step towards supporting this feature, this patch adds a
new `BindingType` corresponding to WebGPU's
`GPUExternalTextureBindingLayout` [2]. This binding type dictates that
when creating a bind group the corresponding entry must be either an
external texture or a texture view with certain additional requirements
[3].
As of yet wgpu has no concept of an external texture (that will follow
in later patches) but for now this patch ensures that texture views
corresponding to an external texture binding type are validated
correctly. Note that as the feature flag is not yet supported on any
real backends, bind group layout creation will fail before getting the
chance to attempt to create a bind group. But in the added tests using
the noop backend we can see this validation taking place.
[1] https://www.w3.org/TR/webgpu/#gpuexternaltexture
[1] https://www.w3.org/TR/webgpu/#dictdef-gpuexternaltexturebindinglayout
[2] https://gpuweb.github.io/gpuweb/#bind-group-creation
With the only caveat that device creation will now panic if the `wgsl` feature is not enabled, `InstanceFlags::VALIDATION_INDIRECT_CALL` is set and the device supports `DownlevelFlags::INDIRECT_EXECUTION`.
* Added “upward” links from `VertexAttribute` and `VertexBufferLayout`
to the places they are used.
* Documented the exact expected inputs of `vertex_attr_array!` and hid
the internal implementation.
* Added doc-test examples for:
* `VertexBufferLayout`, demonstrating how to construct a
`VertexBufferLayout` that corresponds to a `struct`.
* `vertex_attr_array!`, demonstrating exactly what the output of the
macro is.
This will help users determine whether the problem is:
* a backend is not statically enabled
* a backend is not dynamically enabled
* no drivers or physical adapters are present for that backend
(further distinction would be useful here)
* no adapters met the required criteria
There are deficiencies in the reporting of WebGPU vs. WebGL support.
Those would best be fixed by also fixing the mutual exclusion of those
backends.
