Built-in Kütüphanesi

---

§17 Built-in Functions

Belirli fonksiyonlar predeclared (önceden bildirilmiş) olarak implementasyon tarafından sağlanır ve bir WGSL modülünde her zaman kullanılabilir. Bunlara built-in functions (yerleşik fonksiyonlar) denir.

Bir built-in fonksiyon, aynı ada sahip bir fonksiyon ailesidir; ancak parametre sayısı, sırası ve tipleri ile birbirinden ayrılır. Bu farklı varyasyonların her biri bir overload'dur.

Her overload şu bilgilerle tanımlanır:

• Type parameterizations (tip parametreleri) — varsa
• Fonksiyon imzası — ad, parametreler ve dönüş tipi
• Davranış — overload'un çalışma mantığı

Built-in fonksiyon çağrılırken, tüm argümanlar fonksiyon değerlendirmesi başlamadan önce değerlendirilir (bkz. §11.2).

---

17.1 Constructor Built-in Functions

Value constructor built-in fonksiyonları, belirli bir tipin değerini açıkça oluşturur. WGSL, tüm predeclared tipler ve tüm constructible structure tipleri için value constructor sağlar.

Constructor fonksiyonun adı, tip adıyla (veya type alias ile) aynı yazılır.

WGSL iki tür value constructor sağlar:

1. Zero value constructors — sıfır değer oluşturma
2. Value constructors — değer oluşturma ve dönüştürme

17.1.1 Zero Value Built-in Functions

Her concrete, constructible T tipinin benzersiz bir zero value (sıfır değeri) vardır. WGSL'de T() şeklinde yazılır.

Overload:

@const @must_use fn T() -> T

• Parameterization: T, concrete constructible tip
• Açıklama: T tipinin sıfır değerini oluşturur.

vec2<f32>()                 // İki f32 bileşenli sıfır vektör
vec2<f32>(0.0, 0.0)         // Aynı değer, açıkça yazılmış

vec3<i32>()                 // Üç i32 bileşenli sıfır vektör
vec3<i32>(0, 0, 0)          // Aynı değer, açıkça yazılmış

array<bool, 2>()            // İki boolean'lık sıfır dizi
array<bool, 2>(false, false) // Aynı değer, açıkça yazılmış

struct Student {
  grade: i32,
  GPA: f32,
  attendance: array<bool, 4>
}

fn func() {
  var s: Student;
  s = Student();                        // Student sıfır değeri
  s = Student(0, 0.0, array<bool, 4>(false, false, false, false)); // Açık form
  s = Student(i32(), f32(), array<bool, 4>());  // Sıfır üyelerle
}

17.1.2 Value Constructor Built-in Functions

Value constructor built-in fonksiyonları, constructible bir değeri şu yollarla oluşturur:

1. Kopyalama — aynı tipte mevcut bir değerin kopyası (identity)
2. Bileşenlerden oluşturma — açık bileşen listesinden composite değer
3. Dönüştürme — başka bir değer tipinden dönüşüm

Vektör ve matris formları, bileşen tipini belirtmeden boyutları belirten overload'lar sağlar — bileşen tipi argümanlardan çıkarılır.

array

bool

f16

f32

i32

u32

mat2x2 · mat2x3 · mat2x4 · mat3x2 · mat3x3 · mat3x4 · mat4x2 · mat4x3 · mat4x4

Her matCxR matris tipi için üç overload grubu vardır:

• T: AbstractFloat, f16 veya f32
• Column-major sıralama: Elemanlar sütun sütun doldurulur

// mat2x2 sütun vektörlerinden
let m = mat2x2<f32>(
  vec2<f32>(1.0, 2.0),   // 1. sütun
  vec2<f32>(3.0, 4.0)    // 2. sütun
);

// mat2x2 elemanlardan (aynı sonuç)
let m2 = mat2x2<f32>(1.0, 2.0, 3.0, 4.0);

Structures

Constructible structure tipi S, üyelerinin sırasıyla constructor argümanları olarak kullanıldığı bir constructor sağlar:

struct Particle {
  pos: vec3<f32>,
  vel: vec3<f32>,
  mass: f32
}

let p = Particle(vec3<f32>(0.0), vec3<f32>(1.0, 0.0, 0.0), 1.5);

vec2 · vec3 · vec4

