SHUFFLE(3clc)

hey bestie 💖 you just opened SHUFFLE, SHUFFLE2(3clc) from the OpenCL Manual and honestly? iconic. let's get into it 🫶

---

💅 NAME 💅

so shuffle — it constructs a permutation of elements from one (or two) input vectors. that's the whole gig. no cap ✨

and here's the exact tea, the signatures verbatim:

gentypen shuffle(gentypem x, ugentypen mask);

gentypen shuffle2(gentypem x, gentypem y, ugentypen mask);

---

🌸 DESCRIPTION 🌸

okay so listen 🎀 the shuffle and shuffle2 built-in functions construct a permutation of elements from one or two input vectors respectively that are of the same type, and they return a vector with the same element type as the input and a length that is the same as the shuffle mask. the size of each element in the mask must match the size of each element in the result. like, that's non-negotiable bestie 💀

for shuffle, only the ilogb(3clc)(2m-1) least significant bits of each mask element are considered. for shuffle2, only the ilogb(3clc)(2m-1)+1 least significant bits of each mask element are considered. other bits in the mask shall be ignored. so extra bits are just... there. chilling. being ignored. 🙈

the elements of the input vectors are numbered from left to right across one or both of the vectors. for this purpose, the number of elements in a vector is given by vec_step(3clc)(gentypem). the shuffle mask operand specifies, for each element of the result vector, which element of the one or two input vectors the result element gets. it's literally a little assignment chart for your vector elements 💖

we use the generic type name gentypen (or gentypem) to indicate the built-in data types char{2|4|8|16}, uchar{2|4|8|16}, short{2|4|8|16}, ushort{2|4|8|16}, int{2|4|8|16}, uint{2|4|8|16}, long{2|4|8|16}, ulong{2|4|8|16}, or float{2|4|8|16} as the type for the arguments unless otherwise stated. we use the generic name ugentypen to indicate the built-in unsigned integer data types. if the double is supported, then gentypen (or gentypem) also indicate the built-in data types double{2|4|8|16}. 👑

the generic type name gentypen (or gentypem) may indicate the data type half{2|4|8|16} if the cl_khr_fp16(3clc) extension is supported. shoutout to the fp16 girlies 🧚

🍓 Example 🍓

the valid ones, exactly as written:

uint4 mask = (uint4)(3, 2, 1, 0);
float4 a; float4 r = shuffle(a, mask);
// r.s0123 = a.wzyx

uint8 mask = (uint8)(0, 1, 2, 3, 4, 5,
6, 7);

float4 a, b; float8 r = shuffle2(a, b,
mask); // r.s0123 = a.xyzw // r.s4567 =
b.xyzw

uint4 mask; float8 a; float4 b; b =
shuffle(a, mask);

and now the part we don't do 😭 — examples that are not valid are:

uint8 mask; short16 a; short8 b; b =
shuffle(a, mask);

do not try this one at home bestie, it is NOT valid, the mask element size and the result element size do not match, periodt. 💅

---

📜 SPECIFICATION 📜

OpenCL Specification[1] — she's cited, she's official 💜

---

🦋 SEE ALSO 🦋

• miscVectorFunctions(3clc)

---

👑 AUTHORS 👑

The Khronos Group ✨

---

🌈 COPYRIGHT 🌈

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the following conditions: the above copyright notice and this permission notice shall be included in all copies or substantial portions of the Materials. (yes bestie, keep the notice, it's the rules 🫶)

---

🎀 NOTES 🎀

1. OpenCL Specification page 282, section 6.12.12 Miscellaneous Vector Functions

---

and that's the whole page, bestie — go forth and permute those vector elements responsibly 💖✨

this was SHUFFLE, SHUFFLE2(3clc) from The Khronos Group, dated 01/14/2021. mwah, slay, bye 🫶💅