And from either AbstractFloat or AbstractInt to bool.
AbstractFloat to integer was presumably not implemented as *automatic*
conversion between those types is not allowed. However, explicit
conversions (for example `i32(1.0)`) are allowed, and are implemented
during const evaluation using the same code path in
ConstantEvaluator::cast().
The integer conversion constructors treat AbstractFloats as any other
floating point type, meaning we must follow the scalar floating point
to integral conversion algorithm [1]. This specifies:
To convert a floating point scalar value X to an integer scalar
type T:
* If X is a NaN, the result is an indeterminate value in T.
* If X is exactly representable in the target type T, then the
result is that value.
* Otherwise, the result is the value in T closest to truncate(X)
and also exactly representable in the original floating point
type.
Fortunately a rust cast satisfies all these conditions apart from the
result being exactly representable in the original floating point
type. However, as i32::MIN, i32::MAX, u32::MIN, and u32::MAX are all
representable by f64 (the underlying type of AbstractFloat), this is
not an issue.
For i64 and u64 using a rust cast will not meet that requirement, but
as these types are not present in the WGSL spec we are free to ignore
that.
[1] https://www.w3.org/TR/WGSL/#floating-point-conversion
A vector constructor with multiple arguments is represented in IR as a
Compose expression. These can be nested, for example due to code such
as this: `vec4(1, vec3(2, vec2(3, 4)))`. The total number of
components of each argument must match the vector size, meaning
`vec4(1, 2, 3, 4, 5)` is invalid. The validation pass already catches
such occurences. However, validation runs after constant evaluation,
meaning this can cause issues if the expression is evaluated as part
of a const expression.
When applying an operation to a vector compose during const
evaluation, we typically "flatten" the vector using the function
`proc::flatten_compose()`. This silently truncates the list of
components to the size implied by the type, meaning invalid code is
accepted.
This patch validates that the total number of components in a Compose
expression, once flattened, matches the size implied by the type. We
do so once as each expression is registered to avoid needing to handle
this each time the expression is used in a const expression.
For nested compose expressions, the inner expressions will be registed
before the outer ones. This means we can trust that the size implied
by the inner expression's type is correct, as it will have already
been validated, and can therefore avoid recursing through each nested
expression when registering the outer expression.
Add a new method to the `naga::common::wgsl::TryToWgsl` trait,
`to_wgsl_for_diagnostics`, which always returns a `String`, falling
back to the `Debug` representation of the type if necessary.
Provide a custom implementation for `Scalar` that shows abstract types
in a reasonable way.
Provide default implementations for the `write_non_wgsl_inner` and
`write_non_wgsl_scalar` methods of `naga::common::wgsl::TypeContext`.
We will be implementing this trait for various types in the WGSL front
end and the validator, and almost all of these applications will need
basically identical implementations of these methods.
Add new default methods, `type_to_string`, `type_inner_to_string`, and
`resolution_to_string` to the `naga::common::wgsl::TypeResolution`
trait, for generating WGSL source strings from these types.
In `naga::common::wgsl::types`, move the type parameter `<W: Write>`
from the `TypeContext` trait itself to the individual methods of the
trait. It is very unlikely for Naga to need to be able to implement
`TypeContext`, but only for one particular kind of output stream.
The motivation for this change is that the old parameterization makes
it awkward to provide utility methods for generating `String`s on the
trait, which we do in subsequent commits. In order to write to a
`String`, such utility methods need `Self` to implement
`TypeContext<String>`, so you can add bounds to the methods like this:
fn type_to_string(..., out: &mut W) -> ...
where Self: TypeContext<String>
{
... self.write(..., &mut string_buf)?;
}
That will compile, but if you try to actually call it, Rust gets
confused. Remember, the above is not a method on
`TypeContext<String>`, it's a method on `TypeContext<W>` that uses
`TypeContext<String>` internally. So when you write
`ctx.type_to_string(...)`, Rust needs to decide whether `ctx`
implements `TypeContext<W>` for some completely unspecified `W`, and
asks for type annotations.
You could supply type annotations, but this would be basically
supplying some never-used type that implements `core::fmt::Write`.
Instead of
ctx.type_to_string(handle)
you'd have to write
TypeContext::<String>::type_to_string(ctx, handle)
which is dumb.
(I don't *think* this explanation belongs in the code, since it's an
explanation of a design *not* used, replaced by a design that's pretty
natural --- so I'll leave it here.)
Put the `use` directives at the top of `front::wgsl::error` in the
usual order:
- identifiers defined by this crate itself
- identifiers defined by other crates
- identifiers from the standard library
This commit should cause no change in behavior.
Extend the `naga::common::wgsl::TypeContext` trait with new methods,
`write_non_wgsl_inner` and `write_non_wgsl_scalar`, which are called
when `write_type`, `write_type_inner`, or `write_scalar` are presented
with Naga IR that cannot be expressed in WGSL. Delegating these cases
lets most uses of `unreachable!` be removed.
In the WGSL backend, implement `write_non_wgsl_inner` and
`write_non_wgsl_scalar` to call `unreachable!`, preserving existing
behavior.
In `naga::common::wgsl::types`, remove `unwrap_to_wgsl` from
`try_write_type_inner` and replace its uses with calls to a new trait
method, `write_scalar`, with a default definition. This should have no
effect on externally visible behavior, but it makes subsequent commits
easier to read.
Move the guts of the `naga::common::wgsl::TypeContext` trait's
`write_type_inner` method into a new function, `try_write_type_inner`,
private to the module.
This commit is only code motion; there should be no change to
behavior. Subsequent commits will introduce a private error type, with
the new function serving as a `try` block.
In `naga::common::wgsl`, move the `ToWgsl` and `TryToWgsl` trait
definitions and impls into their own submodule, `to_wgsl`.
This change is only code motion; there should be no change in
behavior.
In `naga::common::wgsl`, move `DisplayFilterableTriggeringRule` and
diagnostics-related impls into a new sub-module, `diagonostics`.
This change is only code motion; there should be no change in
behavior.
Use `String` in variants of `naga::front::wgsl::Error`, not
`Box<str>`.
Delete test `naga::front::wgsl::error::test_error_size`. Since `Error`
is always returned boxed, its size should have no effect on `Result`
size.
Change the definition of `naga::front::wgsl::Result` to carry
a boxed `Error`, so that the size of `Error` does not affect
performance of success paths.
Introduce a new type alias, `naga::front::wgsl::Result`, that is
`core::result::Result` with the error type fixed to
`naga::front::wgsl::Error`. Use this alias where appropriate.
This commit should cause no changes in behavior or interface.
The types remain available at their original paths by `pub use ir::*`.
This may or may not be a temporary measure for migration.
The only changes to the moved code are:
* Fixing doc links.
* Moving `pub use block::Block` to the top.
The `#![allow(dead_code)]` on the module was hiding dead code in the
child modules. I changed it to be conditional on actually having no
backends enabled. (Note that with #7349, there would actually be no
warnings and we could remove the `allow(dead_code)` entirely, but I
expect that state of affairs won’t necessarily persist.)
Place the `#[track_caller]` attribute on the `check` and
`validation_error` functions in the Naga `wgsl_errors` test module, so
that panics or assertion failures will point to the actual test,
not to the code in the utility function.
This is a useful shortcut for tests and example code, allowing it to
create a noop device without needing to deal with nonexistent
fallibility and asynchrony.
* 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.
* Add `# Performance considerations` heading, to separate the facts
about how to use the method from the advice about how best to use the
method.
Back when I was learning `wgpu`, I thought that “does *not* submit the
transfer to the GPU immediately” was a claim about *ordering* relevant
to correctness, not just performance. This reorganization and
rewording should help future readers build an accurate model quicker.
* Clarify when it is best to use `write_buffer_with()` — in particular,
if you just copy from other memory, then you aren't making any
improvement over `write_buffer()`, and the advantage comes from being
able to assemble your data in-place.
* Flesh out the first `queue.submit([])` example code block,
and trim back the second one.
* Mention what techniques you might use for writing to a texture other
other than `write_texture()`.
Change the match in the `naga::common::wgsl::TypeContext` trait's
default implementation of `write_type_inner` to be exhaustive, so that
it is more likely to be kept up to date when changes are made to the
IR.
Coincidentally, add support for `TypeInner::RayQuery`.