Her vecN vektör tipi için çeşitli overload'lar:

let v1 = vec3<f32>(1.0, 2.0, 3.0);   // Bileşenlerden
let v2 = vec4<f32>(1.0);              // Splat: (1.0, 1.0, 1.0, 1.0)
let v3 = vec4<f32>(v1, 4.0);          // vec3 + skaler
let v4 = vec4<f32>(v1.xy, v1.yz);     // İki vec2'den

---

17.2 Bit Reinterpretation Built-in Functions

17.2.1 bitcast

bitcast<T>(e), bir değerin bit temsilini tip dönüşümü yapmadan yeniden yorumlar.

Geçerli bitcast kombinasyonları (32-bit tipler arası):

Vektör tipleri için component-wise: bitcast<vec2<f32>>(vec2<u32>(…)) gibi.

Özel durumlar:

• bitcast<f16>(vec2<f16>(…)) — iki f16'yı tek u32 gibi paketleme
• Kaynak veya hedef f32 ise ve kaynak NaN veya ∞ bit deseni içeriyorsa, sonuç indeterminate value olabilir

// Float'ı unsigned integer olarak yorumla (bit manipülasyonu için)
let float_val = 1.0f;
let bits = bitcast<u32>(float_val);  // IEEE-754 bit deseni: 0x3F800000

// Integer'ı float olarak geri yorumla
let restored = bitcast<f32>(bits);   // 1.0f

// vec2<f16> ↔ u32 paketleme
let packed = bitcast<u32>(vec2<f16>(1.0h, 2.0h));
let unpacked = bitcast<vec2<f16>>(packed);

---

17.3 Logical Built-in Functions

17.3.1 all

Bir boolean vektörün tüm bileşenlerinin true olup olmadığını test eder.

let v = vec3<bool>(true, true, false);
let result = all(v);     // false (üçüncü bileşen false)

let v2 = vec2<bool>(true, true);
let result2 = all(v2);   // true

17.3.2 any

Bir boolean vektörün en az bir bileşeninin true olup olmadığını test eder.

let v = vec3<bool>(false, false, true);
let result = any(v);     // true

let v2 = vec2<bool>(false, false);
let result2 = any(v2);   // false

17.3.3 select

Koşula bağlı olarak iki değerden birini seçer (component-wise ternary).

let a = 10;
let b = 20;
let result = select(a, b, true);     // 20 (cond true → t seçilir)

// Component-wise seçim
let v1 = vec3<f32>(1.0, 2.0, 3.0);
let v2 = vec3<f32>(4.0, 5.0, 6.0);
let mask = vec3<bool>(true, false, true);
let result2 = select(v1, v2, mask);  // vec3(4.0, 2.0, 6.0)

---

17.4 Array Built-in Functions

17.4.1 arrayLength

Runtime-sized dizinin eleman sayısını döndürür.

struct Data {
  count: u32,
  values: array<f32>    // Runtime-sized dizi
}
@group(0) @binding(0) var<storage> data: Data;

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let len = arrayLength(&data.values);
  if gid.x < len {
    // values[gid.x] ile güvenle çalış
  }
}

---

17.5 Numeric Built-in Functions

Numerik built-in fonksiyonlar WGSL'in en büyük kategorisidir — 63 fonksiyon içerir. Aşağıda alt kategorilere ayrılmıştır.

Trigonometri & Açı

• T: f32, f16, AbstractFloat veya bunların vecN varyantları
• Tüm trig fonksiyonlar component-wise çalışır

Üstel & Logaritmik

Yuvarlama & Kırpma

Aritmetik & İşaret

// modf örneği
let result = modf(3.75);
// result.fract = 0.75, result.whole = 3.0

// frexp örneği
let result2 = frexp(6.5);
// result2.fract ≈ 0.8125, result2.exp = 3 (6.5 = 0.8125 × 2³)

// mix (lerp) örneği
let color = mix(vec3(1.0, 0.0, 0.0), vec3(0.0, 0.0, 1.0), 0.5);
// color = vec3(0.5, 0.0, 0.5) — kırmızı ile mavi arası

Vektör & Matris

// Yüzey normali ile ışık yönü arasındaki açı (diffuse lighting)
let N = normalize(surface_normal);
let L = normalize(light_dir);
let NdotL = max(dot(N, L), 0.0);

