Skip to content

Define built-in constants and add two circle constants #4473

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mehmetoguzderin wants to merge 15 commits into
base: main
Choose a base branch
from
Open

Define built-in constants and add two circle constants #4473

Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
1984cc4
Start built-in constants section
mehmetoguzderin Jan 31, 2024
364a657
Improve wording
mehmetoguzderin Jan 31, 2024
4c0fb42
Fix typo
mehmetoguzderin Jan 31, 2024
5b44bac
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Feb 1, 2024
7dfd4bb
Add code points and double precision values for circle constants
mehmetoguzderin Feb 1, 2024
e5c41c4
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Feb 4, 2024
bdfdc64
Add example
mehmetoguzderin Feb 13, 2024
b41b838
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Feb 13, 2024
61adc58
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Jun 26, 2024
1868e17
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Oct 18, 2024
fa9198b
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Jul 23, 2025
707d511
Update index.bs
mehmetoguzderin Jul 23, 2025
29c3dbb
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Jul 23, 2025
7812de9
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Jul 24, 2025
df4bf8f
Merge branch 'main' into oguz-202401-constants
mehmetoguzderin Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions wgsl/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19421,6 +19421,58 @@ Both of these scopes are larger than [=quad=].
* IDs 1 and 3 swap.
</table>

# Built-in Constants # {#builtin-constants}

<dfn noexport>Built-in constants</dfn> are [=predeclared=] values provided by
the implementation and, therefore, always available for use in a WGSL module.
All built-in constants are [=const-declarations=], and all their names are
valid [=identifiers=].

Note: The [=built-in constants=] with
[[#abstract-types|abstract numeric types]] that represent symbolic
values are subject to the same rules, including
[[#abstract-float-accuracy|abstract float accuracy]]. As such, where
applicable, expressions involving them might be evaluated at
[=shader module creation|shader-creation time=] and
result in better approximations than operating on target types, reducing
the need for specialized constants such as `PI_2` for scales and offsets.
See the example usage for a demonstration of the accuracy improvement.

<table class='data builtin constants'>
<caption>
<dfn noexport>Built-in mathematical constants</dfn>
</caption>
<thead>
<tr><th>Names<th>Type<th>Description
</thead>
<tr><td>`PI`<br>
`π` (Code point: `U+03C0`)
<td>[=abstractfloat|AbstractFloat=]
<td>Approximates the ratio of the circumference of a circle to its diameter,
known as π, pi, or Archimedes' constant.<br>
Double precision: `3.14159265358979323846264338327950288`
<tr><td>`TAU`<br>
`τ` (Code point: `U+03C4`)
<td>[=abstractfloat|AbstractFloat=]
<td>Approximates the perimeter of a unit circle, known as τ, tau, 2π,
or a turn.<br>
Double precision: `6.28318530717958647692528676655900577`
</table>

<div class='example wgsl function-scope' heading='Using mathematical constants'>
<xmp highlight=wgsl>
// Coefficient calculation for an integral approximation, where accuracy
// is critical for the numerical method. With WGSL constants, evaluation
// resolves to a more accurate value than defining these values as custom
// f32 variables without needing specializations such as M_PI_2.
Copy link
Copy Markdown
Contributor

@ben-clayton ben-clayton Feb 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't the argument for not including M_PI_2 (PI/2) a good argument for omitting TAU? It's just one more character to write PI*2.

Copy link
Copy Markdown
Member Author

@mehmetoguzderin mehmetoguzderin Feb 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Certainly an argument in support of such thinking, although I think the consensus was to add TAU for widespread recognition, but if the group decides otherwise today, I can change it. Though even when precision is not an issue, similar constant collections seem to be including TAU these days, strengthening the case for inclusion.

const coefficient_i = (
2.0 * TAU - (-PI / 4.0) // Interval from -π/4 to 2τ
) / 1024.0; // Number of steps
// Absolute error with WGSL constants: 3.59085e-19
// Absolute error with f32 user constants: 6.53877e-10
</xmp>
</div>

# Grammar for Recursive Descent Parsing # {#grammar-recursive-descent}

This section is non-normative.
Expand Down