ATOMICCOMPSWAP(3G)

💅 ATOMICCOMPSWAP — the 3G manual page, bestie edition ✨

okay so real talk, this is atomicCompSwap from the 3G manual section (the header literally has a [FIXME: manual] in it, iconic of the Khronos group honestly 🫶). It's giving "tiny function, huge responsibility". Let's go.

---

🌸 NAME 🌸

atomicCompSwap — perform an atomic compare-exchange operation to a variable

---

✨ DECLARATION ✨

no cap, there are literally two of them and you have to pick the one that matches your type:

int atomicCompSwap(inout int mem, uint compare, uint data);

uint atomicCompSwap(inout uint mem, uint compare, uint data);

---

🎀 PARAMETERS 🎀

• mem — the variable you're using as the target of the operation. like, the thing getting poked. 👈
• data — the data that's gonna be compared and potentially exchanged with mem. it's the maybe-girlfriend of this whole situation.

---

💖 DESCRIPTION 💖

okay so here's the tea ☕. atomicCompSwap performs an atomic comparison of compare with the contents of mem. and then:

• if the content of mem is equal to compare → the content of data gets written into mem. slay, we swapped 💅
• otherwise → the content of mem is unmodified. it said "not today". 🙈

but here's the part that actually matters: the function returns the original content of mem regardless of the outcome of the comparison. so you always get the old value back, whether the swap happened or not. that's the whole point, iykyk.

and the safety guarantee, which is the actual main character energy here:

The contents of the memory being updated by the atomic operation are guaranteed not to be modified by any other assignment or atomic memory function in any shader invocation between the time the original value is read and the time the new value is written. 🔥

like, nobody else can sneak in and touch it mid-operation. periodt.

now, the vibe check that trips people up: atomic memory functions are supported only for a limited set of variables. if you pass something to the mem argument of an atomic memory function that does not correspond to a buffer or shared variable, a shader will fail to compile. not a warning, bestie. a fail. 💀

the good news? it is acceptable to pass an element of an array or a single component of a vector to the mem argument of an atomic memory function — as long as the underlying array or vector is a buffer or shared variable. so like, you can absolutely reach into an array or pick one component of a vector, you just can't do it to some random local. got it? 🫶

---

🌈 VERSION SUPPORT 🌈

here's the rundown of which OpenGL Shading Language versions said yes to atomicCompSwap. she was late to the party but she ATE when she arrived 👑

• 1.10 — -
• 1.20 — -
• 1.30 — -
• 1.40 — -
• 1.50 — -
• 3.30 — -
• 4.00 — -
• 4.10 — -
• 4.20 — -
• 4.30 — ✔
• 4.40 — ✔
• 4.50 — ✔

so yeah, 4.30 was her debut. everything before that? not invited. ✨

---

🦋 SEE ALSO 🦋

the whole atomic friend group, go say hi:

• atomicAdd()
• atomicAnd()
• atomicOr()
• atomicXor()
• atomicMin()
• atomicMax()
• atomicExchange()

---

👑 COPYRIGHT 👑

Copyright © 2011-2014 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

Copyright © 2012-2014 Khronos Group

---

and that's the whole page, bestie 💜 sourced from [FIXME: source] and dated 01/03/2018, filed under ATOMICCOMPSWAP(3G). go forth and swap atomically. 🧚‍♀️