// Yansıma vektörü (specular lighting)
let R = reflect(-L, N);

Bit Manipülasyonu

• T: i32, u32 veya bunların vecN varyantları

let x: u32 = 0x00FF0000u;
let leading = countLeadingZeros(x);    // 8
let ones = countOneBits(x);            // 8
let trailing = countTrailingZeros(x);  // 16

// Bit alanı çıkarma
let val: u32 = 0xABCD1234u;
let bits = extractBits(val, 8u, 8u);   // 8. bitten başlayarak 8 bit çıkar: 0x12

// firstLeadingBit — log2 yaklaşımı için kullanışlı
let msb = firstLeadingBit(1024u);      // 10 (2^10 = 1024)

17.6 Derivative Built-in Functions

Derivative fonksiyonları uniform control flow içinde çağrılmalıdır; aksi halde derivative_uniformity diagnostic'i tetiklenir.

• Parameterization: T, f32 veya vecN<f32>
• Overload: @must_use fn dpdx(e: T) -> T (ve diğerleri aynı kalıpta)
• Accuracy: Infinite ULP (sonlu hata sınırı yoktur)

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
  // UV koordinatlarının değişim hızını hesapla
  let ddx = dpdx(uv);
  let ddy = dpdy(uv);

  // Mipmap seviyesi seçimi için fwidth kullanımı
  let fw = fwidth(uv);

  return vec4<f32>(fw, 0.0, 1.0);
}

---

17.7 Texture Built-in Functions

Texture fonksiyonları, GPU texture birimlerini sorgulamak, örneklemek ve yazmak için kullanılır.

Sorgulama Fonksiyonları

@group(0) @binding(0) var t: texture_2d<f32>;

@compute @workgroup_size(1)
fn main() {
  let dims = textureDimensions(t);       // vec2<u32>(width, height)
  let dims_mip = textureDimensions(t, 1); // Mip seviye 1'in boyutları
  let levels = textureNumLevels(t);       // Mipmap seviye sayısı
}

Yükleme Fonksiyonları

@group(0) @binding(0) var t: texture_2d<f32>;

@fragment
fn main(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {
  let texel = textureLoad(t, vec2<i32>(pos.xy), 0);  // (x, y, mip_level)
  return texel;
}

Örnekleme Fonksiyonları

@group(0) @binding(0) var t: texture_2d<f32>;
@group(0) @binding(1) var s: sampler;

@fragment
fn main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
  // Implicit LOD (derivative hesaplar — uniform control flow gerektirir)
  let color = textureSample(t, s, uv);

  // Explicit LOD (non-uniform dallanmada güvenle kullanılabilir)
  let color2 = textureSampleLevel(t, s, uv, 0.0);

  // Shadow mapping
  // let shadow = textureSampleCompareLevel(shadow_tex, shadow_sampler, uv, depth, 0);

  return color;
}

Yazma Fonksiyonları

@group(0) @binding(0) var output: texture_storage_2d<rgba8unorm, write>;

@compute @workgroup_size(8, 8)
fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  let color = vec4<f32>(f32(gid.x) / 256.0, f32(gid.y) / 256.0, 0.5, 1.0);
  textureStore(output, vec2<i32>(gid.xy), color);
}

Gather Fonksiyonları

textureGather, dört komşu texel'den belirtilen bileşeni (0=R, 1=G, 2=B, 3=A) vec4 olarak döndürür — shadow mapping ve post-processing filtrelerinde verimlidir.

---

17.8 Atomic Built-in Functions

Atomic fonksiyonlar, storage veya workgroup adres uzayındaki atomic<T> tiplerinde (T: i32 veya u32) bölünmez (thread-safe) okuma-yazma işlemleri gerçekleştirir.

Temel Operasyonlar

Read-Modify-Write (Oku-Değiştir-Yaz) Operasyonları

Tüm RMW fonksiyonları önceki değeri döndürür:

Exchange Operasyonları

@group(0) @binding(0) var<storage, read_write> counter: atomic<u32>;
var<workgroup> local_sum: atomic<u32>;

@compute @workgroup_size(256)
fn main(@builtin(local_invocation_index) lid: u32) {
  // Workgroup-local atomik toplama
  atomicAdd(&local_sum, 1u);

  workgroupBarrier();

  // Tek bir thread global sayacı günceller
  if lid == 0u {
    let local_count = atomicLoad(&local_sum);
    atomicAdd(&counter, local_count);
  }
}

