SAMPLER_T(3clc)

💖 SAMPLER_T 💖

okay bestie, welcome to sampler_t from the OpenCL manual (3clc), and lemme tell you, this one is lowkey the vibe-controller for your images 👑

---

✨ NAME ✨

sampler_t — a type that controls how elements of an image object get read by read_image{f|i|ui}. it's giving "the rules of the reading situation" fr fr 🎀

const sampler_t <sampler name> = <value>
constant sampler_t <sampler name> = <value>
__constant sampler_t <sampler name> = <value>

---

🌸 DESCRIPTION 🌸

so the image read functions take a sampler argument, right? and that sampler can show up in three different ways, pick your fighter:

• passed as an argument to the kernel using clSetKernelArg(3clc) 🫶
• declared in the outermost scope of kernel functions ✨
• a constant variable of type sampler_t declared in the program source 💅

Sampler variables in a program are declared to be of type sampler_t. and here's the tea: a variable of sampler_t type declared in the program source must be initialized with a 32-bit unsigned integer constant, which gets interpreted as a bit-field specifying these properties:

• Addressing Mode
• Filter Mode
• Normalized Coordinates

these properties control how elements of an image object are read by imageFunctions(3clc). no cap, that's the whole job 📸

Samplers can also be declared as global constants in the program source using the syntax shown at the top of this page (you saw it, the const sampler_t moment 👀).

and now, the sampler fields, described in the table below (rip the table, we're doing it in cute little bullets now, same facts tho 🦋):

🎀 Sampler State — <normalized coords>

Specifies whether the x, y and z coordinates are passed in as normalized or unnormalized values. This must be a literal value and can be one of the following predefined enums:

• CLK_NORMALIZED_COORDS_TRUE
• CLK_NORMALIZED_COORDS_FALSE

⚠️ the samplers used with an image in multiple calls to imageFunctions(3clc){f|i|ui} declared in a kernel must use the same value for <normalized coords>. like, consistency is the moment, bestie 💀

---

🌈 Sampler State — <addressing mode>

Specifies the image addressing-mode, i.e. how out-of-range image coordinates are handled. This must be a literal value and can be one of the following predefined enums:

• CLK_ADDRESS_MIRRORED_REPEAT — Flip the image coordinate at every integer junction. This addressing mode can only be used with normalized coordinates. If normalized coordinates are not used, this addressing mode may generate image coordinates that are undefined. 🙈
• CLK_ADDRESS_REPEAT — out-of-range image coordinates are wrapped to the valid range. This address mode can only be used with normalized coordinates. If normalized coordinates are not used, this addressing mode may generate image coordinates that are undefined. 😭
• CLK_ADDRESS_CLAMP_TO_EDGE — out-of-range image coordinates are clamped to the extent. 🫶
• CLK_ADDRESS_CLAMP — out-of-range image coordinates will return a border color. This is similar to the GL_ADDRESS_CLAMP_TO_BORDER addressing mode. 🎨
• CLK_ADDRESS_NONE — for this addressing mode the programmer guarantees that the image coordinates used to sample elements of the image refer to a location inside the image; otherwise the results are undefined. periodt. 💅

📌 for 1D and 2D image arrays, the addressing mode applies only to the x and (x, y) coordinates. The addressing mode for the coordinate which specifies the array index is always CLK_ADDRESS_CLAMP_TO_EDGE. iconic behaviour honestly 👑

---

⭐ Sampler State — <filter mode>

Specifies the filtering mode to use. This must be a literal value and can be one of the following predefined enums:

• CLK_FILTER_NEAREST
• CLK_FILTER_LINEAR

refer to section 8.2 for a description of these filter modes 📖✨

📝 NOTES 📝

okay bestie, listen up, because this part is lowkey important ✨

First things first: samplers that you declare with the constant qualifier? They do not count towards the maximum number of arguments pointing to the constant address space, and they also don't count towards the maximum size of the constant address space allowed per device. That's CL_DEVICE_MAX_CONSTANT_ARGS and CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE, as described in table 4.3. So they're basically free real estate 💅

And the max number of samplers you can declare in a kernel? You can query that with the CL_DEVICE_MAX_SAMPLERS token in clGetDeviceInfo(3clc). Go check it, don't guess 🫶

---

Now, the border color situation, and this is giving very specific:

If the <addressing mode> in the sampler is CLK_ADDRESS_CLAMP, then out-of-range image coordinates return the border color. That border color depends on the image channel order, and it can be one of these values:

• If the image channel order is CL_A, CL_INTENSITY, CL_Rx, CL_RA, CL_RGx, CL_RGBx, CL_ARGB, CL_BGRA, or CL_RGBA, the border color is (0.0f, 0.0f, 0.0f, 0.0f). 💀 all zeroes, nothing to see here.
• If the image channel order is CL_R, CL_RG, CL_RGB, or CL_LUMINANCE, the border color is (0.0f, 0.0f, 0.0f, 1.0f). okay that last one is a 1.0f, we love a little finale 🌈

⚠️ heads up, this next bit is the sneaky part: a kernel that uses a sampler with the CL_ADDRESS_CLAMP addressing mode with multiple images may result in additional samplers being used internally by an implementation. So if the same sampler is used with multiple images called via imageFunctions(3clc), then it's possible that an implementation may need to allocate an additional sampler to handle the different border color values that may be needed depending on the image formats being used. And here's the thing — these implementation-allocated samplers will count against the maximum sampler values supported by the device, the ones given by CL_DEVICE_MAX_SAMPLERS. Enqueuing a kernel that requires more samplers than the implementation can support will result in a CL_OUT_OF_RESOURCES error being returned. so yeah. budget your samplers, bestie 😭

🌟 Example 🌟

okay here's the moment, the little code snippet, she's cute:

const sampler_t samplerA =
CLK_NORMALIZED_COORDS_TRUE |
CLK_ADDRESS_REPEAT         |
CLK_FILTER_NEAREST;

So samplerA specifies a sampler that uses normalized coordinates, the repeat addressing mode and a nearest filter. iconique, no notes 👑

---

📖 SPECIFICATION 📖

OpenCL Specification[1]

---

👀 SEE ALSO 👀

otherDataTypes(3clc), imageFunctions(3clc), classDiagram(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 condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

---

📌 NOTES 📌

the footnotes, we did not forget them:

1. OpenCL Specification — page 292, section 6.12.14.1 - Samplers

---

and that's a wrap on SAMPLER_T(3clc) 💖 brought to you by The Khronos Group, dated 01/14/2021, and yes the page really is called SAMPLER_T(3clc) in the corner like a little signature. go forth and sample responsibly, bestie, mwah 🎀✨🦋