Enum naga::proc::index::BoundsCheckPolicy
source · pub enum BoundsCheckPolicy {
Restrict,
ReadZeroSkipWrite,
Unchecked,
}
Expand description
How should code generated by Naga do bounds checks?
When a vector, matrix, or array index is out of bounds—either negative, or greater than or equal to the number of elements in the type—WGSL requires that some other index of the implementation’s choice that is in bounds is used instead. (There are no types with zero elements.)
Similarly, when out-of-bounds coordinates, array indices, or sample indices
are presented to the WGSL textureLoad
and textureStore
operations, the
operation is redirected to do something safe.
Different users of Naga will prefer different defaults:
-
When used as part of a WebGPU implementation, the WGSL specification requires the
Restrict
behavior for array, vector, and matrix accesses, and either theRestrict
orReadZeroSkipWrite
behaviors for texture accesses. -
When used by the
wgpu
crate for native development,wgpu
selectsReadZeroSkipWrite
as its default. -
Naga’s own default is
Unchecked
, so that shader translations are as faithful to the original as possible.
Sometimes the underlying hardware and drivers can perform bounds checks
themselves, in a way that performs better than the checks Naga would inject.
If you’re using native checks like this, then having Naga inject its own
checks as well would be redundant, and the Unchecked
policy is
appropriate.
Variants§
Restrict
Replace out-of-bounds indexes with some arbitrary in-bounds index.
(This does not necessarily mean clamping. For example, interpreting the index as unsigned and taking the minimum with the largest valid index would also be a valid implementation. That would map negative indices to the last element, not the first.)
ReadZeroSkipWrite
Out-of-bounds reads return zero, and writes have no effect.
When applied to a chain of accesses, like a[i][j].b[k]
, all index
expressions are evaluated, regardless of whether prior or later index
expressions were in bounds. But all the accesses per se are skipped
if any index is out of bounds.
Unchecked
Naga adds no checks to indexing operations. Generate the fastest code possible. This is the default for Naga, as a translator, but consumers should consider defaulting to a safer behavior.
Trait Implementations§
source§impl Clone for BoundsCheckPolicy
impl Clone for BoundsCheckPolicy
source§fn clone(&self) -> BoundsCheckPolicy
fn clone(&self) -> BoundsCheckPolicy
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for BoundsCheckPolicy
impl Debug for BoundsCheckPolicy
source§impl Default for BoundsCheckPolicy
impl Default for BoundsCheckPolicy
The default BoundsCheckPolicy
is Unchecked
.
source§impl Hash for BoundsCheckPolicy
impl Hash for BoundsCheckPolicy
source§impl PartialEq for BoundsCheckPolicy
impl PartialEq for BoundsCheckPolicy
source§fn eq(&self, other: &BoundsCheckPolicy) -> bool
fn eq(&self, other: &BoundsCheckPolicy) -> bool
self
and other
values to be equal, and is used
by ==
.impl Copy for BoundsCheckPolicy
impl Eq for BoundsCheckPolicy
impl StructuralPartialEq for BoundsCheckPolicy
Auto Trait Implementations§
impl Freeze for BoundsCheckPolicy
impl RefUnwindSafe for BoundsCheckPolicy
impl Send for BoundsCheckPolicy
impl Sync for BoundsCheckPolicy
impl Unpin for BoundsCheckPolicy
impl UnwindSafe for BoundsCheckPolicy
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.