// Compare-and-swap ile lock-free güncelleme
fn try_update(p: ptr<storage, atomic<u32>, read_write>, expected: u32, desired: u32) -> bool {
  let result = atomicCompareExchangeWeak(p, expected, desired);
  return result.exchanged;
}

---

17.9 Data Packing Built-in Functions

Packing fonksiyonları, birden fazla küçük değeri tek bir u32'ye sıkıştırır.

// Normal vektörü tek u32'ye sıkıştır (vertex veri optimizasyonu)
let normal = vec4<f32>(0.5, 0.5, 0.707, 0.0);
let packed = pack4x8snorm(normal);

// İki float'u tek u32'ye paketle
let uv = vec2<f32>(0.75, 0.25);
let packed_uv = pack2x16unorm(uv);

---

17.10 Data Unpacking Built-in Functions

Unpacking fonksiyonları, paketlenmiş u32 değerlerini geri çözer.

// Pack → unpack roundtrip
let original = vec4<f32>(0.1, 0.5, 0.9, 1.0);
let packed = pack4x8unorm(original);
let recovered = unpack4x8unorm(packed);
// recovered ≈ original (kuantizasyon hatası ile)

---

17.11 Synchronization Built-in Functions

Senkronizasyon fonksiyonları, bellek tutarlılığı ve yürütme sıralaması sağlar.

var<workgroup> shared_data: array<f32, 256>;

@compute @workgroup_size(256)
fn main(@builtin(local_invocation_index) lid: u32) {
  // Her thread kendi verisini yazar
  shared_data[lid] = compute_value(lid);

  // Tüm thread'lerin yazmasını bekle (kontrol + bellek bariyeri)
  workgroupBarrier();

  // Artık komşu thread'lerin yazdığı veri güvenle okunabilir
  let neighbor = shared_data[(lid + 1u) % 256u];
}

// workgroupUniformLoad: koşullu dallanma güvenli hale gelir
var<workgroup> flag: u32;

@compute @workgroup_size(64)
fn main(@builtin(local_invocation_index) lid: u32) {
  if lid == 0u {
    flag = check_condition();
  }
  // flag'ı tüm invocation'lar için uniform olarak yükle
  let uniform_flag = workgroupUniformLoad(&flag);
  if uniform_flag != 0u {
    // Tüm invocation'lar aynı dalı izler — uniform control flow
    workgroupBarrier();
  }
}

---

17.12 Subgroup Built-in Functions

Subgroup fonksiyonları, aynı subgroup'taki invocation'lar arasında SIMT (Single Instruction Multiple Thread) stilinde verimli iletişim ve hesaplama sağlar. subgroups uzantısı gerektirir.

Reduction Operasyonları

Voting & Ballot

İletişim

enable subgroups;

@compute @workgroup_size(256)
fn main(@builtin(subgroup_invocation_id) sid: u32,
        @builtin(subgroup_size) sg_size: u32) {
  let my_value = compute_something(sid);

  // Subgroup-wide toplam (register düzeyinde, paylaşımlı bellek gerektirmez)
  let total = subgroupAdd(my_value);

  // Prefix sum (parallel scan)
  let prefix = subgroupExclusiveAdd(my_value);

  // Butterfly reduction için XOR shuffle
  let partner_val = subgroupShuffleXor(my_value, 1u);
}

---

17.13 Quad Built-in Functions

Quad fonksiyonları, bir quad (2×2 invocation grubu) içinde veri alışverişi sağlar. subgroups uzantısı gerektirir.

Quad düzeni:

┌───┬───┐
│ 0 │ 1 │   quadSwapX: 0↔1, 2↔3
├───┼───┤   quadSwapY: 0↔2, 1↔3
│ 2 │ 3 │   quadSwapDiagonal: 0↔3, 1↔2
└───┴───┘

enable subgroups;

@fragment
fn main(@location(0) value: f32) -> @location(0) vec4<f32> {
  // Komşu fragment'ın değerini al (X ekseninde)
  let neighbor_x = quadSwapX(value);

  // Manuel derivative hesaplaması
  let dfdx = neighbor_x - value;

  return vec4<f32>(dfdx, 0.0, 0.0, 1.0);
}

---

§18 Grammar for Recursive Descent Parsing

Bu bölüm normatif değildir (non-normative). WGSL grammar'ı LALR(1) parser'a uygun formda belirtilmiştir; ancak bir implementasyon recursive-descent parser kullanabilir.

Normatif grammar doğrudan recursive-descent parser'da kullanılamaz çünkü bazı kuralları sol-özyinelemeli (left-recursive) dir. Aşağıdaki dönüşümler uygulanmıştır:

1. Doğrudan ve dolaylı sol-özyineleme ortadan kaldırılmıştır
2. Boş üretimler (epsilon kuralları) engellenmiştir
3. Ortak ön ekler kardeş üretimler arasında birleştirilmiştir

Temel Grammar Kuralları

translation_unit:
  | global_directive* global_decl* global_assert*

global_directive:
  | 'diagnostic' '(' ident_pattern_token ',' diagnostic_rule_name ','? ')' ';'
  | 'enable' ident_pattern_token (',' ident_pattern_token)* ','? ';'
  | 'requires' ident_pattern_token (',' ident_pattern_token)* ','? ';'

global_decl:
  | attribute* 'fn' ident '(' param_list? ')' ('->' attribute* type_specifier)? compound_statement
  | attribute* 'var' template_args? optionally_typed_ident ('=' expression)? ';'
  | global_value_decl ';'
  | 'alias' ident '=' type_specifier ';'
  | 'struct' ident '{' struct_member (',' struct_member)* ','? '}'

İfade Grammar'ı

expression:
  | unary_expression bitwise_expression.post.unary_expression
  | unary_expression relational_expression.post.unary_expression
  | unary_expression relational_expression.post.unary_expression '&&' ...
  | unary_expression relational_expression.post.unary_expression '||' ...

unary_expression:
  | primary_expression component_or_swizzle_specifier?
  | '!' unary_expression
  | '&' unary_expression
  | '*' unary_expression
  | '-' unary_expression
  | '~' unary_expression

primary_expression:
  | ident template_elaborated_ident.post.ident
  | ident template_elaborated_ident.post.ident argument_expression_list
  | literal
  | '(' expression ')'

Statement Grammar'ı

statement:
  | attribute* 'for' '(' for_init? ';' expression? ';' for_update? ')' compound_statement
  | attribute* 'if' expression compound_statement ('else' 'if' expression compound_statement)* ('else' compound_statement)?
  | attribute* 'loop' attribute* '{' statement* ('continuing' attribute* '{' statement* ('break' 'if' expression ';')? '}')? '}'
  | attribute* 'switch' expression attribute* '{' switch_clause+ '}'
  | attribute* 'while' expression compound_statement
  | attribute* '{' statement* '}'
  | 'break' ';'
  | 'const_assert' expression ';'
  | 'continue' ';'
  | 'discard' ';'
  | 'return' expression? ';'
  | variable_or_value_statement ';'
  | variable_updating_statement ';'
  | ident func_call_statement.post.ident ';'

Operatör Öncelik Kuralları

shift_expression.post.unary_expression:
  | (multiplicative_operator unary_expression)* (additive_operator unary_expression (multiplicative_operator unary_expression)*)*
  | shift_left unary_expression
  | shift_right unary_expression

multiplicative_operator: | '%' | '*' | '/'
additive_operator: | '+' | '-'

compound_assignment_operator:
  | shift_left_assign | shift_right_assign
  | '%=' | '&=' | '*=' | '+=' | '-=' | '/=' | '^=' | '|='

Literal Grammar'ı

literal: | bool_literal | float_literal | int_literal

bool_literal: | 'false' | 'true'

int_literal: | decimal_int_literal | hex_int_literal
decimal_int_literal: | /0[iu]?/ | /[1-9][0-9]*[iu]?/

float_literal: | decimal_float_literal | hex_float_literal
decimal_float_literal:
  | /0[fh]/
  | /[0-9]*\.[0-9]+([eE][+-]?[0-9]+)?[fh]?/
  | /[0-9]+[eE][+-]?[0-9]+[fh]?/
  | /[0-9]+\.[0-9]*([eE][+-]?[0-9]+)?[fh]?/
  | /[1-9][0-9]*[fh]/

---

---